工具搜索工具

工具搜索工具（tool search tool）让 Claude 能够通过按需发现和加载工具来处理数百或数千个工具。Claude 不会预先将所有工具定义加载到 "context window"（上下文窗口）中，而是搜索您的工具目录（包括工具名称、描述、参数名称和参数描述），并仅加载它所需的工具。

随着工具库的增长，预先加载每个工具定义会导致两个问题：

• 上下文膨胀： 一个典型的多服务器设置（GitHub、Slack、Sentry、Grafana 和 Splunk）在 Claude 开始任何工作之前，仅定义就可能消耗约 55k 个令牌。工具搜索通常可将其减少 85% 以上，仅加载 Claude 处理给定请求所需的 3–5 个工具。
• 工具选择准确性： 一旦可用工具超过 30–50 个，Claude 选择正确工具的能力就会下降。由于工具搜索仅按需加载一组聚焦的相关工具，因此即使面对数千个工具，选择准确性也能保持较高水平。

有关支持工具搜索的模型，请参阅模型兼容性。

工具搜索作为服务器端工具运行，但您也可以实现自己的客户端工具搜索。详情请参阅自定义工具搜索实现。

模型兼容性

两种工具搜索变体均可在以下模型上使用：

Claude Opus 4.1 及更早的模型不支持工具搜索工具。

工具搜索的工作原理

工具搜索有两种变体：

• Regex（tool_search_tool_regex_20251119）：Claude 构造正则表达式模式来搜索工具。
• BM25（tool_search_tool_bm25_20251119）：Claude 使用自然语言查询来搜索工具。

当您启用工具搜索工具时：

1. 您在 tools 列表中包含一个工具搜索工具（例如 tool_search_tool_regex_20251119 或 tool_search_tool_bm25_20251119）。
2. 您在 tools 数组中提供每个工具定义，并在不应预先加载的工具上设置 defer_loading: true。至少有一个工具（通常是工具搜索工具本身）必须保持非延迟状态。
3. 最初，Claude 的上下文仅包含工具搜索工具和任何非延迟工具。
4. 当 Claude 需要其他工具时，它会使用工具搜索工具进行搜索。
5. API 运行搜索并以 tool_reference 块的形式返回匹配的工具（默认最多 5 个；Claude 可以在其搜索输入中设置 limit）。
6. API 自动将这些引用展开为完整的工具定义。
7. Claude 从发现的工具中进行选择并调用它们。

快速开始

以下示例包含工具搜索工具和两个延迟工具：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get the weather at a specific location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location"],
            },
            "defer_loading": True,
        },
        {
            "name": "search_files",
            "description": "Search through files in the workspace",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "file_types": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["query"],
            },
            "defer_loading": True,
        },
    ],
)

print(response)

Claude 搜索目录，发现 get_weather 并调用它。响应以 stop_reason: "tool_use" 结束。请按照处理工具调用中的方式执行发现的工具并返回 tool_result。响应格式展示了您收到的块以及接下来要发送的内容。

工具定义

工具搜索工具有两种变体：

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}

延迟工具加载

通过添加 defer_loading: true 将工具标记为按需加载：

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"]
  },
  "defer_loading": true
}

defer_loading 控制的是进入上下文窗口的内容，而不是您在请求中发送的内容：

• 您仍然需要在每个请求的 tools 数组中发送每个工具的完整定义，包括延迟的工具。API 需要在服务器端使用它们来运行搜索并展开 tool_reference 块。
• 没有 defer_loading 的工具会立即加载到上下文中。
• 带有 defer_loading: true 的工具仅在 Claude 通过搜索发现它们时才会加载。
• 切勿在工具搜索工具本身上设置 defer_loading: true。
• 将您最常用的 3–5 个工具保持为非延迟状态，以便 Claude 无需先搜索即可调用它们。

计算机使用和浏览器使用工具集（computer_toolset_20260801 和 browser_toolset_20260801）在条目的 configs 对象内按成员工具接受 defer_loading，而不是在条目本身上设置；在条目级别设置它的请求会被拒绝。由于工具集作为一个整体进行延迟和展开，defer_loading 在每个已启用的成员上必须解析为相同的值，并且当 Claude 通过搜索发现该工具集时，所有已启用的成员会一次性加载。有关 configs 格式，请参阅客户端工具集。

两种工具搜索变体（regex 和 bm25）都会搜索工具名称、描述、参数名称和参数描述。

在内部，API 会将延迟工具从系统提示前缀中排除。当 Claude 通过工具搜索发现延迟工具时，API 会在对话中内联追加一个 tool_reference 块，然后在将其传递给 Claude 之前将其展开为完整的工具定义。前缀保持不变，因此 "prompt caching"（提示缓存）得以保留。严格模式的语法（约束工具调用输出以匹配您的模式的规则）是基于完整工具集构建的，因此 defer_loading 和严格模式可以组合使用而无需重新编译语法。

响应格式

当 Claude 使用工具搜索工具时，响应包含以下块类型：

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll search for tools to help with the weather information."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01ABC123",
      "name": "tool_search_tool_regex",
      "input": {
        "pattern": "weather",
        "limit": 10
      }
    },
    {
      "type": "tool_search_tool_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": {
        "type": "tool_search_tool_search_result",
        "tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }]
      }
    },
    {
      "type": "text",
      "text": "I found a weather tool. Let me get the weather for San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01XYZ789",
      "name": "get_weather",
      "input": { "location": "San Francisco", "unit": "fahrenheit" }
    }
  ],
  "stop_reason": "tool_use"
}

理解响应

