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 servers also expose their own tools without tools: entries through expose (all of them by default). Declare MCP tools here when you want a custom id, defaults, or a formatter.

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.

Note

Declaring any tool for a server turns that server’s expose policy off: your entries become the whole set of tools for it.

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

If cmd starts with a shell (sh, bash, zsh, dash, fish, cmd, powershell, pwsh) and contains {placeholders}, capa refuses to run it, because caller values would be re-parsed by the shell. Use a non-shell program, or set allowShellPlaceholders: true on that run / init spec if you accept the risk.

Formatters (MCP only)

Optional def.formatter.cmd pipes serialized tool output through a command on the capa server (run directly, without a shell) 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. Their cmd also runs without a shell, so to pipe output wrap it in an explicit shell (for example sh -c '… | jq …'), which needs allowShellPlaceholders: true if the command uses {placeholders}.

Skip formatting for a single CLI call:

capa sh --raw db list-rows

Caution

Formatters run as operator-authored commands and receive tool output on stdin. That output may be attacker-influenced. Do not use formatters that re-execute stdin (for example eval or xargs sh -c). Prefer pure transformers like jq.

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. In search mode, give tools you declare a description: search matches on it.

Related

• Servers · Skills
• Tool exposure
• CLI: sh · CLI: install