工具

工具搜尋工具

使用工具搜尋工具讓 Claude 能夠動態發現和按需加載數百或數千個工具

工具搜尋工具使 Claude 能夠通過動態發現和按需加載工具來處理數百或數千個工具。與其將所有工具定義預先加載到上下文窗口中，Claude 會搜尋您的工具目錄（包括工具名稱、描述、參數名稱和參數描述），並僅加載它需要的工具。

隨著工具庫的擴展，此方法解決了兩個關鍵挑戰：

上下文效率：工具定義可能會消耗您上下文窗口的大部分（50 個工具 ≈ 10-20K 個令牌），留下較少的空間用於實際工作
工具選擇準確性：Claude 在超過 30-50 個常規可用工具時，正確選擇工具的能力會顯著下降

雖然這是作為伺服器端工具提供的，但您也可以實現自己的客戶端工具搜尋功能。有關詳細信息，請參閱自訂工具搜尋實現。

工具搜尋工具目前處於公開測試版。為您的提供商包含適當的測試版標頭：

提供商	測試版標頭	支援的模型
Claude API Microsoft Foundry	`advanced-tool-use-2025-11-20`	Claude Opus 4.5 Claude Sonnet 4.5
Google Cloud 的 Vertex AI	`tool-search-tool-2025-10-19`	Claude Opus 4.5 Claude Sonnet 4.5
Amazon Bedrock	`tool-search-tool-2025-10-19`	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_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 伺服器。將 "mcp-client-2025-11-20" 測試版標頭添加到您的 API 請求中，然後使用帶有 default_config 的 mcp_toolset 來延遲加載 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_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 塊來實現自己的工具搜尋邏輯（例如使用嵌入或語義搜尋）：

JSON

{
  "type": "tool_search_tool_result",
  "tool_use_id": "toolu_custom_search",
  "content": {
    "type": "tool_search_tool_search_result",
    "tool_references": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
  }
}

每個被參考的工具必須在頂級 tools 參數中有相應的工具定義，並設置 defer_loading: true。此方法讓您可以使用更複雜的搜尋演算法，同時保持與工具搜尋系統的相容性。

有關使用嵌入的完整示例，請參閱我們的帶有嵌入的工具搜尋食譜。

錯誤處理

工具搜尋工具與工具使用示例不相容。如果您需要提供工具使用示例，請使用不帶工具搜尋的標準工具調用。

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_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 請求中的定價相同。

限制和最佳實踐

限制

最大工具數：您的目錄中最多 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 個令牌），留下較少的空間用於實際工作
工具選擇準確性：Claude 在超過 30-50 個常規可用工具時，正確選擇工具的能力會顯著下降

雖然這是作為伺服器端工具提供的，但您也可以實現自己的客戶端工具搜尋功能。有關詳細信息，請參閱自訂工具搜尋實現。

工具搜尋工具目前處於公開測試版。為您的提供商包含適當的測試版標頭：

提供商	測試版標頭	支援的模型
Claude API Microsoft Foundry	`advanced-tool-use-2025-11-20`	Claude Opus 4.5 Claude Sonnet 4.5
Google Cloud 的 Vertex AI	`tool-search-tool-2025-10-19`	Claude Opus 4.5 Claude Sonnet 4.5
Amazon Bedrock	`tool-search-tool-2025-10-19`	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_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 調用發現的工具

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_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 塊來實現自己的工具搜尋邏輯（例如使用嵌入或語義搜尋）：

JSON

{
  "type": "tool_search_tool_result",
  "tool_use_id": "toolu_custom_search",
  "content": {
    "type": "tool_search_tool_search_result",
    "tool_references": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
  }
}

有關使用嵌入的完整示例，請參閱我們的帶有嵌入的工具搜尋食譜。

錯誤處理

工具搜尋工具與工具使用示例不相容。如果您需要提供工具使用示例，請使用不帶工具搜尋的標準工具調用。

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_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 請求中的定價相同。

限制和最佳實踐

限制

最大工具數：您的目錄中最多 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 找不到預期的工具

提示快取

串流

批次請求

限制和最佳實踐

限制

何時使用工具搜尋

優化提示

使用和定價