---
title: "Tool Search — Scale to Thousands of Tools"
aliases: [tool-search, dynamic-tool-loading, enable-tool-search]
tags: [agent-sdk, tools, mcp, context-window, performance]
sources: [raw/Scale to many tools with tool search.md]
created: 2026-04-17
updated: 2026-04-17
---

# 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

1. Tool definitions are **withheld** from context by default.
2. The agent receives a summary of available tools.
3. When it needs a capability, it **searches** the catalog — 3–5 most relevant tools are loaded.
4. Loaded tools **stay in context** for subsequent turns.
5. 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`

```typescript
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|custom SDK MCP tools]].

## Related Articles

- [[wiki/agent-sdk/mcp-integration|MCP Integration]] — connect remote MCP servers that expose many tools
- [[wiki/agent-sdk/custom-tools|Custom Tools]] — build in-process tools with `@tool`
- [[wiki/agent-sdk/agent-loop|Agent Loop]] — how context compaction affects tool availability
- [[wiki/agent-sdk/typescript-api-reference|TypeScript API Reference]] — full `query()` options

## Sources

- `raw/Scale to many tools with tool search.md`
