Tool Configuration

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

Built-in Tools

Built-in tools are included with cagent and require no external dependencies. Add them to your agent’s toolsets list.

Filesystem

Read, write, list, search, and navigate files in the working directory.

toolsets:
  - type: filesystem
    ignore_vcs: false # Optional: ignore .gitignore files
    post_edit: # Optional: run commands after file edits
      - path: "*.go"
        cmd: "gofmt -w ${file}"

Operation	Description
`read_file`	Read the complete contents of a file
`read_multiple_files`	Read several files in one call (more efficient than multiple `read_file`)
`write_file`	Create or overwrite a file with new content
`edit_file`	Make line-based edits (find-and-replace) in an existing file
`list_directory`	List files and directories at a given path
`directory_tree`	Recursive tree view of a directory
`search_files_content`	Search for text or regex patterns across files

Property	Type	Default	Description
`ignore_vcs`	boolean	`false`	When `true`, ignores `.gitignore` patterns and includes all files
`post_edit`	array	`[]`	Commands to run after editing files matching a path pattern
`post_edit[].path`	string	—	Glob pattern for files (e.g., `.go`, `src//.ts`)
`post_edit[].cmd`	string	—	Command to run (use `${file}` for the edited file path)

💡 Tip

The filesystem tool resolves paths relative to the working directory. Agents can also use absolute paths.

Shell

Execute arbitrary shell commands. Each call runs in a fresh, isolated shell session — no state persists between calls.

toolsets:
  - type: shell
    env: # Optional: environment variables
      MY_VAR: "value"
      PATH: "${PATH}:/custom/bin"

The agent has access to the full system shell and environment variables. Commands have a default 30-second timeout. Requires user confirmation unless --yolo is used.

Property	Type	Description
`env`	object	Environment variables to set for all shell commands
`sandbox`	object	Run commands in a Docker container. See Sandbox Mode.

Think

Step-by-step reasoning scratchpad. The agent writes its thoughts without producing visible output — ideal for planning, decomposition, and decision-making.

toolsets:
  - type: think

No configuration options. No side effects. Recommended for all agents — adds minimal overhead while improving reasoning quality.

Todo

Task list management. Agents can create, update, and track tasks with status (pending, in-progress, completed).

toolsets:
  - type: todo
    shared: false # Optional: share todos across agents

Operation	Description
`create_todo`	Create a new task
`create_todos`	Create multiple tasks at once
`update_todos`	Update status of one or more tasks
`list_todos`	List all current tasks with their status

Property	Type	Default	Description
`shared`	boolean	`false`	When `true`, todos are shared across all agents in a multi-agent config

Memory

Persistent key-value storage backed by SQLite. Data survives across sessions, letting agents remember context, user preferences, and past decisions.

toolsets:
  - type: memory
    path: ./agent_memory.db # optional: custom database path

Property	Type	Default	Description
`path`	string	automatic	Path to the SQLite database file. If omitted, uses a default location.

Fetch

Make HTTP requests to external APIs and web services.

toolsets:
  - type: fetch
    timeout: 30 # Optional: request timeout in seconds

Supports GET, POST, PUT, DELETE, and other HTTP methods. The agent can set headers, send request bodies, and receive response data. Useful for calling REST APIs, reading web pages, and downloading content.

Property	Type	Default	Description
`timeout`	int	`30`	Request timeout in seconds

Script

Define custom shell scripts as named tools. Unlike the generic shell tool, scripts are predefined and can be given descriptive names — ideal for exposing safe, well-scoped operations.

Simple format:

toolsets:
  - type: script
    shell:
      run_tests:
        cmd: task test
        description: Run the project test suite
      lint:
        cmd: task lint
        description: Run the linter
      deploy:
        cmd: ./scripts/deploy.sh ${env}
        description: Deploy to an environment
        args:
          env:
            type: string
            enum: [staging, production]
        required: [env]

Property	Type	Description
`shell.<name>.cmd`	string	Shell command to execute (supports `${arg}` interpolation)
`shell.<name>.description`	string	Description shown to the model
`shell.<name>.args`	object	Parameter definitions (JSON Schema properties)
`shell.<name>.required`	array	Required parameter names
`shell.<name>.env`	object	Environment variables for this script
`shell.<name>.working_dir`	string	Working directory for script execution

