{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# 使用工具搜索扩展到大量工具

> 通过按需发现和加载所需工具，将你的智能体扩展到数千个工具。

工具搜索使你的智能体能够通过按需动态发现和加载来使用数百甚至数千个工具。智能体不会将所有工具定义预先加载到上下文窗口中，而是搜索工具目录并仅加载所需的工具。

随着工具库规模的增长，这种方法解决了两个挑战：

* **上下文效率：** 工具定义可能消耗大量上下文窗口（50 个工具可能使用 10-20K 个 token），为实际工作留下的空间更少。
* **工具选择准确性：** 当同时加载超过 30-50 个工具时，工具选择准确性会下降。

工具搜索默认启用。本页涵盖[其工作原理](#how-tool-search-works)、如何[配置](#configure-tool-search)以及如何[优化工具发现](#optimize-tool-discovery)。

## 工具搜索的工作原理

当工具搜索处于活动状态时，工具定义会从上下文窗口中移除。智能体会收到可用工具的摘要，并在任务需要尚未加载的功能时搜索相关工具。3-5 个最相关的工具会被加载到上下文中，并在后续轮次中保持可用。如果对话足够长以至于 SDK 压缩较早的消息以释放空间，先前发现的工具可能会被移除，智能体会根据需要重新搜索。

工具搜索在 Claude 首次发现工具时会增加一次额外的往返（搜索步骤），但对于大型工具集，这可以通过每轮更小的上下文来抵消。当工具少于约 10 个时，预先加载所有工具通常更快。

有关底层 API 机制的详细信息，请参阅 [API 中的工具搜索](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool)。

<Note>
  工具搜索需要 Claude Sonnet 4 或更高版本，或 Claude Opus 4 或更高版本。Haiku 模型不支持工具搜索。
</Note>

## 配置工具搜索

工具搜索默认开启。在 Vertex AI 上默认禁用，支持 Claude Sonnet 4.5 及更高版本和 Claude Opus 4.5 及更高版本。当 `ANTHROPIC_BASE_URL` 指向非第一方主机时也会禁用，因为大多数代理不会转发 `tool_reference` 块。你可以使用 `ENABLE_TOOL_SEARCH` 环境变量覆盖任一默认值：

| 值    | 行为                                                                                                                                                                                                                         |
| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| （未设置）  | 工具搜索开启。工具定义被延迟并按需发现。在 Vertex AI 或非第一方 `ANTHROPIC_BASE_URL` 上回退到预先加载。                                                                 |
| `true`   | 工具搜索始终开启。即使在 Vertex AI 上和通过代理，SDK 也会发送 beta 头。在早于 Sonnet 4.5 或 Opus 4.5 的 Vertex AI 模型上，或在不支持 `tool_reference` 块的代理上，请求会失败。 |
| `auto`   | 检查所有工具定义的组合 token 数量与模型上下文窗口的比较。如果超过 10%，工具搜索激活。如果低于 10%，所有工具正常加载到上下文中。                         |
| `auto:N` | 与 `auto` 相同但使用自定义百分比。`auto:5` 在工具定义超过上下文窗口的 5% 时激活。更低的值会更早激活。                                                                                 |
| `false`  | 工具搜索关闭。所有工具定义在每轮都加载到上下文中。                                                                                                                                                  |

工具搜索适用于所有注册的工具，无论它们来自远程 MCP 服务器还是[自定义 SDK MCP 服务器](/en/agent-sdk/custom-tools)。使用 `auto` 时，阈值基于所有服务器上所有工具定义的组合大小。

在 `query()` 的 `env` 选项中设置值。以下示例连接到一个暴露许多工具的远程 MCP 服务器，使用通配符预先批准所有工具，并使用 `auto:5` 以便在工具定义超过上下文窗口的 5% 时激活工具搜索：

<CodeGroup>
  ```typescript TypeScript theme={null}
  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": {
          // Connect to a remote MCP server
          type: "http",
          url: "https://tools.example.com/mcp"
        }
      },
      allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
      env: {
        ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when tools exceed 5% of context
      }
    }
  })) {
    if (message.type === "result" && message.subtype === "success") {
      console.log(message.result);
    }
  }
  ```

  ```python Python theme={null}
  import asyncio
  from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


  async def main():
      options = ClaudeAgentOptions(
          mcp_servers={
              "enterprise-tools": {
                  "type": "http",
                  "url": "https://tools.example.com/mcp",
              }
          },
          allowed_tools=[
              "mcp__enterprise-tools__*"
          ],  # Wildcard pre-approves all tools from this server
          env={
              "ENABLE_TOOL_SEARCH": "auto:5"  # Activate tool search when tools exceed 5% of context
          },
      )

      async for message in query(
          prompt="Find and run the appropriate database query",
          options=options,
      ):
          if isinstance(message, ResultMessage) and message.subtype == "success":
              print(message.result)


  asyncio.run(main())
  ```
</CodeGroup>

将 `ENABLE_TOOL_SEARCH` 设置为 `"false"` 会禁用工具搜索，并在每轮将所有工具定义加载到上下文中。这会消除搜索往返，当工具集较小（少于约 10 个工具）且定义可以舒适地放入上下文窗口时，这可能更快。

## 优化工具发现

搜索机制将查询与工具名称和描述进行匹配。像 `search_slack_messages` 这样的名称比 `query_slack` 能够匹配更广泛的请求。包含特定关键字的描述（"Search Slack messages by keyword, channel, or date range"）比通用描述（"Query Slack"）能匹配更多查询。

你还可以添加一个列出可用工具类别的系统提示部分。这让智能体了解有哪些类型的工具可供搜索：

```text theme={null}
You can search for tools to interact with Slack, GitHub, and Jira.
```

## 限制

* **最大工具数：** 目录中最多 10,000 个工具
* **搜索结果：** 每次搜索返回 3-5 个最相关的工具
* **模型支持：** Claude Sonnet 4 及更高版本，Claude Opus 4 及更高版本（不支持 Haiku）

## 相关文档

* [API 中的工具搜索](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool)：工具搜索的完整 API 文档，包括自定义实现
* [连接 MCP 服务器](/en/agent-sdk/mcp)：通过 MCP 服务器连接到外部工具
* [自定义工具](/en/agent-sdk/custom-tools)：使用 SDK MCP 服务器构建自己的工具
* [TypeScript SDK 参考](/en/agent-sdk/typescript)：完整 API 参考
* [Python SDK 参考](/en/agent-sdk/python)：完整 API 参考