工具搜尋工具

工具搜尋工具讓 Claude 能夠透過按需探索與載入工具，來處理數百或數千個工具。Claude 不會預先將所有工具定義載入「context window」（上下文視窗），而是搜尋您的工具目錄（包括工具名稱、描述、參數名稱與參數描述），並僅載入所需的工具。

隨著工具庫的成長，預先載入每個工具定義會造成兩個問題：

• 上下文膨脹： 典型的多伺服器設定（GitHub、Slack、Sentry、Grafana 與 Splunk）在 Claude 開始任何工作之前，光是定義就可能消耗約 55k 個 token。工具搜尋通常可將此減少超過 85%，僅載入 Claude 針對特定請求所需的 3–5 個工具。
• 工具選擇準確度： 一旦可用工具超過 30–50 個，Claude 挑選正確工具的能力就會下降。由於工具搜尋僅按需載入一組聚焦的相關工具，即使面對數千個工具，選擇準確度仍能維持在高水準。

關於支援工具搜尋的模型，請參閱模型相容性。

工具搜尋以伺服器端工具的形式執行，但您也可以實作自己的用戶端工具搜尋。詳情請參閱自訂工具搜尋實作。



模型相容性

兩種工具搜尋變體皆可在下列模型上使用：

Claude Opus 4.1 及更早的模型不支援工具搜尋工具。



工具搜尋的運作方式

工具搜尋有兩種變體：

• Regex（tool_search_tool_regex_20251119）：Claude 建構正規表示式模式來搜尋工具。
• BM25（tool_search_tool_bm25_20251119）：Claude 使用自然語言查詢來搜尋工具。

當您啟用工具搜尋工具時：

1. 您在 tools 清單中加入一個工具搜尋工具（例如 tool_search_tool_regex_20251119 或 tool_search_tool_bm25_20251119）。
2. 您在 tools 陣列中提供每個工具定義，並在不應預先載入的工具上設定 defer_loading: true。至少必須有一個工具（通常是工具搜尋工具本身）保持非延遲狀態。
3. 一開始，Claude 的上下文僅包含工具搜尋工具以及任何非延遲的工具。
4. 當 Claude 需要額外的工具時，它會使用工具搜尋工具進行搜尋。
5. API 執行搜尋並以 tool_reference 區塊的形式回傳相符的工具（預設最多 5 個；Claude 可在其搜尋輸入中設定 limit）。
6. API 自動將這些參照展開為完整的工具定義。
7. Claude 從探索到的工具中進行選擇並呼叫它們。



快速開始

以下範例包含工具搜尋工具與兩個延遲載入的工具：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    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,
        },
    ],
)

print(response)

Claude 搜尋目錄、探索到 get_weather 並呼叫它。回應以 stop_reason: "tool_use" 結束。請依照處理工具呼叫中的方式執行探索到的工具並回傳 tool_result。回應格式說明了您會收到的區塊以及接下來要傳送的內容。



工具定義

工具搜尋工具有兩種變體：

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}



延遲工具載入

透過加入 defer_loading: true 將工具標記為按需載入：

{
  "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 控制的是進入上下文視窗的內容，而非您在請求中傳送的內容：

• 您仍需在每次請求的 tools 陣列中傳送每個工具的完整定義，包括延遲載入的工具。API 需要在伺服器端使用它們來執行搜尋並展開 tool_reference 區塊。
• 沒有 defer_loading 的工具會立即載入上下文。
• 設有 defer_loading: true 的工具僅在 Claude 透過搜尋探索到它們時才會載入。
• 切勿在工具搜尋工具本身設定 defer_loading: true。
• 將您最常使用的 3–5 個工具保持為非延遲狀態，讓 Claude 無需先搜尋即可呼叫它們。

電腦使用與瀏覽器使用工具集（computer_toolset_20260801 與 browser_toolset_20260801）是在項目的 configs 物件內針對每個成員工具設定 defer_loading，而非在項目本身設定；在項目層級設定它的請求會被拒絕。由於工具集是以整體為單位進行延遲與展開，defer_loading 在每個已啟用的成員上必須解析為相同的值，且當 Claude 透過搜尋探索到該工具集時，所有已啟用的成員會一次全部載入。關於 configs 格式，請參閱用戶端工具集。

兩種工具搜尋變體（regex 與 bm25）皆會搜尋工具名稱、描述、參數名稱與參數描述。

在內部，API 會將延遲載入的工具排除在系統提示前綴之外。當 Claude 透過工具搜尋探索到延遲載入的工具時，API 會在對話中內嵌附加一個 tool_reference 區塊，然後在傳遞給 Claude 之前將其展開為完整的工具定義。前綴保持不變，因此「prompt caching」（提示快取）得以保留。嚴格模式的文法（將工具呼叫輸出限制為符合您結構描述的規則）是從完整工具集建構的，因此 defer_loading 與嚴格模式可以組合使用而無需重新編譯文法。



回應格式

當 Claude 使用工具搜尋工具時，回應會包含下列區塊類型：

{
  "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": {
        "pattern": "weather",
        "limit": 10
      }
    },
    {
      "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 對工具搜尋工具的呼叫。搜尋在 Anthropic 的伺服器上執行。切勿針對其 srvtoolu_... ID 回傳 tool_result。input 包含搜尋內容（regex 變體為 pattern，BM25 為 query），並可能包含選用的 limit，這是一個介於 1 到 10,000 之間的整數，用於限制搜尋回傳的相符工具數量（預設：5）。
• tool_search_tool_result： 搜尋結果，位於巢狀的 tool_search_tool_search_result 物件中。請將其原樣保留在訊息歷史中。
• tool_references： 指向已探索工具的 tool_reference 物件陣列。API 會為 Claude 展開這些參照。您永遠不需要自行展開它們。
• tool_use： Claude 對已探索工具的呼叫。請執行它並回傳 tool_result，方式與標準工具使用完全相同。

API 會在向 Claude 顯示之前，自動將 tool_reference 區塊展開為完整的工具定義。只要您在 tools 參數中提供所有相符的工具定義，就不需要自行處理此展開。



繼續對話

在下一次請求中，請原封不動地傳回助理的內容，包括 server_tool_use 與 tool_search_tool_result 區塊。在使用者訊息中加入您針對已探索工具的 tool_result，並傳送相同的 tools 陣列：搜尋工具加上每個延遲載入的定義。請勿針對 srvtoolu_... ID 回傳 tool_result：API 會拒絕該請求。API 會在整個對話歷史中展開 tool_reference 區塊，因此 Claude 可以在後續回合中重複使用已探索的工具而無需重新搜尋。沒有任何相符結果的搜尋會回傳一個 tool_references 陣列為空的 tool_search_tool_search_result，而非錯誤。



MCP 整合

如果您的工具是透過 MCP 連接器來自 MCP 伺服器，則不需要在個別工具定義上設定 defer_loading。請改為在 mcp_toolset 項目的 default_config 上為整個伺服器設定一次，或在其 configs 中針對每個工具設定。請參閱 MCP 工具集設定。



自訂工具搜尋實作

您可以透過從自訂工具回傳 tool_reference 區塊，來實作自己的工具搜尋邏輯（例如使用嵌入向量或語意搜尋）。當 Claude 呼叫您的自訂搜尋工具時，請回傳一個標準的 tool_result，並在內容陣列中包含 tool_reference 區塊：

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

每個被參照的工具都必須在頂層 tools 參數中有對應的工具定義，通常設有 defer_loading: true。這讓您能夠使用內建變體未提供的搜尋方法，例如基於嵌入向量的檢索，而 API 會以相同方式展開回傳的 tool_reference 區塊。

關於使用嵌入向量的完整範例，請參閱使用嵌入向量的工具搜尋範例。



錯誤處理



HTTP 錯誤（400 狀態）

這些錯誤會阻止 API 處理請求：

所有工具皆為延遲載入：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "At least one tool must have defer_loading=false. All tools cannot be deferred."
  }
}

