Tool Search

When agents have many configured tools (10+), tool definitions consume large amounts of context and model tool-selection accuracy degrades. Tool search solves this by indexing all tools at startup and giving the agent a single search_tools meta-tool to discover capabilities on demand.

How It Works

1. At agent startup, all configured tools are indexed in a BM25 keyword index (pure Python, no embeddings, no external dependencies).
2. Only tools listed in always_available are loaded into the initial context.
3. The agent receives a search_tools meta-tool instead of every tool definition.
4. When the agent needs a capability, it searches by keyword (e.g. "read file", "send slack").
5. Matched tools are dynamically injected into the agent's toolset for the remainder of the run.

This typically reduces tool-related context by 60-80% for agents with 10+ tools.

Configuration

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: multi-tool-agent
  description: Agent with many tools and on-demand discovery
spec:
  tool_search:
    enabled: true
    always_available:
      - filesystem
      - think
    max_results: 5
    threshold: 0.0
  tools:
    - type: filesystem
      root_path: ./src
    - type: think
    - type: http
      base_url: https://api.example.com
    - type: search
      provider: duckduckgo
    - type: git
    - type: shell
      allowed_commands: [make, npm]
    - type: sql
      connection_string: sqlite:///data.db
    - type: slack
      webhook_url: "${SLACK_WEBHOOK_URL}"
    - type: email
    - type: csv_analysis
    - type: web_reader
    - type: web_scraper

In this example, only filesystem and think are visible to the model from the start. The remaining 10 tools are discoverable via search_tools.

See Configuration — Tool Search for the full field reference.

When To Use It

• Agents with 10+ tools where most are only needed for specific tasks
• Agents that need broad capability but run on context-limited models
• Reducing token costs on models with expensive input pricing

For agents with fewer tools, the overhead of an extra search step outweighs the context savings. Leave enabled: false (the default).

Implementation Details

• BM25 keyword index — Tools are indexed by type, name, description, and parameter names. Standard BM25 scoring (k1=1.5, b=0.75) with IDF weighting, name/param boosting, and prefix matching.
• No embeddings — Unlike RAG, tool search uses keyword matching only. Startup is instant with no embedding API calls.
• Run-scoped — Discovered tools persist for the duration of the run but do not carry over to subsequent runs.
• camelCase expansion — Tokenization expands sendSlackMessage into send, slack, message for better matching.

Dashboard

The Cognition panel in the web dashboard provides a visual interface for configuring tool search — toggle it on, pick always-available tools from a checklist, and tune max_results and threshold without editing YAML.