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.

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, not in this table.

[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 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.

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:

   [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:

   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:

[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.