工具搜索工具

摘要

工具搜索工具允许 Claude 通过按需动态发现和延迟加载机制，高效处理多达上万个工具，从而大幅节省上下文空间（解决 50 个工具消耗 10-20K token 的问题）并提高工具选择的准确性。

工作机制：通过为工具设置 defer_loading: true 实现延迟加载，Claude 搜索后 API 会返回 3-5 个最相关的 tool_reference 块，并自动展开为完整的工具定义。
搜索变体：提供两种内置服务器端搜索方式：正则表达式（regex_20251119，最大查询长度 200 字符）和 BM25 自然语言搜索（bm25_20251119）。
容量与模型限制：工具目录最多支持 10,000 个工具；目前仅支持 Sonnet 4.0+ 和 Opus 4.0+ 模型（不支持 Haiku）。
最佳实践：建议将 3-5 个最常用的工具保持为非延迟加载；不要将工具搜索工具本身设置为延迟加载，且至少需保留一个非延迟加载工具。
自定义实现：可通过返回包含 tool_reference 块的标准 tool_result，在客户端实现自定义搜索逻辑（如向量/语义搜索）。
生态兼容性：支持与 MCP 服务器集成，并兼容提示缓存、流式传输和批量请求。

正文

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

这种方法解决了工具库规模扩大时的两个关键挑战：

上下文效率：工具定义可能消耗上下文窗口的大量空间（50 个工具 ≈ 10-20K token），留给实际工作的空间更少
工具选择准确性：当常规可用工具超过 30-50 个时，Claude 正确选择工具的能力会显著下降

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

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

服务器端工具搜索不适用零数据保留 (ZDR) 协议。数据按照该功能的标准保留策略进行保留。自定义客户端工具搜索实现使用标准 Messages API，符合 ZDR 资格。

在 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 从发现的工具中选择并调用它们

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

快速开始

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

Shell

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
            }
        ]
    }'

工具定义

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

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）都会搜索工具名称、描述、参数名称和参数描述。

响应格式

当 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 集成

工具搜索工具可与 MCP 服务器配合使用。在您的 API 请求中添加 "mcp-client-2025-11-20" Beta 请求头，然后使用 mcp_toolset 配合 default_config 来延迟加载 MCP 工具：

Shell

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-4-6",
    "max_tokens": 2048,
    "mcp_servers": [
      {
        "type": "url",
        "name": "database-server",
        "url": "https://mcp-db.example.com"
      }
    ],
    "tools": [
      {
        "type": "tool_search_tool_regex_20251119",
        "name": "tool_search_tool_regex"
      },
      {
        "type": "mcp_toolset",
        "mcp_server_name": "database-server",
        "default_config": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

MCP 配置选项：

default_config.defer_loading：为 MCP 服务器的所有工具设置默认值
configs：按名称覆盖特定工具的默认设置
将多个 MCP 服务器与工具搜索结合使用，以支持大规模工具库

自定义工具搜索实现

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

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_reference 内容块的标准 tool_result 格式。

有关使用嵌入的完整示例，请参阅我们的使用嵌入的工具搜索 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：工具搜索服务暂时不可用

提示缓存

工具搜索可与提示缓存配合使用。添加 cache_control 断点以优化多轮对话：

Python

import anthropic

client = anthropic.Anthropic()

# 第一个带工具搜索的请求
messages = [{"role": "user", "content": "What's the weather in Seattle?"}]

response1 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=2048,
    messages=messages,
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
            "defer_loading": True,
        },
    ],
)

# 将 Claude 的响应添加到对话中
messages.append({"role": "assistant", "content": response1.content})

# 带缓存断点的第二个请求
messages.append(
    {
        "role": "user",
        "content": "What about New York?",
        "cache_control": {"type": "ephemeral"},
    }
)

response2 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=2048,
    messages=messages,
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
            "defer_loading": True,
        },
    ],
)

print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

系统会自动在整个对话历史中展开 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 继续使用已发现的工具

批量请求

您可以在 Messages Batches API 中包含工具搜索工具。通过 Messages Batches API 进行的工具搜索操作与常规 Messages API 请求中的定价相同。

限制和最佳实践

限制

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

何时使用工具搜索

适用场景：

系统中有 10 个以上的工具
工具定义消耗超过 10K token
大型工具集出现工具选择准确性问题
构建具有多个服务器的 MCP 驱动系统（200+ 工具）
工具库随时间不断增长

传统工具调用可能更好的场景：

总共少于 10 个工具
每个请求都频繁使用所有工具
工具定义非常小（总共 <100 token）

优化建议

将 3-5 个最常用的工具保持为非延迟加载
编写清晰、描述性的工具名称和描述
在描述中使用与用户描述任务方式匹配的语义关键词
添加描述可用工具类别的系统提示部分：“您可以搜索与 Slack、GitHub 和 Jira 交互的工具”
监控 Claude 发现了哪些工具以优化描述

用量

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

JSON

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

wsl-docs

探索

工具搜索工具

摘要

正文

工具搜索的工作原理

快速开始

工具定义

延迟工具加载

响应格式

理解响应

MCP 集成

自定义工具搜索实现

错误处理

HTTP 错误（400 状态码）

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

提示缓存

流式传输

批量请求

限制和最佳实践

限制

何时使用工具搜索

优化建议

用量

相关文档

关联主题

关系图谱

目录

反向链接