当工具数量超过 30-50 个时，将所有工具定义预加载到上下文窗口会消耗大量 token（50 个工具约 10-20K tokens），且工具选择准确率下降。Tool Search 默认开启，Agent 按需搜索并加载最相关的 3-5 个工具。
核心机制
工作原理：工具定义默认不加载到上下文，Agent 收到工具摘要，需要某种能力时搜索并加载相关工具。已加载的工具在后续轮次保持可用，上下文压缩时可能被移除并重新搜索。
搜索匹配：基于工具名称和描述进行语义匹配，返回 3-5 个最相关工具。
支持模型：Claude Sonnet 4+、Claude Opus 4+（Haiku 不支持）。
默认行为：
- 标准 Anthropic API：默认开启
- Vertex AI：默认关闭（Sonnet 4.5+ 和 Opus 4.5+ 支持）
- 非 Anthropic 代理（
ANTHROPIC_BASE_URL指向第三方）：默认关闭
关键细节
ENABLE_TOOL_SEARCH 配置值：
| 值 | 行为 |
|---|---|
| 不设置 | 默认开启（Vertex AI 和第三方代理除外） |
true | 强制开启（Vertex AI 上不支持的模型会失败） |
auto | 工具定义超过上下文窗口 10% 时激活 |
auto:5 | 工具定义超过 5% 时激活（自定义阈值） |
false | 关闭，所有工具定义每轮都加载 |
options = ClaudeAgentOptions(
mcp_servers={"enterprise-tools": {"type": "http", "url": "..."}},
allowed_tools=["mcp__enterprise-tools__*"],
env={"ENABLE_TOOL_SEARCH": "auto:5"},
)优化工具发现：
- 工具名使用描述性命名：
search_slack_messages优于query_slack - 描述包含具体关键词：
"Search Slack messages by keyword, channel, or date range"优于"Query Slack" - 在 system prompt 中列出可用工具类别：
"You can search for tools to interact with Slack, GitHub, and Jira."
限制：最多 10,000 个工具，每次搜索返回 3-5 个。
与其他概念的关联
- mcp - MCP 服务器工具默认使用 Tool Search
- custom-tools - 自定义工具也支持 Tool Search
- agent-loop - Tool Search 增加一次额外的搜索往返
实践要点
- 工具数量少（<10 个）时，关闭 Tool Search（
false）更快，避免额外搜索往返 auto模式是平衡点，工具少时直接加载，工具多时按需搜索- 工具描述质量直接影响搜索准确率，投入时间写好描述
- Vertex AI 上需要显式设置
ENABLE_TOOL_SEARCH=true才能启用