Tool Configuration

Complete reference for configuring built-in tools, MCP tools, and Docker-based tools.

Built-in Tools

Built-in tools are included with docker-agent and require no external dependencies. Add them to your agent's toolsets list by type. Each tool's dedicated page covers its full configuration options, available operations, and examples.

Example:

toolsets:
  - type: filesystem
  - type: shell
  - type: think
  - type: todo
  - type: memory
    path: ./dev.db

MCP Tools

Extend agents with external tools via the Model Context Protocol. For a standalone overview of the mcp toolset see the MCP tool page.

Tip

Reusable MCP definitions

Repeated MCP server definitions can be hoisted into the top-level mcps: section and referenced by name with {type: mcp, ref: <name>}. See Reusable MCP Servers.

Docker MCP (Recommended)

Run MCP servers as secure Docker containers via the MCP Gateway:

toolsets:
  - type: mcp
    ref: docker:duckduckgo # web search
  - type: mcp
    ref: docker:github-official # GitHub integration

Browse available tools at the Docker MCP Catalog.

Local MCP (stdio)

Run MCP servers as local processes communicating over stdin/stdout:

toolsets:
  - type: mcp
    command: python
    args: ["-m", "mcp_server"]
    tools: ["search", "fetch"]
    env:
      API_KEY: value

Remote MCP (Streamable HTTP / SSE)

Connect to MCP servers over the network:

toolsets:
  - type: mcp
    remote:
      url: "https://mcp-server.example.com"
      transport_type: "streamable"
      headers:
        Authorization: "Bearer your-token"
    # Optional: allow OAuth helper requests to reach private/internal IPs.
    allow_private_ips: true
    tools: ["search_web", "fetch_url"]

Auto-Installing Tools

When configuring MCP or LSP tools that require a binary command, docker agent can automatically download and install the command if it's not already available on your system. This uses the aqua registry — a curated index of CLI tool packages.

How It Works

1. When a toolset with a command is loaded, docker agent checks if the command is available in your PATH
2. If not found, it checks the docker agent tools directory (~/.cagent/tools/bin/)
3. If still not found, it looks up the command in the aqua registry and installs it automatically

Explicit Package Reference

Use the version property to specify exactly which package to install:

toolsets:
  - type: mcp
    command: gopls
    version: "golang/tools@v0.21.0"
    args: ["mcp"]
  - type: lsp
    command: rust-analyzer
    version: "rust-lang/rust-analyzer@2024-01-01"
    file_types: [".rs"]

The format is owner/repo or owner/repo@version. When a version is omitted, the latest release is used.

Automatic Detection

If the version property is not set, docker agent tries to auto-detect the package from the command name by searching the aqua registry:

toolsets:
  - type: mcp
    command: gopls  # auto-detected as golang/tools
    args: ["mcp"]

Checksum Verification

Where the aqua registry includes a checksum manifest, downloaded binaries are verified against it before installation. Verification behaviour depends on the checksum type advertised:

• Strong checksums (sha256, sha512, etc.) — verified before the binary is installed. If the downloaded archive does not match, the install is aborted and an error is returned (fails closed).
• Unsupported or weak checksum types (e.g. md5, sha1) — skipped with a warning; installation proceeds without verification.
• No manifest — if no checksum is advertised in the registry entry, the binary is installed without verification.

version_overrides Resolution

The auto-installer correctly resolves version_overrides entries in the aqua registry. Many common tools (for example, fzf) keep their package configuration — including download URLs and checksums — under version_overrides rather than at the top level of their registry entry. These tools previously failed to install silently; they are now handled correctly.

Disabling Auto-Install

Per toolset — set version to "false" or "off":

toolsets:
  - type: mcp
    command: my-custom-server
    version: "false"

Globally — set the DOCKER_AGENT_AUTO_INSTALL environment variable:

export DOCKER_AGENT_AUTO_INSTALL=false

Environment Variables

Installed binaries are placed in ~/.cagent/tools/bin/ and cached so they are only downloaded once.