缺少工具定義：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' not found in available tools"
  }
}



工具結果錯誤（200 狀態）

當工具搜尋操作在執行期間失敗時，API 會回傳 200 回應，並在主體中包含錯誤：

{
  "type": "tool_search_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_tool_input",
    "error_message": "Invalid regular expression pattern: missing ) at position 1"
  }
}

error_code 欄位有四個可能的值：

• invalid_tool_input：搜尋輸入無效，例如格式錯誤的正規表示式模式，或超過 200 字元上限的模式
• unavailable：搜尋無法執行，例如因為逾時或服務無法使用
• too_many_requests：工具搜尋操作超過速率限制
• execution_time_exceeded：搜尋超過其執行時間上限



常見錯誤



提示快取

關於 defer_loading 如何保留提示快取，請參閱搭配提示快取的工具使用。

設有 defer_loading: true 的工具不能同時帶有 cache_control：API 會回傳 400。請將快取斷點放在非延遲的工具上。



串流

啟用「streaming」（串流）後，您會在串流中收到工具搜尋事件：

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

// Search pattern streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"pattern\":\"weather\"}"}}

// Pause while search executes

// Search results streamed
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 continues with discovered tools



批次請求

您可以在 Messages Batches API 中加入工具搜尋工具。



限制與最佳實務



限制

• 延遲工具數量上限： 每次請求最多 10,000 個設有 defer_loading: true 的工具
• 搜尋結果： 每次搜尋預設最多回傳 5 個相符的工具；Claude 可在其搜尋輸入中將 limit 設定為 1 到 10,000 之間的任意整數
• 模式與查詢長度： 正規表示式模式上限為 200 個字元，BM25 查詢上限為 500 個字元
• 模型支援： 請參閱模型相容性



何時使用工具搜尋

當符合下列任一情況時，請使用工具搜尋：

• 您有 10 個或更多可用工具。
• 您的工具定義消耗超過 10k 個 token。
• 隨著工具集成長，工具選擇準確度下降。
• 您彙整了多個 MCP 伺服器（200 個以上的工具）。
• 您的工具庫會隨時間成長。

當您的工具少於 10 個、每個工具在每次請求中都會使用，或您的工具定義很小（總計少於 100 個 token）時，不使用工具搜尋的標準工具呼叫會更為合適。



最佳化提示

• 將您最常使用的 3–5 個工具保持為非延遲狀態。
• 撰寫清晰、具描述性的工具名稱與描述。
• 在工具名稱中使用一致的命名空間：以服務或資源作為前綴（例如 github_、slack_），讓一次搜尋即可比對整個群組。
• 在描述中使用符合使用者描述任務方式的關鍵字。
• 加入一段描述可用工具類別的系統提示：「You can search for tools to interact with Slack, GitHub, and Jira.」
• 監控 Claude 探索到哪些工具，以改進您的描述。



用量

工具搜尋不會作為獨立的伺服器工具計量。回應的 usage.server_tool_use 物件沒有工具搜尋欄位，而搜尋載入上下文的工具定義會像任何其他工具定義一樣計為輸入 token。



後續步驟