工具
工具搜尋工具
了解如何使用工具搜尋工具讓 Claude 動態發現和載入數百或數千個工具。
工具搜尋工具使 Claude 能夠通過動態發現和按需載入工具來處理數百或數千個工具。與其將所有工具定義預先載入到上下文窗口中，Claude 會搜尋您的工具目錄（包括工具名稱、描述、參數名稱和參數描述），並僅載入它需要的工具。
隨著工具庫的擴展，這種方法解決了兩個關鍵挑戰：
- 上下文效率：工具定義可能會消耗上下文窗口的大量部分（50 個工具 ≈ 10-20K 個令牌），留下較少的空間用於實際工作
- 工具選擇準確性：Claude 在超過 30-50 個常規可用工具時，正確選擇工具的能力會顯著下降
雖然這是作為伺服器端工具提供的，但您也可以實現自己的客戶端工具搜尋功能。有關詳細信息，請參閱自訂工具搜尋實現。
平台和模型支援
平台和模型支援
| 平台 | 支援的模型 |
|---|---|
| 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 提供，不支援反向 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 伺服器。將 "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。這種方法讓您可以使用更複雜的搜尋演算法，同時保持與工具搜尋系統的相容性。
有關使用嵌入的完整示例，請參閱我們的帶有嵌入的工具搜尋食譜。
錯誤處理
錯誤處理
工具搜尋工具與工具使用示例不相容。 如果您需要提供工具使用示例，請使用不帶工具搜尋的標準工具調用。
HTTP 錯誤（400 狀態）
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 狀態）
工具執行期間的錯誤返回 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 繼續使用發現的工具批次請求
批次請求
您可以在 Messages Batches API 中包含工具搜尋工具。通過 Messages Batches API 進行的工具搜尋操作的定價與常規 Messages 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
}
}
}有關目前定價信息，請參閱定價頁面。