Transfer Task

The transfer_task tool is automatically available when an agent has sub_agents. Allows delegating tasks to sub-agents. No configuration needed — it’s enabled implicitly.

LSP (Language Server Protocol)

Connect to language servers for code intelligence: go-to-definition, find references, diagnostics, and more.

toolsets:
  - type: lsp
    command: gopls
    args: []
    file_types: [".go"]

Property	Type	Description
`command`	string	LSP server executable command
`args`	array	Command-line arguments for the LSP server
`env`	object	Environment variables for the LSP process
`file_types`	array	File extensions this LSP handles

See LSP Tool for full documentation.

User Prompt

Ask users questions and collect interactive input during agent execution.

toolsets:
  - type: user_prompt

The agent can use this tool to ask questions, present choices, or collect information from the user. Supports JSON Schema for structured input validation.

See User Prompt Tool for full documentation.

API

Create custom tools that call HTTP APIs without writing code.

toolsets:
  - type: api
    name: get_weather
    method: GET
    endpoint: "https://api.weather.example/v1/current?city=${city}"
    instruction: Get current weather for a city
    args:
      city:
        type: string
        description: City name
    required: ["city"]
    headers:
      Authorization: "Bearer ${env.WEATHER_API_KEY}"

Property	Type	Description
`name`	string	Tool name
`method`	string	HTTP method: `GET` or `POST`
`endpoint`	string	URL with `${param}` interpolation
`args`	object	Parameter definitions
`required`	array	Required parameter names
`headers`	object	HTTP headers (supports `${env.VAR}`)

See API Tool for full documentation.

Handoff

Delegate tasks to remote agents via the A2A (Agent-to-Agent) protocol.

toolsets:
  - type: handoff
    name: research_agent
    description: Specialized research agent
    url: "http://localhost:8080/a2a"
    timeout: 5m

Property	Type	Description
`name`	string	Tool name for delegation
`description`	string	Description for the agent
`url`	string	A2A server endpoint URL
`timeout`	string	Request timeout (default: 5m)

See A2A Protocol for full documentation.

A2A (Agent-to-Agent)

Connect to remote agents via the A2A protocol. Similar to handoff but configured as a toolset.

toolsets:
  - type: a2a
    name: research_agent
    url: "http://localhost:8080/a2a"

Property	Type	Description
`name`	string	Tool name for the remote agent
`url`	string	A2A server endpoint URL

See A2A Protocol for full documentation.

MCP Tools

Extend agents with external tools via the Model Context Protocol.

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
  - type: mcp
    ref: docker:fetch # HTTP fetching

Browse available tools at the Docker MCP Catalog.

Property	Type	Description
`ref`	string	Docker MCP reference (`docker:name`)
`tools`	array	Optional: only expose these tools
`instruction`	string	Custom instructions injected into the agent’s context
`config`	any	MCP server-specific configuration (passed during initialization)

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"] # optional: whitelist specific tools
    env:
      - "API_KEY=value"
    env_file:
      - .env

Property	Type	Description
`command`	string	Command to execute the MCP server
`args`	array	Command arguments
`tools`	array	Optional: only expose these tools
`env`	array	Environment variables (`"KEY=value"` format)
`env_file`	array	Files to load environment variables from
`instruction`	string	Custom instructions injected into the agent’s context

Remote MCP (SSE / Streamable HTTP)

Connect to MCP servers over the network:

toolsets:
  - type: mcp
    remote:
      url: "https://mcp-server.example.com"
      transport_type: "sse" # sse or streamable
      headers:
        Authorization: "Bearer your-token"
    tools: ["search_web", "fetch_url"]

Property	Type	Description
`remote.url`	string	Base URL of the MCP server
`remote.transport_type`	string	`sse` or `streamable`
`remote.headers`	object	HTTP headers (typically for auth)

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.

Combined Example

agents:
  root:
    model: anthropic/claude-sonnet-4-0
    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
        run_tests:
          description: Run the test suite
          cmd: task test
        lint:
          description: Run the linter
          cmd: task lint
      # Custom API tool
      - type: api
        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: "sse"
          headers:
            Authorization: "Bearer ${INTERNAL_TOKEN}"

⚠️ Toolset Order Matters

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

← Previous Model Config Next → Hooks