Tool Search — Scale to Thousands of Tools

Tool search lets an agent work with up to 10,000 tools by discovering and loading only the relevant ones on demand, instead of cramming all definitions into the context window upfront.

Why It Matters

Problem	Detail
Context bloat	50 tools ≈ 10–20K tokens; leaves less room for actual work
Selection degradation	Accuracy drops noticeably beyond 30–50 loaded tools

How It Works

Tool definitions are withheld from context by default.
The agent receives a summary of available tools.
When it needs a capability, it searches the catalog — 3–5 most relevant tools are loaded.
Loaded tools stay in context for subsequent turns.
If the SDK compacts the conversation (long sessions), previously loaded tools may drop and be re-searched.

One extra round-trip on first discovery, offset by smaller context on every turn. For < ~10 tools, loading everything upfront is faster.

Configuration — `ENABLE_TOOL_SEARCH`

Set via env in query() options:

Value	Behavior
(unset) / `true`	Always on — definitions never in context (default)
`auto`	Activates when tool definitions exceed 10% of context window
`auto:N`	Activates when definitions exceed N% (e.g. `auto:5`)
`false`	Off — all definitions loaded every turn

Example — Remote MCP with `auto:5`

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and run the appropriate database query",
  options: {
    mcpServers: {
      "enterprise-tools": {
        type: "http",
        url: "https://tools.example.com/mcp"
      }
    },
    allowedTools: ["mcp__enterprise-tools__*"], // wildcard pre-approves all
    env: {
      ENABLE_TOOL_SEARCH: "auto:5" // activate when tools exceed 5% of context
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Optimize Tool Discovery

Tool search matches against names and descriptions — write them to surface well:

Names: search_slack_messages > query_slack
Descriptions: "Search Slack messages by keyword, channel, or date range" > "Query Slack"
System prompt hint: list available tool categories so the agent knows what to search for:
```
You can search for tools to interact with Slack, GitHub, and Jira.
```

Limits

Limit	Value
Max tools in catalog	10,000
Results per search	3–5 most relevant
Model support	Claude Sonnet 4+, Opus 4+ (Haiku not supported)

Key Takeaways

Tool search is on by default — no setup needed for large tool sets.
Use auto:N for mixed workloads where tool count varies.
Disable (false) only when tool count is < ~10 and definitions are small.
Good tool names and descriptions are the primary knob for improving discovery accuracy.
Works across all registered tools: remote MCP servers and wiki/agent-sdk/custom-tools.

wiki/agent-sdk/mcp-integration — connect remote MCP servers that expose many tools
wiki/agent-sdk/custom-tools — build in-process tools with @tool
wiki/agent-sdk/agent-loop — how context compaction affects tool availability
wiki/agent-sdk/typescript-api-reference — full query() options

Sources

raw/Scale to many tools with tool search.md

3.8 KiB Raw Blame History Unescape Escape

Tool Search — Scale to Thousands of Tools

Why It Matters

How It Works

Configuration — ENABLE_TOOL_SEARCH

Example — Remote MCP with auto:5