A sub-agent should not hold every tool
← All posts

A sub-agent should not hold every tool

By Antonio

By April the capabilities file was doing more than proxying MCP. CAPA 1.3, on April 6, added sub-agents: a named specialist with its own instructions, and only the tools you list.

The problem

A general agent with every tool will eventually use one it should not. The research pass does not need to publish, push, or send. If those tools are in its list, the only thing stopping it is the prompt, and prompts leak.

I wanted the restriction in the config, where I can read it.

Declare the specialist

A sub-agent points at skill ids and tool ids that already exist in the file. This one looks things up and stops:

subagents:
  - id: research-agent
    description: >-
      Looks up product facts before a brief is written. Use when a draft
      needs sources. Does not publish.
    skills:
      - draft-brief
    tools:
      - draft-status
    instructions: |
      You gather sources for the brief. You do not publish it.

capa install writes that into each provider’s own format. Cursor gets .cursor/agents/research-agent.md. Claude Code gets .claude/agents/research-agent.md, plus a second MCP entry, capa-research-agent, that only accepts the tools on the list. A call to anything else is rejected.

The Cursor file from this install:

The research-agent file CAPA wrote for Cursor

The description is what Cursor uses to decide when to delegate, so it has to say when to use the agent and what it must not do. “Helps with research” is not enough.

What this is not

The filtered MCP endpoint is the hard boundary, and today that registration is on Claude Code. Cursor keeps a single capa MCP entry and uses the agent file for delegation. If you need the tool list enforced rather than suggested, check which client you installed for.

Removing the sub-agent from the file and running capa install again deletes the agent files. capa clean removes all of them.

Why it mattered

The February post cut the tool list for the main agent. Sub-agents do the same cut per role. The research agent can print a status line. It cannot publish the brief, because that tool was never given to it.

Sub-agents landed in CAPA 1.3. The agent file above is from a current install, 2.2.4.