工具搜尋工具

工具搜尋工具讓 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 區塊來實作客戶端工具搜尋。

工具搜尋的運作方式

工具搜尋有兩種變體：

Regex（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"
}

Regex 變體查詢格式：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 connector。

自訂工具搜尋實作

您可以透過從自訂工具返回 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 繼續使用已發現的工具

批次請求

您可以在 Messages Batches API 中包含工具搜尋工具。透過 Messages Batches API 進行的工具搜尋操作與一般 Messages API 請求的定價相同。

資料保留

伺服器端工具搜尋（tool_search 工具）會在即時 API 回應之外索引並儲存工具目錄資料（工具名稱、描述和參數元資料）；此目錄資料根據 Anthropic 的標準保留政策進行保留。使用標準 Messages 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 connector

使用延遲載入設定 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 找不到預期的工具

提示快取

串流

批次請求

資料保留

限制與最佳實踐

限制

何時使用工具搜尋

最佳化提示

使用量

後續步驟