> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bumbleagi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Built-in tools, MCP integration, and extending the stack.

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                  |

### Social Broadcast

| 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](/architecture/autonomous-wake#sustained-wake-sessions). `end_turn` ends a single perceive round.

## Enabling and disabling

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

```yaml theme={null}
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](https://modelcontextprotocol.io) stdio servers. Their tools register dynamically at startup, prefixed with the server name so they stay distinct from native tools.

```yaml theme={null}
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](https://pypi.org/project/mcp-proxy/):

```yaml theme={null}
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:

```bash theme={null}
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](/deployment/hybrid-railway#execution) for details on execution safety and configuration.