Skip to content

On-demand tools

Use options.toolExposure: on-demand when a large toolset would bloat the agent context. At startup the agent only sees setup_tools and call_tool; it activates skills as needed.

Goal

Configure multiple skills with explicit requires, set toolExposure to on-demand, install, and let the agent call setup_tools([...]) before call_tool.

capabilities.yaml

providers:
  - cursor

options:
  toolExposure: on-demand

skills:
  - id: researcher
    type: inline
    def:
      description: Web research skill
      requires:
        - '@brave.search'
      content: |
        ---
        name: researcher
        description: Activate for web research
        ---
        Call setup_tools with this skill, then use brave.search via call_tool.

  - id: data-analyst
    type: inline
    def:
      description: Local pandas queries
      requires:
        - pandas_query
      content: |
        ---
        name: data-analyst
        description: Activate for CSV / DataFrame queries
        ---
        Call setup_tools with this skill, then use pandas_query.

servers:
  - id: brave
    type: mcp
    def:
      cmd: npx
      args:
        - -y
        - "@modelcontextprotocol/server-brave-search"
      env:
        BRAVE_API_KEY: ${BraveApiKey}

tools:
  - id: search
    type: mcp
    def:
      server: "@brave"
      tool: brave_web_search

  - id: pandas_query
    type: command
    def:
      run:
        cmd: python -c "import pandas as pd; df = pd.read_csv('{file}'); print(df.query('{query}'))"
        args:
          - name: file
            type: string
            required: true
          - name: query
            type: string
            required: true

Agent flow

setup_tools(["researcher"]) — activates the skill and returns compact tool signatures (not full schemas).
call_tool({ name: "brave.search", data: { query: "…" } }) — invokes the tool. Invalid args return the full input schema so the agent can retry.
setup_tools(["data-analyst"]) — adds pandas_query to the active set.

Install and restart

capa install
capa restart   # pick up toolExposure changes on the proxy

See also