← All guides
Guides November 1, 2026

Tool Search Explained: Why 100 Tools Make Agents Worse

You connected five MCP servers, and your agent got slower and picked the wrong tool more often. That is not bad luck. Each tool definition sits in the context and competes for the model's attention. Tool search fixes this by showing the agent only the tools it asks for. This guide explains how the search works, the trade-offs, and the exact settings.

Bottom Line

  • More tools make the agent pick worse. One 2026 study found accuracy fell below 90% at 10 to 15 tools for Claude Haiku 4.5.
  • Tool search shows the agent only the tools it asks for. The rest stay out of the context until needed.
  • It does not break the prompt cache in the Claude API. Editing your tool list directly does.
  • Code mode is the other fix. The agent writes code that calls the tools. It wins on long chains of calls, and loses on one or two calls.
  • In OpenClaw, set tools.toolSearch. It is experimental and uses BM25 keyword ranking.

Our MCP vs CLI vs API page covers the token cost of MCP and the headline tool search numbers. This page explains how the search works and how to set it up.

Why More Tools Make the Agent Worse

Two costs grow with every tool you add:

  1. Context. Each definition is text: a name, a description and a parameter schema. Anthropic says its own internal setup reached 134,000 tokens of tool definitions before it optimized them.
  2. Choice. The model must pick one tool from the list. Similar names and overlapping descriptions cause wrong picks.

The research on the second cost:

StudyFinding
Rodrigues and Vas (June 2026)Accuracy below 90% between 10 and 15 tools for Claude Haiku 4.5, and between 20 and 30 for Sonnet 4
RAG-MCP (May 2025)Success above 90% under about 30 tools. Past about 100, failures dominate. Retrieving tools first raised accuracy from 13.62% to 43.13% and halved prompt tokens
ToolLLM (2023)16,464 real APIs. The fix was a retriever that picks the APIs first

The pattern is old. Once a list of options is too long, you search it first. Tool search applies that to tools.

How Tool Search Works

  1. The agent starts with a search tool and a few tools you always load.
  2. It writes a query when it needs something it does not have, such as “create a GitHub issue”.
  3. The search returns references to matching tools.
  4. The API loads those full definitions into the context.
  5. The agent calls the tool as normal. Found tools stay usable for the rest of the conversation.

The search methods

MethodHow the agent searchesGood for
Regex (Claude)A Python re.search() pattern, such as "github_.*issue", up to 200 charactersTools with predictable names
BM25 (Claude, OpenClaw)Plain words, up to 500 characters in ClaudeMost setups. Matches words in names and descriptions
EmbeddingsYour own search tool returns tool_reference blocksQueries that use different words from the tool descriptions

BM25 is keyword ranking. It finds “create_issue” for “create an issue”, but it may miss it for “file a bug”. If your users ask in many different ways, an embeddings search is worth the extra work.

Prompt caching

In the Claude API, tool search keeps your cache. The docs say deferred tools “are not included in the system-prompt prefix”. Found tools are added inline, so “prompt caching is preserved.”

Editing the tool list breaks it. Anthropic’s caching docs say a change to tool definitions invalidates the whole cache. Tool search is the cache-safe way to have a large catalog.

OpenAI adds found tools at the end of the context. Its docs say a change to the loaded tool set breaks the cache from that point forward.

Setup: Claude API

Mark tools with defer_loading: true and add a search tool:

{
  "tools": [
    { "type": "tool_search_tool_bm25_20251119", "name": "tool_search_tool_bm25" },
    { "name": "github_create_issue", "description": "Create an issue in a GitHub repository", "input_schema": { "type": "object", "properties": {} }, "defer_loading": true },
    { "name": "read_file", "description": "Read a file from the workspace", "input_schema": { "type": "object", "properties": {} } }
  ]
}

Rules from the docs:

  • Keep 3 to 5 of your most used tools loaded. At least one tool must stay non-deferred, or the API returns a 400 error.
  • Prefix names by service (github_, slack_), so one search finds the whole group.
  • Add one line to the system prompt that lists the tool categories, so the agent knows what to search for.
  • A deferred tool cannot carry cache_control. Put the cache breakpoint on a loaded tool.
  • You still send every definition on every request. defer_loading controls what enters the context, not what you send.
  • Search returns 5 tools by default. No match returns an empty list, not an error.
  • For MCP servers, set defer_loading once in the mcp_toolset default_config.

Use it with 10 or more tools, or more than 10,000 tokens of definitions. Skip it with fewer than 10 tools, or when every tool is used on every request.

Setup: OpenAI

