工具搜索工具

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

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

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

有关工具搜索所解决的扩展挑战的背景信息，请参阅 Advanced tool use。工具搜索的按需加载也是 Effective context engineering 中描述的更广泛的即时检索原则的一个实例。

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

请通过反馈表单分享您对此功能的反馈。

This feature qualifies for Zero Data Retention (ZDR) with limited technical retention. See the Data retention section for details on what is retained and why.

在 Amazon Bedrock 上，服务器端工具搜索仅通过 invoke API 提供，而非 converse API。

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

工具搜索的工作原理

工具搜索有两种变体：

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

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

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

这使您的上下文窗口保持高效，同时维持较高的工具选择准确性。

快速开始

以下是一个使用延迟工具的简单示例：

工具定义

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

JSON

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

JSON

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

正则表达式变体查询格式：Python 正则表达式，而非自然语言

使用 tool_search_tool_regex_20251119 时，Claude 使用 Python 的 re.search() 语法构建正则表达式模式，而非自然语言查询。常见模式：

"weather" - 匹配名称/描述中包含 "weather" 的工具
"get_.*_data" - 匹配 get_user_data、get_weather_data 等工具
"database.*query|query.*database" - 灵活的 OR 模式
"(?i)slack" - 不区分大小写的搜索

最大查询长度：200 个字符

BM25 变体查询格式：自然语言

使用 tool_search_tool_bm25_20251119 时，Claude 使用自然语言查询来搜索工具。

延迟工具加载

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

JSON

{
  "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 使用工具搜索工具时，响应包含新的块类型：

JSON

{
  "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_reference 块的标准 tool_result：

JSON

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

每个被引用的工具都必须在顶层 tools 参数中有对应的工具定义，并设置 defer_loading: true。这种方法让您可以使用更复杂的搜索算法，同时保持与工具搜索系统的兼容性。

响应格式部分中显示的 tool_search_tool_result 格式是 Anthropic 内置工具搜索在内部使用的服务器端格式。对于自定义客户端实现，请始终使用标准 tool_result 格式，并在内容块中包含 tool_reference，如上所示。

有关使用嵌入的完整示例，请参阅使用嵌入的工具搜索 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 响应，错误信息包含在响应体中：

JSON

{
  "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"}}

// 搜索查询流式传输
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}

// 搜索执行时暂停

// 搜索结果流式传输
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 继续使用已发现的工具

批量请求

您可以在消息批处理 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 个 token
在大型工具集中遇到工具选择准确性问题
构建具有多个服务器（200 个以上工具）的 MCP 驱动系统
工具库随时间增长

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

总共不到 10 个工具
所有工具在每个请求中都频繁使用
工具定义非常小（总计 <100 个 token）

优化技巧

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

使用量

工具搜索工具的使用量在响应使用对象中进行跟踪：

JSON

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

后续步骤

工具参考

包含模型兼容性和参数的完整工具目录。

MCP 连接器

配置具有延迟加载的 MCP 工具集。

提示缓存

将工具搜索与缓存的工具定义结合使用。

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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
            }
        ]
    }'

工具搜索的工作原理

快速开始

工具定义

延迟工具加载

响应格式

理解响应

MCP 集成

自定义工具搜索实现

错误处理

HTTP 错误（400 状态）

工具结果错误（200 状态）

常见错误

400 错误：所有工具均已延迟

400 错误：缺少工具定义

Claude 找不到预期的工具

提示缓存

流式传输

批量请求

数据保留

限制和最佳实践

限制

何时使用工具搜索

优化技巧

使用量

后续步骤