<!-- SPDX-License-Identifier: Apache-2.0 -->

# Tool configuration

`config/tools.toml` enables built-in, plugin, and configured MCP tools for an agent. It is required.

Each tool is enabled with a boolean. Unknown tool names are rejected during `dry-run` and startup, even when their value is `false`.

```toml
edit = true
read = true
respond = true
exec = false
```

## The exec tool

The `exec` tool runs commands through the agent sandbox and can be a boolean or a table. `exec = true` enables execution with the defaults below; `exec = false` disables it. The binary entrypoint list belongs in [`sandbox.toml`](sandbox.md#bubblewrap), not in this table.

```toml
[exec]
enabled = true
timeout = 60000
inline = true
inlineThresholdBytes = 16384
outputDir = "/workspace/.exec-output"
previewHead = 20
previewTail = 20
maxPreviewLineLength = 1000
hostEnvPassthrough = []
```

| Field                  | Default                   | Description                                                                                                                                        |
| ---------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`              | `false`                   | Whether execution is enabled.                                                                                                                      |
| `timeout`              | `60000`                   | Command timeout in milliseconds.                                                                                                                   |
| `inline`               | `true`                    | Whether short output is returned inline.                                                                                                           |
| `inlineThresholdBytes` | `16384`                   | Inline output threshold in bytes.                                                                                                                  |
| `outputDir`            | `/workspace/.exec-output` | Output directory inside the sandbox.                                                                                                               |
| `previewHead`          | `20`                      | Preview lines from the start of file output.                                                                                                       |
| `previewTail`          | `20`                      | Preview lines from the end of file output.                                                                                                         |
| `maxPreviewLineLength` | `1000`                    | Maximum characters kept from any single preview line. Long lines are elided with a marker so minified or binary-ish output cannot flood the model. |
| `hostEnvPassthrough`   | `[]`                      | Host environment variables copied into the sandbox.                                                                                                |

The command timeout remains active while writing input and draining stdout/stderr, including after the command's parent process exits. A background child that inherits output handles cannot make output collection wait indefinitely. A timeout reports failure and retains stdout captured before the deadline; cancellation of the calling turn propagates as cancellation rather than a successful command result.

If writing captured output fails because of an I/O or access error, `exec` returns `fallbackInline = true` with `stdout` and `stderr` bounded by `previewHead`, `previewTail`, and `maxPreviewLineLength`, even when `inline = false`. `truncated` indicates whether content was omitted; the original byte counts and command exit code are retained. This fallback does not return output paths, and omitted content cannot be recovered from the tool result.

## Built-in tools

| Tool                   | Purpose                                              |
| ---------------------- | ---------------------------------------------------- |
| `respond`              | Send a message to the current or another channel.    |
| `no-response`          | End a turn without sending a message.                |
| `edit`                 | Targeted replacements in a file with fuzzy matching. |
| `read`                 | Read a file; large files return a section outline.   |
| `read-sections`        | Add sections of an opened file to context.           |
| `open-file`            | Pin a file or sections to session context.           |
| `close-file`           | Unpin a file from context.                           |
| `read-skill`           | Load a skill document.                               |
| `list-dir`             | List a sandbox directory.                            |
| `write`                | Create or overwrite a sandbox file.                  |
| `exec`                 | Run a command in the sandbox.                        |
| `read-history`         | Fetch message history from the current channel.      |
| `read-session`         | Read a persisted session's history.                  |
| `list-sessions`        | List persisted sessions.                             |
| `query-sessions`       | Search persisted session contents.                   |
| `download-attachments` | Download channel attachments into the sandbox.       |
| `react`                | Add an emoji reaction to a message.                  |
| `schedule`             | Schedule a one-shot task for a future time.          |
| `invoke`               | Queue a turn in another existing session.            |
| `session-info`         | Describe the current session.                        |
| `prune-boundaries`     | Commit a topic compaction range.                     |

`edit` is the built-in targeted editing tool. CireilClaw 2.0.0 removes `str-replace` and migrates existing tool configuration to `edit`, preserving whether editing was enabled. Update custom tool calls and agent instructions to use `edit`; see the [editing tool migration](../operations/upgrades.md#v200-editing-tool-migration) for the configuration and argument changes.

For block files and skill `SKILL.md` files, `edit` preserves frontmatter and searches only the body. A `dryRun` preview returns an `applyId`; apply it with the same `path` and `apply` set to that ID. Application checks that the complete original file, including frontmatter, is unchanged. Preview and apply return the same body-only patch, without presenting preserved frontmatter as additions.

`open-file` and `read-sections` use IDs from the file outline. Markdown section IDs use link labels rather than link destinations. Setext headings (`===` or `---` underlines) are supported when the file has no ATX headings (`#` prefixes). A pinned Markdown section includes its child headings and stops before the next heading at the same or a higher level.

`session-info` returns `platform` and `session_id` for Discord, Matrix, TUI, internal, and remote sessions. Both scheduled internal sessions and named persistent internal sessions report `platform = "internal"`; adapter-owned sessions report `platform = "remote"`. Platform-specific fields remain limited to the relevant session type.

`read` rejects text files larger than 262144 bytes (256 KiB) with an error before returning content or generating an outline. This limit also applies when `raw` is enabled. Use sandboxed commands through `exec`, when enabled and permitted, to extract a smaller excerpt into a separate file, then read that file. Image and video reads use their existing media handling rather than this text limit.

Plugin tools must also be enabled here by name; see [Plugins](plugins.md).

`read-session` limits each rendered thinking block to 200 characters and appends `… (truncated)` when more content remains.

## HTTP MCP tools

The runtime supports MCP tool discovery and calls over Streamable HTTP, including JSON and SSE responses to HTTP requests. It does not launch stdio servers, support legacy HTTP+SSE transport, or provide MCP resources, prompts, sampling, elicitation, or OAuth login.

1. Create `agents/<slug>/config/mcp.toml` under your runtime root:

   ```toml
   [servers.metacog]
   url = "https://metacog.inanna-c38.workers.dev/mcp"
   timeout = 60000
   ```

2. Enable the tools you want in that agent's `config/tools.toml`:

   ```toml
   mcp__metacog__feel = true
   ```

3. Restart the runtime. Startup discovers tools and their input schemas from the configured endpoints. `dry-run` also connects and discovers tools to validate their names, but does not call them.

Each server entry requires an HTTP or HTTPS `url`. `timeout` is a positive deadline in milliseconds, defaulting to `60000`; it covers connection and discovery together, and separately each tool call. Cancellation of the calling turn propagates to MCP. A timeout does not prove that the remote operation had no effect.

Static authentication and other request headers can be configured per server:

```toml
[servers.private]
url = "https://example.com/mcp"

[servers.private.headers]
Authorization = "<your server's authorization header>"
```

Protect this file as a credential when it contains secrets. Transport-owned headers cannot be overridden, and HTTP redirects are rejected instead of forwarding credentials to a different endpoint.

Local tool names are `mcp__<server>__<tool>`. Server names allow ASCII letters, digits, hyphens, and underscores, but not double underscores. Remote tool-name characters other than ASCII letters, digits, hyphens, and underscores become underscores in the local name; calls still use the original remote name. Collisions and local names longer than 64 characters fail startup rather than overwriting another tool. Tool descriptions include the server's usage instructions. The connected server's advertised tools and schemas, not its repository README, determine what is available.

MCP tool results preserve the server's content blocks and structured content as JSON, including non-text blocks; this does not add native image or audio rendering. Remote `isError` results become `success = false` for the runtime's ordinary failure handling. Protocol and network failures use the existing tool error path.

Only configure servers you trust with the inputs passed to their tools. MCP calls run from the host to explicitly configured endpoints, not inside the command sandbox. Enabling a tool grants the agent access to its remote effects; the runtime does not sandbox the remote server. Remote-session grants still filter and authorize enabled MCP tools as harness tools.

Each agent owns its own connections. MCP connection/session state is memory-only and recreated at startup; no agent state files are written. A configured server that cannot initialize or list tools prevents startup. Connections and discovered definitions remain fixed until restart, including when the server advertises a tool-list change.

## Reload

Changes to `tools.toml` are picked up by the running runtime and apply to subsequent turns. An in-progress turn keeps the tool set it started with.

Changes to `mcp.toml`, authentication headers, or the server's discovered tool definitions require a full runtime restart. Enablement changes for already discovered MCP tools in `tools.toml` use the normal subsequent-turn reload boundary.