Tools

Tools are what agents (and you) actually invoke. Declare them under tools, reference them from skills with requires, and exercise them with capa sh.

MCP tools

Point at a configured server and the upstream tool name:

tools:
  - id: search
    type: mcp
    description: Web search via Brave
    def:
      server: '@brave'
      tool: brave_web_search
      # defaults: { count: 5 }

In skills, reference as @server.tool using your tool id: @brave.search.

Command tools

tools:
  - id: hello_world
    type: command
    description: Print a greeting
    group: demo
    def:
      run:
        cmd: 'echo Hello, {name}!'
        args:
          - name: name
            type: string
            description: Who to greet
            required: true

Optional def.init.cmd runs one-time setup. Use group to nest the command under capa sh <group> ….

Formatters (MCP only)

Optional def.formatter.cmd pipes serialized tool output through a shell command on the capa server before returning it to MCP clients and capa sh (for example jq to reshape JSON). On failure or timeout (default 3000ms; override with def.formatter.timeout) capa returns the original output.

def:
  server: '@db'
  tool: list_rows
  formatter:
    cmd: 'jq -r ''.[] | [.id, .name] | @tsv'''
    # timeout: 3000

Command-type tools do not use formatter — pipe inside def.run.cmd instead.

Skip formatting for a single CLI call:

capa sh --raw db list-rows

Run from the CLI

capa sh                         # list
capa sh brave                   # tools for a server group
capa sh brave search --help
capa sh demo hello-world --name Ada

Tool ids are slugified to kebab-case. The capa server must be running (capa start / after install).

How many tools appear on the MCP tools/list depends on options.toolExposure.