工具搜尋工具

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

隨著工具庫規模的擴大，這種方法解決了兩個複合增長的問題：

• 上下文膨脹： 工具定義會快速消耗您的上下文預算。典型的多伺服器設置（GitHub、Slack、Sentry、Grafana、Splunk）在 Claude 進行任何實際工作之前可能會消耗約 55k 個令牌的定義。工具搜尋通常會將此減少超過 85%，僅加載 Claude 實際需要的 3-5 個工具。
• 工具選擇準確性： 一旦可用工具超過 30-50 個，Claude 正確選擇正確工具的能力會顯著下降。通過按需呈現一組有針對性的相關工具，工具搜尋即使在數千個工具中也能保持高選擇準確性。

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

您也可以通過從自己的搜尋實現返回 tool_reference 塊來實現客戶端工具搜尋。

工具搜尋如何運作

有兩種工具搜尋變體：

• 正則表達式 (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-7",
    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）都搜尋工具名稱、描述、參數名稱和參數描述。

延遲工作原理： 延遲工具不包含在系統提示前綴中。當模型通過工具搜尋發現延遲工具時，工具定義作為 tool_reference 塊內聯附加到對話中。前綴保持不變，因此提示快取得以保留。嚴格模式的語法從完整工具集構建，因此 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，其內容數組中包含 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。這種方法讓您可以使用更複雜的搜尋算法，同時保持與工具搜尋系統的兼容性。

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

錯誤處理

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_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

批次請求

您可以在訊息批次 API 中包含工具搜尋工具。通過訊息批次 API 的工具搜尋操作的定價與常規訊息 API 請求中的相同。

數據保留

伺服器端工具搜尋（tool_search 工具）索引和存儲工具目錄數據（工具名稱、描述和參數元數據），超出立即 API 回應；此目錄數據根據 Anthropic 的標準保留政策保留。使用標準訊息 API 的自訂客戶端工具搜尋實現完全符合 ZDR 資格。

有關所有功能的 ZDR 資格，請參閱 API 和數據保留。

限制和最佳實踐

限制

• 最大工具數： 您的目錄中最多 10,000 個工具
• 搜尋結果： 每次搜尋返回 3-5 個最相關的工具
• 模式長度： 正則表達式模式最多 200 個字符
• 模型支持： Claude Mythos Preview、Sonnet 4.0+、Opus 4.0+ 僅限（不支持 Haiku）

何時使用工具搜尋

良好的使用案例：

• 您的系統中有 10+ 個工具可用
• 工具定義消耗 >10k 個令牌
• 在大型工具集中遇到工具選擇準確性問題
• 構建具有多個伺服器的 MCP 驅動系統（200+ 個工具）
• 工具庫隨時間增長

傳統工具調用可能更好的情況：

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

優化提示

• 將最常用的 3-5 個工具保持為非延遲
• 編寫清晰、描述性的工具名稱和描述
• 在工具名稱中使用一致的命名空間：按服務或資源前綴（例如 github_、slack_），以便搜尋查詢自然地呈現正確的工具組
• 在描述中使用與用戶描述任務方式相匹配的語義關鍵字
• 添加系統提示部分，描述可用的工具類別："您可以搜尋工具來與 Slack、GitHub 和 Jira 交互"
• 監控 Claude 發現的工具以改進描述

使用

工具搜尋工具使用在回應使用對象中被追蹤：

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

後續步驟