Tip

Auto-install supports both Go packages (via go install) and GitHub release binaries (via archive download). The aqua registry metadata determines which method is used.

Toolset Lifecycle

Long-running toolsets — local MCP servers (stdio), remote MCP servers (Streamable HTTP / SSE), and LSP servers — are managed by a single supervisor that can auto-reconnect them when they crash, time out, or drop their session. The lifecycle block on the toolset lets you tune that supervisor per toolset. It applies to every type: mcp and type: lsp toolset.

The simplest knob is profile, which picks a preset:

toolsets:
  - type: mcp
    ref: docker:duckduckgo
    lifecycle:
      profile: resilient   # default; shown here for clarity

  - type: lsp
    command: gopls
    file_types: [".go"]
    lifecycle:
      profile: strict

  - type: mcp
    ref: docker:openbnb-airbnb
    lifecycle:
      profile: best-effort

Tuning the defaults

Any field set on lifecycle overrides the profile preset, so you can mix-and-match: pick a profile and only override the knobs you care about.

toolsets:
  - type: mcp
    command: ["docker", "mcp", "gateway"]
    lifecycle:
      profile: resilient
      max_restarts: 10        # keep trying longer than the default of 5
      backoff:
        initial: 500ms
        max: 1m
        multiplier: 2
        jitter: 0.2           # 20% random offset to avoid thundering-herd retries

Note

required and startup_timeout are not yet enforced

The schema validates these fields and the supervisor stores them, but no code path acts on them yet. They are documented now so config files written today keep working when the planned eager-startup phase lands. Picking the strict profile is forward-compatible — it will start enforcing required=true automatically.

Inspecting and restarting toolsets at runtime

The TUI exposes the supervisor through two slash commands:

• /tools — the unified tools dialog. Its top section lists every toolset on the current agent with its lifecycle state (Stopped, Starting, Ready, Degraded, Restarting, Failed), restart count, and last error; its bottom section lists every tool the agent can call, grouped by category. Use this to answer both "what can the agent do?" and "is anything degraded?" with one command.
• /toolset-restart <name> — force the supervisor to reconnect the named toolset. Useful after completing OAuth, when a remote MCP server has been redeployed, or when an LSP like gopls is stuck.

See the TUI reference for the full list of slash commands.

See examples/lifecycle.yaml for a complete lifecycle configuration example.

TOON-Encoded Tool Outputs

Many MCP servers return verbose JSON responses that consume a lot of context budget. The toon field on a toolset transparently re-encodes matching tools' JSON output as TOON — a compact, model-friendly key/value format — before the result is shown to the model.

toolsets:
  - type: mcp
    ref: docker:github-official
    toon: ".*"          # toonify every tool from this MCP server
  - type: mcp
    command: my-server
    toon: "list_.*,get_.*" # only toonify list_/get_ tools

When a tool's output is not valid JSON, it is returned unchanged — TOON encoding is best-effort and never breaks tools that emit plain text.

Note

When to use TOON

TOON typically yields 30-60% smaller payloads than equivalent JSON for MCP tools that return arrays of records (issue lists, search results, file listings, …). It works best when the schema is regular; one-off responses with deeply nested or heterogeneous shapes may benefit less.

Per-Toolset Model Routing

The model field on a toolset overrides which LLM is invoked for the next turn after a tool from that toolset returns — letting you process simple tool results (file reads, knowledge-base lookups, shell stdout) with a cheaper or faster model while keeping the agent's primary model for reasoning.

models:
  primary:
    provider: anthropic
    model: claude-sonnet-4-5
  fast:
    provider: anthropic
    model: claude-haiku-4-5

agents:
  root:
    model: primary
    toolsets:
      - type: filesystem
        model: fast            # process file reads with the fast model
      - type: shell
        model: fast            # ditto for shell stdout
      - type: mcp
        ref: docker:github-official
        model: openai/gpt-4o-mini  # inline provider/model also works

