Tools

Tools are how the entity interacts with the world — not “services for the user,” but senses and reach. The entity decides when and how to use tools based on conversation context. Both reflex and deliberate reasoning profiles share the same tool registry, and the agent loop executes multiple tool calls in parallel when the model emits them in one step. When presence.tool_activity is enabled, tool use surfaces in chat with short status lines so the user can see what the entity is doing.

How the entity uses tools

Tools are registered at startup based on YAML configuration and installed extras. During each turn, the perceive pipeline routes to either reflex or deliberate reasoning. Both profiles have access to the full tool registry — the difference is token budget and thinking mode. The bounded agent loop runs tool calls, inspects results, and decides whether to continue (more tools needed), produce a final reply, or report a failure. A context-aware nudge after each tool round tells the model which tools ran and whether they succeeded, referencing the user’s original question. A completion gate prevents thin acknowledgements from escaping as final replies. The entity can chain tools across multiple rounds. For example, a question about current weather might trigger get_weather, while a research question might chain search_web into fetch_url into a synthesized reply. The maximum number of tool rounds per turn is controlled by cognition.tool_continuation_rounds (default 21).

Complete tool reference

Every built-in tool, its harness configuration key, and default state. Tools marked “always on” have no enabled gate — they register whenever the harness starts. Others are toggled via tools.<key>.enabled in configs/default.yaml or per-entity YAML.

Web and search

Tool	Harness key	Default	Description
`search_web`	—	on	Web search (DuckDuckGo by default; optional Firecrawl)
`fetch_url`	—	on	Fetch and extract text from a URL

Shell and processes

Tool	Harness key	Default	Description
`run_command`	`shell`	on	Run a shell command (denylist + timeout)
`run_background`	`shell`	on	Start a background shell command
`check_process`	`shell`	on	Inspect a tracked background job
`kill_process`	`shell`	on	Stop a background job

Filesystem

Tool	Harness key	Default	Description
`read_file`	—	on	Read a file under the execution workspace
`write_file`	—	on	Write or create a file
`append_file`	—	on	Append to an allowed file path
`list_directory`	—	on	List files under the workspace directory
`search_files`	—	on	Search by pattern under the workspace
`apply_patch`	—	on	Apply a unified diff hunks to workspace files (atomic multi-file edits)
`send_file`	—	on	Send a workspace file to the active chat (Telegram/Discord) with optional caption

Episodic memory

Tool	Harness key	Default	Description
`search_past_conversations`	—	on	Semantic search over episodic summaries (natural-language query; embedding-backed)

Session planning

Tool	Harness key	Default	Description
`todo_add`	—	on	Add an item to the in-session todo list
`todo_list`	—	on	List pending session todos
`todo_complete`	—	on	Mark a session todo done
`todo_remove`	—	on	Remove a session todo

Human-in-the-loop

Tool	Harness key	Default	Description
`ask_user`	—	on	Ask a short clarifying question and wait for a reply (structured follow-up)
`delegate_task`	—	on	Run a bounded sub-task with a reduced tool subset (delegation platform)

Code execution

Tool	Harness key	Default	Description
`execute_python`	`code`	on	Run Python in a sandboxed helper
`execute_javascript`	`code`	on	Run JavaScript in a sandboxed helper
`code_task_session`	`code`	on	Structured multi-step code work inside an isolated session (files, tools, history)

Knowledge and journal

Tool	Harness key	Default	Description
`update_knowledge`	—	on	Add, update, or remove `knowledge.md` sections
`read_journal`	`journal`	on	Read recent private journal entries
`write_journal`	`journal`	on	Append a private journal entry

Voice

Tool	Harness key	Default	Description
`speak`	`voice`	on	Send a TTS voice note to the active chat
`get_tts_voice`	`voice`	on	Current Edge-TTS voice ID
`set_tts_voice`	`voice`	on	Set Edge-TTS voice for this process
`list_tts_voices`	`voice`	on	List available Edge-TTS voices (filterable)

Messaging

