工具搜尋工具

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

此方法解決了隨著工具庫規模擴大而迅速加劇的兩個問題：

• 上下文膨脹： 工具定義會快速消耗您的上下文預算。典型的多伺服器配置（GitHub、Slack、Sentry、Grafana、Splunk）在 Claude 執行任何實際工作之前，光是定義就可能消耗約 55k 個 token。工具搜尋通常可將此減少超過 85%，僅載入 Claude 處理特定請求實際需要的 3–5 個工具。
• 工具選擇準確度： 一旦可用工具超過 30–50 個，Claude 正確選擇工具的能力會顯著下降。透過按需呈現一組聚焦的相關工具，工具搜尋即使在數千個工具中也能保持高選擇準確度。

雖然這是以伺服器端工具的形式提供，但您也可以實作自己的用戶端工具搜尋功能。詳情請參閱自訂工具搜尋實作。



工具搜尋的運作方式

工具搜尋有兩種變體：

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

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

1. 您在工具清單中包含一個工具搜尋工具（例如 tool_search_tool_regex_20251119 或 tool_search_tool_bm25_20251119）。
2. 您為不應立即載入的工具提供所有工具定義，並設定 defer_loading: true。
3. Claude 最初只會看到工具搜尋工具和任何非延遲載入的工具。
4. 當 Claude 需要其他工具時，它會使用工具搜尋工具進行搜尋。
5. API 會回傳 3-5 個最相關的 tool_reference 區塊。
6. 這些參照會自動展開為完整的工具定義。
7. Claude 從探索到的工具中進行選擇並呼叫它們。

這能保持您的上下文視窗高效運作，同時維持高工具選擇準確度。



快速入門

以下是使用延遲載入工具的簡單範例：

client = anthropic.Anthropic()

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



工具定義

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

{
  "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 的工具會立即載入上下文
• 設定 defer_loading: true 的工具只有在 Claude 透過搜尋探索到它們時才會載入
• 工具搜尋工具本身絕不應設定 defer_loading: true
• 將您最常使用的 3-5 個工具保持為非延遲載入，以獲得最佳效能

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

延遲載入的內部運作方式： 延遲載入的工具不會包含在系統提示前綴中。當模型透過工具搜尋探索到延遲載入的工具時，API 會在對話中內嵌附加一個 tool_reference 區塊，然後在傳遞給 Claude 之前將其展開為完整的工具定義。前綴不會被更動，因此提示快取得以保留。嚴格模式的語法（限制工具呼叫輸出以符合您的結構描述的規則）是從完整工具集建構的，因此 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": {
        "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 連接器。



自訂工具搜尋實作

您可以透過從自訂工具回傳 tool_reference 區塊，實作自己的工具搜尋邏輯（例如使用嵌入或語意搜尋）。當 Claude 呼叫您的自訂搜尋工具時，回傳一個標準的 tool_result，並在 content 陣列中包含 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。此方法讓您能使用更精密的搜尋演算法，同時保持與工具搜尋系統的相容性。

如需使用嵌入的完整範例，請參閱 tool search with embeddings 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 回應，並在主體中包含錯誤資訊：

{
  "type": "tool_search_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"}}

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"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 中包含工具搜尋工具。透過 Messages Batches API 進行的工具搜尋操作，其定價與一般 Messages API 請求相同。



限制與最佳實務



限制

• 工具數量上限： 您的目錄中最多 10,000 個工具
• 搜尋結果： 每次搜尋回傳 3-5 個最相關的工具
• 模式長度： 正規表示式模式最多 200 個字元
• 模型支援： Claude Mythos Preview、Sonnet 4.0+、Opus 4.0+、Haiku 4.5+



何時使用工具搜尋

適合的使用情境：

• 您的系統中有 10 個以上的可用工具
• 工具定義消耗超過 10k 個 token
• 在大型工具集中遇到工具選擇準確度問題
• 建構具有多個伺服器（200 個以上工具）的 MCP 驅動系統
• 工具庫隨時間持續增長

傳統工具呼叫可能更適合的情況：

• 總共少於 10 個工具
• 每個請求都會頻繁使用所有工具
• 工具定義非常小（總計 <100 個 token）



最佳化提示

• 將最常使用的 3-5 個工具保持為非延遲載入
• 撰寫清晰、具描述性的工具名稱和描述
• 在工具名稱中使用一致的命名空間：依服務或資源加上前綴（例如 github_、slack_），讓搜尋查詢自然地呈現正確的工具群組
• 在描述中使用與使用者描述任務方式相符的語意關鍵字
• 新增一個系統提示章節來描述可用的工具類別：「您可以搜尋與 Slack、GitHub 和 Jira 互動的工具」
• 監控 Claude 探索到哪些工具，以改進描述



使用量

工具搜尋工具的使用量會在回應的 usage 物件中追蹤：

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



後續步驟