Tool Exposure

The options.toolExposure setting controls how CAPA exposes MCP tools to your AI agent. Different modes trade off between context window usage, compatibility, and simplicity.

Configuration

Set toolExposure under the options key in your capabilities file. The default is expose-all.

options:
  toolExposure: on-demand  # expose-all | on-demand | none
{
  "options": {
    "toolExposure": "on-demand"
  }
}

Modes

expose-all (default)

Every tool's full JSON schema is published up front via MCP tools/list. This is the vanilla MCP baseline — the agent sees all available tools immediately in its context window.

Best for: simple setups with few tools, clients that support dynamic tool lists.

Tradeoff: context window usage scales linearly with the number of tools. With large MCP servers (e.g., GitHub's 108 tools / 161 KB of schemas), this can consume significant prompt space.

on-demand

Only two meta-tools are exposed: setup_tools and call_tool. The agent must first call setup_tools to discover available tool signatures, then use call_tool to invoke them. Full schemas are returned lazily — only when a call_tool invocation fails does the response include the full input schema for correction.

Best for: multi-server setups, schema-heavy MCP servers, cost-sensitive workloads.

Workflow:

  1. Agent calls: setup_tools({"skills": ["skill-id"]})
  2. CAPA returns: compact tool signatures (not full schemas)
  3. Agent calls: call_tool({"name": "tool_name", "data": {args}})
  4. On success: result returned directly
  5. On validation error: full schema attached for self-correction

none

CAPA skips all project-local MCP config writes at install time. The MCP endpoint returns an empty tools/list and rejects tools/call with a hint to use capa sh. The agent reaches tools exclusively through capa sh <server> <tool> shell commands.

Best for: shell-comfortable agents, one-shot CLI patterns, maximum context savings.

See the capa sh documentation for details on invoking tools from the command line.

Performance Impact

Benchmarks on claude-opus-4-8 across 5 real-world tasks (150 trials) show:

  • Both on-demand and none modes deliver ~19% cost savings vs the expose-all baseline ($0.99 vs $1.22 across the suite)
  • Savings concentrate on schema-heavy, multi-backend tasks — up to 40% cheaper on incident triage (sentry+slack, 36 tools / 128 KB)
  • Zero quality regression: 150/150 deterministic assertions pass across all modes
  • The control case (pure code editing, no SaaS tools) shows ~10% overhead — bounding the worst case

See the full benchmark report for detailed charts and per-scenario breakdowns.

Recommendations

  • Default to on-demand for general MCP-heavy agents
  • Use none when shell-comfortable, one-shot patterns dominate
  • Keep expose-all only when there's no SaaS surface to filter (pure coding tasks)

Related Documentation

  • Benchmarks - Detailed performance comparisons across tool exposure modes
  • Capabilities File - Overall configuration structure
  • capa sh - Run tools directly from the command line
  • Tools - Define MCP and command tools