Tools

We kept the base toolset small: a handful of native tools, gated by permissions. Anything beyond that is something you add deliberately, either a skill plus a CLI or an MCP server. Every tool an agent carries is more attack surface, more context and one more way for a small model to get confused, so the framework ships with very little and lets you add the rest.

Native tools

Tools follow permissions. A native tool exists for the agent only when the permissions block grants what it needs. This means that no unused tool schema takes up context, and there is nothing sitting there to misuse:

An agent with no permissions: block gets current_time, plus read_skill if it has skills. Nothing else.

MCP servers

Use an MCP server when a good one exists and is worth the context cost:

tools:
  mcp:
    - name: github
      command: ["docker", "run", "-i", "ghcr.io/github/github-mcp-server"]  # stdio
      env:
        GITHUB_TOKEN: ${GITHUB_TOKEN}     # scoped: the server sees only this
      include: [create_issue, update_issue, search_issues]
    - name: internal
      url: https://mcp.internal.example.com/mcp                             # or HTTP

• Tools are namespaced mcp__github__create_issue in the loop and the audit trail.
• We strongly recommend include:. A 40-tool server puts 40 schemas into a small model's context; expose the three you actually need. include: is also the permission surface for MCP: a tool you didn't include does not exist for the agent.
• readonly: true on a server exposes only tools whose readOnlyHint annotation marks them read-only, which is a good fit when the job only reads. The hint is self-reported by the server, so treat this as a guard against wiring write tools into a read-only job; the trust decision is still whether to declare the server at all.
• Every MCP call is recorded in the audit trail with the tool name and whether it succeeded, alongside the run's permission decisions.
• Each server sees only its own env: block (values may be ${VAR} references); the agent's own environment stays private.
• Results are truncated at 8k chars; servers connect at startup and close on shutdown.

The gh-issues-mcp example is a complete deployment of this block: the Dockerfile installs the GitHub MCP server binary and the agent file exposes five of its tools. Its sibling gh-issues-cli does the same job with the gh CLI and a skill, so the two read as a side-by-side comparison.

Tool search

include: keeps context lean by hand; tool search does the same thing automatically. When the total toolset grows past 10, MCP tool schemas stay out of context entirely. The model gets a single search_tools schema, and it activates the tools the task needs while the run is underway:

tools:
  search: auto   # auto (default) | on | off

• auto - defer MCP tools when the agent carries more than 10 tools in total; below that, everything loads normally.
• on / off - always or never defer, regardless of count.

A search is a keyword match against tool names and descriptions; the top matches (up to five, with a relevance cutoff) become callable for the rest of the run. Native and skill tools always load, since they are small and framework-owned. include: and search compose: include: filters the server down to what the agent should ever see, and search decides when it sees it.

Custom tools

tools.custom (TypeScript tool modules) is planned and hasn't landed yet; the config loader rejects the key loudly, so a config that relies on it fails immediately (#12). In the meantime, give the agent a CLI and a skill.