• server_tool_use： Claude 对工具搜索工具的调用。搜索在 Anthropic 的服务器上运行。切勿为其 srvtoolu_... ID 返回 tool_result。input 包含搜索内容（regex 变体为 pattern，BM25 为 query），并且可能包含一个可选的 limit，即一个 1 到 10,000 之间的整数，用于限制搜索返回的匹配工具数量（默认值：5）。
• tool_search_tool_result： 搜索结果，位于嵌套的 tool_search_tool_search_result 对象中。请将其原样保留在消息历史中。
• tool_references： 指向已发现工具的 tool_reference 对象数组。API 会为 Claude 展开这些引用。您永远不需要自己展开它们。
• tool_use： Claude 对已发现工具的调用。请执行它并返回 tool_result，与标准工具使用完全相同。

API 会在向 Claude 展示之前自动将 tool_reference 块展开为完整的工具定义。只要您在 tools 参数中提供了所有匹配的工具定义，就无需自己处理此展开过程。

继续对话

在下一个请求中，原样传回助手的内容，包括 server_tool_use 和 tool_search_tool_result 块。在用户消息中为已发现的工具添加您的 tool_result，并发送相同的 tools 数组：搜索工具加上每个延迟定义。不要为 srvtoolu_... ID 返回 tool_result：API 会拒绝该请求。API 会在整个对话历史中展开 tool_reference 块，因此 Claude 可以在后续轮次中重用已发现的工具而无需重新搜索。没有匹配结果的搜索会返回一个带有空 tool_references 数组的 tool_search_tool_search_result，而不是错误。

MCP 集成

如果您的工具通过 MCP 连接器来自 MCP 服务器，则无需在单个工具定义上设置 defer_loading。相反，您可以在 mcp_toolset 条目的 default_config 上为整个服务器设置一次，或在其 configs 中按工具设置。请参阅 MCP 工具集配置。

自定义工具搜索实现

您可以通过从自定义工具返回 tool_reference 块来实现自己的工具搜索逻辑（例如，使用嵌入或语义搜索）。当 Claude 调用您的自定义搜索工具时，返回一个标准的 tool_result，并在内容数组中包含 tool_reference 块：

{
  "type": "tool_result",
  "tool_use_id": "toolu_your_tool_id",
  "content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}

每个被引用的工具都必须在顶层 tools 参数中有对应的工具定义，通常带有 defer_loading: true。这使您可以使用内置变体不提供的搜索方法，例如基于嵌入的检索，并且 API 会以相同的方式展开返回的 tool_reference 块。

有关使用嵌入的完整示例，请参阅使用嵌入的工具搜索示例。

错误处理

HTTP 错误（400 状态）

这些错误会阻止 API 处理请求：

所有工具均被延迟：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "At least one tool must have defer_loading=false. All tools cannot be deferred."
  }
}

缺少工具定义：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' not found in available tools"
  }
}

工具结果错误（200 状态）

当工具搜索操作在执行期间失败时，API 会返回 200 响应，并在响应体中包含错误：

{
  "type": "tool_search_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_tool_input",
    "error_message": "Invalid regular expression pattern: missing ) at position 1"
  }
}

error_code 字段有四个可能的值：

• invalid_tool_input：搜索输入无效，例如格式错误的正则表达式模式或超过 200 个字符限制的模式
• unavailable：搜索无法运行，例如因为超时或服务不可用
• too_many_requests：工具搜索操作超出速率限制
• execution_time_exceeded：搜索超出了其执行时间限制

常见错误

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

{
  "name": "my_tool",
  "description": "Full description here",
  "input_schema": {
    "type": "object"
  },
  "defer_loading": true
}

提示缓存

要了解 defer_loading 如何保留提示缓存，请参阅工具使用与提示缓存。

带有 defer_loading: true 的工具不能同时携带 cache_control：API 会返回 400。请将缓存断点放在非延迟工具上。

流式传输

启用 "streaming"（流式传输）后，您将在流中收到工具搜索事件：

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "tool_search_tool_regex"}}

// Search pattern streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"pattern\":\"weather\"}"}}

// Pause while search executes

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "tool_search_tool_search_result", "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}]}}}

// Claude continues with discovered tools

批量请求

您可以在 Messages Batches API 中包含工具搜索工具。

限制和最佳实践

限制

• 最大延迟工具数： 每个请求最多 10,000 个带有 defer_loading: true 的工具
• 搜索结果： 每次搜索默认最多返回 5 个匹配工具；Claude 可以在其搜索输入中将 limit 设置为 1 到 10,000 之间的任意整数
• 模式和查询长度： 正则表达式模式最多 200 个字符，BM25 查询最多 500 个字符
• 模型支持： 请参阅模型兼容性

何时使用工具搜索

当满足以下任一条件时，请使用工具搜索：

• 您有 10 个或更多可用工具。
• 您的工具定义消耗超过 10k 个令牌。
• 随着工具集的增长，工具选择准确性下降。
• 您聚合了多个 MCP 服务器（200+ 个工具）。
• 您的工具库随时间增长。

当您的工具少于 10 个、每个请求都会使用每个工具，或者您的工具定义很小（总计少于 100 个令牌）时，不使用工具搜索的标准工具调用更为合适。

优化技巧

• 将您最常用的 3–5 个工具保持为非延迟状态。
• 编写清晰、描述性强的工具名称和描述。
• 在工具名称中使用一致的命名空间：按服务或资源添加前缀（例如 github_、slack_），以便一次搜索即可匹配整个组。
• 在描述中使用与用户描述任务方式相匹配的关键词。
• 添加一个描述可用工具类别的系统提示部分："You can search for tools to interact with Slack, GitHub, and Jira."
• 监控 Claude 发现了哪些工具，以优化您的描述。

用量

工具搜索不作为单独的服务器工具计量。响应的 usage.server_tool_use 对象中没有工具搜索字段，搜索加载到上下文中的工具定义与任何其他工具定义一样计为输入令牌。

后续步骤