Tool	Harness key	Default	Description
`send_dm`	`messaging`	on	DM on Telegram or Discord (confirmation flow)
`send_message_to`	`messaging`	on	Message a platform target or resolved person
`list_known_contacts`	`messaging`	on	Known people and routes from prior interactions

Automations

Tool	Harness key	Default	Description
`create_automation`	`automations`	on	Create a scheduled routine (cron, prompt, optional delivery)
`edit_automation`	`automations`	on	Edit routine fields
`delete_automation`	`automations`	on	Remove a routine
`list_automations`	`automations`	on	List all routines
`toggle_automation`	`automations`	on	Enable or disable a routine
`run_automation_now`	`automations`	on	Trigger a routine immediately

Reminders

Tool	Harness key	Default	Description
`set_reminder`	`reminders`	on	Schedule a reminder (DB + APScheduler)
`list_reminders`	`reminders`	on	List active reminders
`cancel_reminder`	`reminders`	on	Cancel a scheduled reminder

Browser (optional)

Tool	Harness key	Default	Description
`browser_navigate`	`browser`	off	Open a URL in the automated browser
`browser_click`	`browser`	off	Click an element (Playwright)
`browser_type`	`browser`	off	Type into the page
`browser_screenshot`	`browser`	off	Screenshot the current page

Remote desktop sessions (optional)

Tool	Harness key	Default	Description
`desktop_session_click`	`remote_session`	off	Click at screen coordinates
`desktop_session_keypress`	`remote_session`	off	Send key presses or shortcuts
`desktop_session_open_url`	`remote_session`	off	Open a URL inside the remote desktop
`desktop_session_status`	`remote_session`	off	Inspect the active session
`desktop_session_stop`	`remote_session`	off	Stop the active session
`desktop_session_type`	`remote_session`	off	Type text into the session
`desktop_session_view`	`remote_session`	off	Capture the current frame

Image generation (optional)

Tool	Harness key	Default	Description
`generate_image`	`imagegen`	off	Text-to-image (Fal or local SD WebUI-compatible)

IoT / Environment

Tool	Harness key	Default	Description
`get_ha_state`	`iot`	on	Check the current state of a Home Assistant entity
`set_ha_state`	`iot`	on	Call a Home Assistant service to change state

Observation

Tool	Harness key	Default	Description
`tail_file`	`observation`	on	Read the last N lines of a file (useful for fast log monitoring)
`check_file_modified`	`observation`	on	Check the last modified time and size of a file

Tool	Harness key	Default	Description
`post_mastodon_status`	`social`	on	Post a status update to a configured Mastodon account
`read_mastodon_timeline`	`social`	on	Read the latest posts from the Mastodon home timeline
`post_zweet_status`	`social`	on	Post a zweet (status update/tweet) to an X (Twitter) account

Local RAG / Indexing

Tool	Harness key	Default	Description
`index_text`	`rag`	on	Index a block of text into a local SQLite vector DB using Ollama embeddings
`search_collection`	`rag`	on	Semantically search a specific RAG collection for information

Information

Tool	Harness key	Default	Description
`get_current_time`	—	on	Current local date and time (timezone-aware)
`get_weather`	`weather`	on	Weather for a location
`get_news`	`news`	on	News headlines by topic
`get_system_info`	`system`	on	Host and system snapshot

Content

Tool	Harness key	Default	Description
`read_pdf`	`pdf`	on	Extract text from a PDF path
`read_reddit`	`reddit`	on	Browse a subreddit
`read_reddit_post`	`reddit`	on	Read a Reddit post thread
`read_wikipedia`	`wikipedia`	on	Wikipedia summary or full article
`get_youtube_transcript`	`youtube`	on	Transcript for a YouTube video
`search_youtube`	`youtube`	on	Search YouTube

Discovery

Tool	Harness key	Default	Description
`search_tools`	—	on	Search registered tools by keyword
`describe_tool`	—	on	Full name, description, and JSON Schema for one tool

Agency and flow control