When multiple tool calls in a single turn come from toolsets with different model overrides, the runtime picks the override of the first tool call that has one set. See examples/per_tool_model_routing.yaml for a complete configuration.

Tool Filtering

Toolsets may expose many tools. Use the tools property to whitelist only the ones your agent needs. This works for any toolset type — not just MCP:

toolsets:
  - type: mcp
    ref: docker:github-official
    tools: ["list_issues", "create_issue", "get_pull_request"]
  - type: filesystem
    tools: ["read_file", "search_files_content"]
  - type: shell
    tools: ["shell"]

Tip

Filtering tools improves agent performance — fewer tools means less confusion for the model about which tool to use.

Tool Instructions

Add context-specific instructions that get injected when a toolset is loaded:

toolsets:
  - type: mcp
    ref: docker:github-official
    instruction: |
      Use these tools to manage GitHub issues.
      Always check for existing issues before creating new ones.
      Label new issues with 'triage' by default.

By default, the instruction: field replaces the toolset's built-in instructions (if any). To keep the built-in guidance and add your own rules on top, include the {ORIGINAL_INSTRUCTIONS} placeholder anywhere in your instruction text. At runtime it expands to the toolset's default instructions:

toolsets:
  # Enrich: keep built-in instructions, then add your own rules
  - type: filesystem
    instruction: |
      {ORIGINAL_INSTRUCTIONS}

      ## Project-specific rules
      - Never modify files outside the `src/` directory.
      - Always create a backup before overwriting a file.

  # Enrich: prepend your rules before the built-in instructions
  - type: shell
    instruction: |
      Important: only run commands inside the project root.
      {ORIGINAL_INSTRUCTIONS}

  # Replace: omit the placeholder to discard built-in instructions entirely
  - type: mcp
    ref: docker:github-official
    instruction: |
      Only read GitHub issues. Never create, edit, or close anything.

Three patterns at a glance:

See examples/toolset_instructions.yaml for a complete example.

Deferred Tool Loading

Load tools on-demand to speed up agent startup. When a toolset is deferred, its tools are registered lazily — the tool server process is not started until the agent first calls one of its tools. This is useful for large toolsets (e.g., an MCP server with hundreds of tools) where startup time matters.

toolsets:
  - type: mcp
    ref: docker:github-official
    defer: true
  - type: mcp
    ref: docker:slack
    defer: true
  - type: filesystem

Or defer specific tools within a toolset:

toolsets:
  - type: mcp
    ref: docker:github-official
    defer:
      - "list_issues"
      - "search_repos"

When defer is a list of tool names, only those specific tools are deferred; all other tools in the toolset load eagerly. Setting defer: true defers the entire toolset.

See examples/deferred.yaml for a complete example.

Combined Example

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Full-featured developer assistant
    instruction: You are an expert developer.
    toolsets:
      # Built-in tools
      - type: filesystem
      - type: shell
      - type: think
      - type: todo
      - type: memory
        path: ./dev.db
      - type: user_prompt
      # LSP for code intelligence
      - type: lsp
        command: gopls
        file_types: [".go"]
      # Custom scripts
      - type: script
        shell:
          run_tests:
            description: Run the test suite
            cmd: task test
          lint:
            description: Run the linter
            cmd: task lint
      # Custom API tool
      - type: api
        api_config:
          name: get_status
          method: GET
          endpoint: "https://api.example.com/status"
          instruction: Check service health
      # Docker MCP tools
      - type: mcp
        ref: docker:github-official
        tools: ["list_issues", "create_issue"]
      - type: mcp
        ref: docker:duckduckgo
      # Remote MCP
      - type: mcp
        remote:
          url: "https://internal-api.example.com/mcp"
          transport_type: "streamable"
          headers:
            Authorization: "Bearer ${env.INTERNAL_TOKEN}"

Warning

Toolset Order Matters

If multiple toolsets provide a tool with the same name, the first one wins. Order your toolsets intentionally.