Add {"type": "tool_search"} and set defer_loading: true on functions, namespaces or MCP servers. Two rules from OpenAI’s guide:

  • Keep each namespace under 10 functions. The models were trained mainly to search namespaces and MCP servers.
  • Use client-side search when the right tools depend on the user or project. Your app answers the tool_search_call itself.

Setup: OpenClaw

Tool search is an experimental feature. It is on by default for some run types when the key is unset.

openclaw config set tools.toolSearch true
{
  tools: {
    toolSearch: {
      mode: "tools",           // or "directory"
      searchDefaultLimit: 8,
      maxSearchLimit: 20,
      include: [{ source: "mcp" }],
      exclude: [{ source: "mcp", name: "github__read_*" }],
    },
  },
}

What the agent sees:

ToolWhat it does
tool_searchFinds tools with BM25 over names, descriptions and parameters
tool_describe(id)Returns the full schema of one tool
dispatch_action(id, args)Calls the tool. Approvals, hooks and logging still apply

Facts from the OpenClaw docs:

  • directory mode also adds a short list of trusted tool names and descriptions, capped at 18,000 characters. It is built to keep the prompt cache reusable between turns.
  • Local models get smaller limits: 5 results by default and 10 at most, against 8 and 20.
  • Queries must be in English. There are no embeddings.
  • Claude CLI runs use Claude’s own tool search instead of these tools.
  • A small catalog may not gain. The docs warn that the extra search turns can cost more than they save.

Tool search hides tools. A tool filter removes them. If an agent never needs a tool, remove it:

{ mcp: { servers: { docs: { url: "https://mcp.example.com/mcp", transport: "streamable-http", toolFilter: { include: ["search", "read_*"] } } } } }

A removed tool also cannot be called by an injected instruction. That makes filtering a security step, not only a token saving.

The Alternative: Code Mode

Tool search reduces what the agent sees. Code mode changes how it calls tools. The agent writes a short program that calls several tools, and only the final result returns to the context.

SourceResult
Cloudflare (February 2026)Its API has more than 2,500 endpoints. As plain MCP tools: 1.17 million tokens. With two tools, search() and execute(): about 1,000 tokens
Anthropic code execution with MCP (November 2025)150,000 tokens down to 2,000 on one task
Anthropic programmatic tool calling docsAbout 38% fewer input tokens on a 75-tool benchmark, with no change in accuracy
Same docs, τ²-benchNo better scores and about 8% more cost, with one or two calls per turn

Pick by the shape of the work:

  • Many calls in a row, or big results to filter: code mode.
  • One or two calls per turn, from a large catalog: tool search.
  • A small, fixed set of tools: neither. Load them all.

In OpenClaw, code mode is tools.codeMode.enabled (false, true or "auto"). The default node executor is “not a security boundary”. Use executor: "quickjs" for stronger isolation. It is also experimental.

Where the Standard Is Going

MCP has a working group for this problem, now called Progressive Disclosure. It became a working group on 21 September 2026 and is still at “Active Exploration”. There is no spec feature yet. Each client, such as Claude, OpenAI or OpenClaw, does tool search its own way.

Honest Caveats

  1. The tool-count studies used specific models and tasks. Your break point depends on how clear your tool names and descriptions are.
  2. We did not measure OpenClaw tool search. Its docs give no token savings figures.
  3. Both OpenClaw features are experimental. Check the keys in your version.
  4. The OpenClaw code mode example is ours. The docs list the fields but give no full example config.

Sources

See Also

Read next

Agent Loops Explained: Goal, Act, Verify, Stop
Every AI agent is a loop: goal, act, verify, stop. Loop engineering is designing that loop so it checks its own work and ends at the right time. Stop conditions in Claude Code, Codex, the OpenAI Agents SDK and OpenClaw, the verification data, and the runaway costs.
Context Rot Explained: Why Agents Get Worse Over Time
Context rot is the drop in model accuracy as the input grows, long before the context window is full. The benchmark data, why a 1M window is not 1M useful tokens, what compaction loses, and the fixes in Claude Code, the Claude API and OpenClaw.
MCP vs CLI vs API Explained: What Your Agent Should Use
MCP, a CLI and a plain API call can all give an agent the same ability. They differ in token cost, reliability, auth and how easy they are to control. The 2026 benchmarks, the new stateless MCP spec, tool search, and a decision rule with the OpenClaw settings for each.
Pass Rate vs Completion Rate Explained: Agent Benchmarks
Why the best coding agents pass only 40% of Android Bench 2.0's long tasks but complete over 80% of the work. Pass rate vs completion rate, pass@k vs pass^k, harness effects, saturated benchmarks, and a checklist for reading any agent benchmark claim.