Tool	Harness key	Default	Description
`think`	—	on	Private scratchpad thought (not shown to users)
`say`	—	on	Send a message mid-turn to the active chat
`end_turn`	—	on	End the current turn (mood / parting thought optional)
`end_wake_session`	—	on	During sustained autonomous wake, signal no further rounds after this perceive completes
`wait`	—	on	Pause briefly before the next action
`observe`	—	on	Fetch recent messages from a channel (where supported)
`compact_context`	—	on	Request proactive context compaction

end_wake_session only affects multi-round autonomous wake. end_turn ends a single perceive round.

Enabling and disabling

Each tool category has an enabled flag in configs/default.yaml:

tools:
  shell:
    enabled: true
    deny: ["rm -rf /", "sudo rm", "shutdown"]
    timeout: 30
  browser:
    enabled: false
  voice:
    enabled: true
  imagegen:
    enabled: false

Override per entity with a top-level tools: block in entity YAML.

Runtime discovery

The live registry depends on YAML toggles, installed extras, and any MCP servers attached. The entity can inspect its own capabilities at runtime:

search_tools — find tools by keyword
describe_tool — get the full JSON Schema for a specific tool

MCP

Attach external tools via Model Context Protocol stdio servers. Their tools register dynamically at startup, prefixed with the server name so they stay distinct from native tools.

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

Multiple servers and reconnects are supported. See configs/entities/example.yaml for a commented template.

Zapier MCP

Zapier exposes MCP over Streamable HTTP, but Bumblebee only spawns stdio servers today. Bridge with mcp-proxy:

mcp_servers:
  zapier:
    command: mcp-proxy
    args: ["--transport", "streamablehttp", "https://actions.zapier.com/mcp/YOUR_ID/sse"]
    env:
      API_ACCESS_TOKEN: "your_zapier_secret"

Optional extras

Some tools require additional Python packages:

pip install 'bumblebee[voice]'      # Edge-TTS voice notes
pip install 'bumblebee[browser]'    # Playwright browser tools
pip install 'bumblebee[imagegen]'   # fal image generation
pip install 'bumblebee[pdf]'        # PDF reading
pip install 'bumblebee[youtube]'    # YouTube transcripts
pip install 'bumblebee[full]'       # everything

Execution layer

Shell, filesystem, and code tools run via the execution layer. Where they execute depends on your deployment:

Local — same machine as Bumblebee
Railway — inside the container (RAILWAY_ENVIRONMENT is set)
RPC — remote execution host via BUMBLEBEE_EXECUTION_RPC_URL

See Hybrid deployment for details on execution safety and configuration.

Getting started

Guides

Deployment

Agents

Build

How the entity uses tools

Complete tool reference

Web and search

Shell and processes

Filesystem

Episodic memory

Session planning

Human-in-the-loop

Code execution

Knowledge and journal

Voice

Messaging

Automations

Reminders

Browser (optional)

Remote desktop sessions (optional)

Image generation (optional)

IoT / Environment

Observation

Local RAG / Indexing

Information

Content

Discovery

Agency and flow control

Enabling and disabling

Runtime discovery

MCP

Zapier MCP

Optional extras

Execution layer

​How the entity uses tools

​Complete tool reference

​Web and search

​Shell and processes

​Filesystem

​Episodic memory

​Session planning

​Human-in-the-loop

​Code execution

​Knowledge and journal

​Voice

​Messaging

​Automations

​Reminders

​Browser (optional)

​Remote desktop sessions (optional)

​Image generation (optional)

​IoT / Environment

​Observation

​Social Broadcast

​Local RAG / Indexing

​Information

​Content

​Discovery

​Agency and flow control

​Enabling and disabling

​Runtime discovery

​MCP

​Zapier MCP

​Optional extras

​Execution layer

How the entity uses tools

Complete tool reference

Web and search

Shell and processes

Filesystem

Episodic memory

Session planning

Human-in-the-loop

Code execution

Knowledge and journal

Voice

Messaging

Automations

Reminders

Browser (optional)

Remote desktop sessions (optional)

Image generation (optional)

IoT / Environment

Observation

Social Broadcast

Local RAG / Indexing

Information

Content

Discovery

Agency and flow control

Enabling and disabling

Runtime discovery

MCP

Zapier MCP

Optional extras

Execution layer