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

At agent startup, all configured tools are indexed in a BM25 keyword index (pure Python, no embeddings, no external dependencies).
Only tools listed in always_available are loaded into the initial context.
The agent receives a search_tools meta-tool instead of every tool definition.
When the agent needs a capability, it searches by keyword (e.g. "read file", "send slack").
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

name: multi-tool-agent
description: Agent with many tools and on-demand discovery
prompt: |
  You are an operations assistant. Search for the tool you need before answering.
tool_search:
  enabled: true
  always_available:
    - read_file
    - list_directory
    - think
  max_results: 5
  threshold: 0.0
tools:
  - filesystem:
      root_path: ./src
  - think
  - http:
      base_url: https://api.example.com
  - search:
      provider: duckduckgo
  - git
  - shell:
      allowed_commands: [make, npm]
  - sql:
      database: ./data.db
  - slack:
      webhook_url: "${SLACK_WEBHOOK_URL}"
  - email:
      imap_host: imap.example.com
      username: "${EMAIL_USER}"
      password: "${EMAIL_PASSWORD}"
  - csv_analysis
  - web_reader
  - web_scraper

In this example, only the filesystem read functions (read_file, list_directory) and think are visible to the model from the start. The remaining tools are discoverable via search_tools. Names in always_available are tool function names, not tool types: one type can register several functions (datetime registers current_time and parse_date).

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.