工具搜索工具

工具搜索工具使 Claude 能够通过动态发现和按需加载工具来处理数百或数千个工具。与其将所有工具定义预先加载到上下文窗口中，Claude 会搜索您的工具目录（包括工具名称、描述、参数名称和参数描述），并仅加载它需要的工具。

这种方法解决了两个随着工具库规模扩大而迅速加剧的问题：

• 上下文膨胀： 工具定义会快速消耗您的上下文预算。典型的多服务器设置（GitHub、Slack、Sentry、Grafana、Splunk）在 Claude 进行任何实际工作之前可能会消耗约 55k 个令牌的定义。工具搜索通常会将其减少 85% 以上，仅加载 Claude 对给定请求实际需要的 3-5 个工具。
• 工具选择准确性： 一旦可用工具超过 30-50 个，Claude 正确选择正确工具的能力会显著下降。通过按需呈现一组有针对性的相关工具，工具搜索即使在数千个工具中也能保持高选择准确性。

虽然这是作为服务器端工具提供的，但您也可以实现自己的客户端工具搜索功能。有关详细信息，请参阅自定义工具搜索实现。

您也可以通过从自己的搜索实现返回 tool_reference 块来实现客户端工具搜索。

工具搜索的工作原理

有两种工具搜索变体：

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

启用工具搜索工具时：

1. 您在工具列表中包含工具搜索工具（例如 tool_search_tool_regex_20251119 或 tool_search_tool_bm25_20251119）
2. 您为不应立即加载的工具提供所有工具定义，并设置 defer_loading: true
3. Claude 最初只看到工具搜索工具和任何非延迟工具
4. 当 Claude 需要其他工具时，它使用工具搜索工具进行搜索
5. API 返回 3-5 个最相关的 tool_reference 块
6. 这些引用会自动扩展为完整的工具定义
7. Claude 从发现的工具中选择并调用它们

这样可以保持上下文窗口的效率，同时保持高工具选择准确性。

快速开始

这是一个带有延迟工具的简单示例：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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)

工具定义

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

{
  "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 的工具会立即加载到上下文中
• 具有 defer_loading: true 的工具仅在 Claude 通过搜索发现它们时才加载
• 工具搜索工具本身不应该具有 defer_loading: true
• 为了获得最佳性能，将您最常用的 3-5 个工具保持为非延迟

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

延迟工作原理： 延迟工具不包含在系统提示前缀中。当模型通过工具搜索发现延迟工具时，工具定义作为 tool_reference 块内联附加到对话中。前缀保持不变，因此提示缓存得以保留。严格模式的语法从完整工具集构建，因此 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": {
        "query": "weather"
      }
    },
    {
      "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 正在调用工具搜索工具
• tool_search_tool_result： 包含搜索结果，其中包含嵌套的 tool_search_tool_search_result 对象
• tool_references： 指向发现的工具的 tool_reference 对象数组
• tool_use： Claude 调用发现的工具

tool_reference 块会自动扩展为完整的工具定义，然后显示给 Claude。您无需自己处理此扩展。只要您在 tools 参数中提供所有匹配的工具定义，它就会在 API 中自动进行。

MCP 集成

有关使用 defer_loading 配置 mcp_toolset 的信息，请参阅 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。这种方法让您可以使用更复杂的搜索算法，同时保持与工具搜索系统的兼容性。

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

错误处理

HTTP 错误（400 状态）

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

所有工具都延迟：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "All tools have defer_loading set. At least one tool must be non-deferred."
  }
}

缺少工具定义：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' has no corresponding tool definition"
  }
}

工具结果错误（200 状态）

工具执行期间的错误返回 200 响应，错误信息在正文中：

{
  "type": "tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_pattern"
  }
}

错误代码：

• too_many_requests：工具搜索操作的速率限制已超出
• invalid_pattern：格式错误的正则表达式模式
• pattern_too_long：模式超过 200 个字符限制
• unavailable：工具搜索服务暂时不可用

常见错误

提示缓存

有关 defer_loading 如何保留提示缓存的信息，请参阅带提示缓存的工具使用。

系统会自动在整个对话历史中扩展 tool_reference 块，因此 Claude 可以在后续轮次中重用发现的工具，而无需重新搜索。

流式传输

启用流式传输后，您将在流中接收工具搜索事件：

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 query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"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

批处理请求

您可以在消息批处理 API 中包含工具搜索工具。通过消息批处理 API 的工具搜索操作的定价与常规消息 API 请求中的定价相同。

数据保留

服务器端工具搜索（tool_search 工具）索引和存储工具目录数据（工具名称、描述和参数元数据），超出立即 API 响应的范围；此目录数据根据 Anthropic 的标准保留政策保留。使用标准消息 API 的自定义客户端工具搜索实现完全符合 ZDR 资格。

有关所有功能的 ZDR 资格，请参阅 API 和数据保留。

限制和最佳实践

限制

• 最大工具数： 目录中最多 10,000 个工具
• 搜索结果： 每次搜索返回 3-5 个最相关的工具
• 模式长度： 正则表达式模式最多 200 个字符
• 模型支持： Claude Mythos Preview、Sonnet 4.0+、Opus 4.0+ 仅支持（不支持 Haiku）

何时使用工具搜索

良好的用例：

• 系统中有 10+ 个工具可用
• 工具定义消耗 >10k 个令牌
• 在大型工具集中遇到工具选择准确性问题
• 构建具有多个服务器的 MCP 驱动系统（200+ 个工具）
• 工具库随时间增长

传统工具调用可能更好的情况：

• 总共少于 10 个工具
• 所有工具在每个请求中都频繁使用
• 非常小的工具定义（总共 <100 个令牌）

优化提示

• 将最常用的 3-5 个工具保持为非延迟
• 编写清晰、描述性的工具名称和描述
• 在工具名称中使用一致的命名空间：按服务或资源前缀（例如 github_、slack_），以便搜索查询自然地呈现正确的工具组
• 在描述中使用与用户描述任务方式相匹配的语义关键字
• 添加系统提示部分，描述可用的工具类别："您可以搜索工具来与 Slack、GitHub 和 Jira 交互"
• 监控 Claude 发现的工具以改进描述

使用情况

工具搜索工具的使用情况在响应使用对象中跟踪：

{
  "usage": {
    "input_tokens": 1024,
    "output_tokens": 256,
    "server_tool_use": {
      "tool_search_requests": 2
    }
  }
}

后续步骤