工具

工具搜索工具

使用工具搜索工具让Claude能够动态发现和按需加载数百或数千个工具

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

当工具库扩展时，这种方法解决了两个关键挑战：

上下文效率：工具定义可能会消耗您上下文窗口的大部分（50个工具≈10-20K个令牌），留下较少的空间用于实际工作
工具选择准确性：当传统可用工具超过30-50个时，Claude正确选择工具的能力会显著下降

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

工具搜索工具目前处于公开测试阶段。

要使用此功能，请将"advanced-tool-use-2025-11-20" 测试版标头添加到您的API请求中。

请通过我们的反馈表单分享您对工具搜索工具的体验。

平台和模型支持

平台	支持的模型
Claude API	Claude Opus 4.5, Claude Sonnet 4.5
Microsoft Foundry	Claude Opus 4.5, Claude Sonnet 4.5
Google Cloud Vertex AI	Claude Opus 4.5, Claude Sonnet 4.5
Amazon Bedrock	Claude Opus 4.5

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

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

快速开始

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: advanced-tool-use-2025-11-20" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5-20250929",
        "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_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": [{ "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_result与tool_reference：包含对发现工具的引用的搜索结果
tool_use：Claude调用发现的工具

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

MCP集成

工具搜索工具与MCP服务器配合使用。将"mcp-client-2025-11-20" 测试版标头添加到您的API请求中，然后使用mcp_tool_set与default_configs来延迟加载MCP工具：

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: advanced-tool-use-2025-11-20,mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "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_tool_set",
        "mcp_server_name": "database-server",
        "default_configs": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

MCP配置选项：

default_configs.defer_loading：为来自MCP服务器的所有工具设置默认值
configs：按名称覆盖特定工具的默认值
将多个MCP服务器与工具搜索结合以获得大规模工具库

自定义工具搜索实现

您可以通过从自定义工具返回tool_reference块来实现自己的工具搜索逻辑（例如，使用嵌入或语义搜索）：

JSON

{
  "type": "tool_result",
  "tool_use_id": "toolu_custom_search",
  "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响应，错误信息在正文中：

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.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    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.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    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_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "tool_reference", "tool_name": "get_weather"}]}}

// Claude继续使用发现的工具

批量请求

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

限制和最佳实践

限制

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

何时使用工具搜索

良好用例：

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

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

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

优化提示

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

使用和定价

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

JSON

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

有关当前定价信息，请参阅定价页面。

工具

工具搜索工具

使用工具搜索工具让Claude能够动态发现和按需加载数百或数千个工具

当工具库扩展时，这种方法解决了两个关键挑战：

上下文效率：工具定义可能会消耗您上下文窗口的大部分（50个工具≈10-20K个令牌），留下较少的空间用于实际工作
工具选择准确性：当传统可用工具超过30-50个时，Claude正确选择工具的能力会显著下降

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

工具搜索工具目前处于公开测试阶段。

要使用此功能，请将"advanced-tool-use-2025-11-20" 测试版标头添加到您的API请求中。

请通过我们的反馈表单分享您对工具搜索工具的体验。

平台和模型支持

平台	支持的模型
Claude API	Claude Opus 4.5, Claude Sonnet 4.5
Microsoft Foundry	Claude Opus 4.5, Claude Sonnet 4.5
Google Cloud Vertex AI	Claude Opus 4.5, Claude Sonnet 4.5
Amazon Bedrock	Claude Opus 4.5

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

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

快速开始

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: advanced-tool-use-2025-11-20" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5-20250929",
        "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_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": [{ "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_result与tool_reference：包含对发现工具的引用的搜索结果
tool_use：Claude调用发现的工具

MCP集成

工具搜索工具与MCP服务器配合使用。将"mcp-client-2025-11-20" 测试版标头添加到您的API请求中，然后使用mcp_tool_set与default_configs来延迟加载MCP工具：

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: advanced-tool-use-2025-11-20,mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "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_tool_set",
        "mcp_server_name": "database-server",
        "default_configs": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

MCP配置选项：

default_configs.defer_loading：为来自MCP服务器的所有工具设置默认值
configs：按名称覆盖特定工具的默认值
将多个MCP服务器与工具搜索结合以获得大规模工具库

自定义工具搜索实现

您可以通过从自定义工具返回tool_reference块来实现自己的工具搜索逻辑（例如，使用嵌入或语义搜索）：

JSON

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

有关使用嵌入的完整示例，请参阅我们的带嵌入的工具搜索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.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    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.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    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_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "tool_reference", "tool_name": "get_weather"}]}}

// Claude继续使用发现的工具

批量请求

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

限制和最佳实践

限制

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

何时使用工具搜索

良好用例：

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

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

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

优化提示

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

使用和定价

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

JSON

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

有关当前定价信息，请参阅定价页面。

平台和模型支持

工具搜索如何工作

快速开始

工具定义

延迟工具加载

响应格式

理解响应

MCP集成

自定义工具搜索实现

错误处理

HTTP错误（400状态）

工具结果错误（200状态）

常见错误

400错误：所有工具都延迟

400错误：缺少工具定义

Claude找不到预期的工具

提示缓存

流式传输

批量请求

限制和最佳实践

限制

何时使用工具搜索

优化提示

使用和定价

平台和模型支持

工具搜索如何工作

快速开始

工具定义

延迟工具加载

响应格式

理解响应

MCP集成

自定义工具搜索实现

错误处理

HTTP错误（400状态）

工具结果错误（200状态）

常见错误

400错误：所有工具都延迟

400错误：缺少工具定义

Claude找不到预期的工具

提示缓存

流式传输

批量请求

限制和最佳实践

限制

何时使用工具搜索

优化提示

使用和定价