工具基礎設施

工具搜尋工具

了解如何使用工具搜尋工具讓 Claude 動態發現和載入工具。

工具搜尋工具使 Claude 能夠透過動態發現和按需載入來處理數百或數千個工具。Claude 不需要預先將所有工具定義載入到上下文視窗中，而是搜尋您的工具目錄——包括工具名稱、描述、參數名稱和參數描述——並僅載入它需要的工具。

這種方法解決了工具庫規模擴大時的兩個關鍵挑戰：

上下文效率：工具定義可能佔用上下文視窗的大量空間（50 個工具 ≈ 10-20K tokens），留給實際工作的空間更少
工具選擇準確性：當傳統可用工具超過 30-50 個時，Claude 正確選擇工具的能力會顯著下降

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

請透過我們的意見回饋表單分享您對此功能的意見。

伺服器端工具搜尋不包含在零資料保留 (ZDR) 安排中。資料會根據該功能的標準保留政策進行保留。自訂客戶端工具搜尋實作使用標準 Messages API，符合 ZDR 資格。

在 Amazon Bedrock 上，伺服器端工具搜尋僅可透過 invoke API 使用，不支援 converse 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 "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
            }
        ]
    }'

工具定義

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

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 伺服器配合使用。在您的 API 請求中添加 "mcp-client-2025-11-20" beta 標頭，然後使用 mcp_toolset 搭配 default_config 來延遲載入 MCP 工具：

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-4-6",
    "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 區塊。當 Claude 呼叫您的自訂搜尋工具時，返回一個標準的 tool_result，其中 content 陣列包含 tool_reference 區塊：

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：工具搜尋服務暫時不可用

常見錯誤

提示快取

工具搜尋可與提示快取配合使用。添加 cache_control 斷點以最佳化多輪對話：

Python

import anthropic

client = anthropic.Anthropic()

# First request with tool search
messages = [{"role": "user", "content": "What's the weather in Seattle?"}]

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

# Add Claude's response to conversation
messages.append({"role": "assistant", "content": response1.content})

# Second request with cache breakpoint
messages.append(
    {
        "role": "user",
        "content": "What about New York?",
        "cache_control": {"type": "ephemeral"},
    }
)

response2 = client.messages.create(
    model="claude-opus-4-6",
    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"}}

// 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 個字元
模型支援：僅限 Sonnet 4.0+、Opus 4.0+（不支援 Haiku）

何時使用工具搜尋

適合的使用場景：

系統中有 10 個以上的工具
工具定義消耗超過 10K tokens
大型工具集遇到工具選擇準確性問題
建構具有多個伺服器的 MCP 驅動系統（200+ 個工具）
工具庫隨時間增長

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

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

最佳化提示

將最常用的 3-5 個工具保持為非延遲載入
撰寫清晰、描述性的工具名稱和描述
在描述中使用與使用者描述任務方式相匹配的語義關鍵字
添加系統提示部分描述可用的工具類別：「您可以搜尋工具來與 Slack、GitHub 和 Jira 互動」
監控 Claude 發現了哪些工具以改進描述

使用量

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

JSON

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

Was this page helpful?

工具基礎設施

工具搜尋工具

了解如何使用工具搜尋工具讓 Claude 動態發現和載入工具。

這種方法解決了工具庫規模擴大時的兩個關鍵挑戰：

上下文效率：工具定義可能佔用上下文視窗的大量空間（50 個工具 ≈ 10-20K tokens），留給實際工作的空間更少
工具選擇準確性：當傳統可用工具超過 30-50 個時，Claude 正確選擇工具的能力會顯著下降

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

請透過我們的意見回饋表單分享您對此功能的意見。

在 Amazon Bedrock 上，伺服器端工具搜尋僅可透過 invoke API 使用，不支援 converse 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 "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
            }
        ]
    }'

工具定義

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

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: mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-4-6",
    "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 伺服器與工具搜尋以支援大型工具庫

自訂工具搜尋實作

JSON

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

如需使用嵌入向量的完整範例，請參閱我們的使用嵌入向量的工具搜尋 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：工具搜尋服務暫時不可用

常見錯誤

提示快取

工具搜尋可與提示快取配合使用。添加 cache_control 斷點以最佳化多輪對話：

Python

import anthropic

client = anthropic.Anthropic()

# First request with tool search
messages = [{"role": "user", "content": "What's the weather in Seattle?"}]

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

# Add Claude's response to conversation
messages.append({"role": "assistant", "content": response1.content})

# Second request with cache breakpoint
messages.append(
    {
        "role": "user",
        "content": "What about New York?",
        "cache_control": {"type": "ephemeral"},
    }
)

response2 = client.messages.create(
    model="claude-opus-4-6",
    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"}}

// 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 個字元
模型支援：僅限 Sonnet 4.0+、Opus 4.0+（不支援 Haiku）

何時使用工具搜尋

適合的使用場景：

系統中有 10 個以上的工具
工具定義消耗超過 10K tokens
大型工具集遇到工具選擇準確性問題
建構具有多個伺服器的 MCP 驅動系統（200+ 個工具）
工具庫隨時間增長

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

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

最佳化提示

將最常用的 3-5 個工具保持為非延遲載入
撰寫清晰、描述性的工具名稱和描述
在描述中使用與使用者描述任務方式相匹配的語義關鍵字
添加系統提示部分描述可用的工具類別：「您可以搜尋工具來與 Slack、GitHub 和 Jira 互動」
監控 Claude 發現了哪些工具以改進描述

使用量

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

JSON

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

Was this page helpful?

工具搜尋的運作方式

快速開始

工具定義

延遲工具載入

回應格式

理解回應

MCP 整合

自訂工具搜尋實作

錯誤處理

HTTP 錯誤（400 狀態碼）

工具結果錯誤（200 狀態碼）

常見錯誤

400 錯誤：所有工具都被延遲載入

400 錯誤：缺少工具定義

Claude 找不到預期的工具

提示快取

串流

批次請求

限制與最佳實踐

限制

何時使用工具搜尋

最佳化提示

使用量

工具搜尋的運作方式

快速開始

工具定義

延遲工具載入

回應格式

理解回應

MCP 整合

自訂工具搜尋實作

錯誤處理

HTTP 錯誤（400 狀態碼）

工具結果錯誤（200 狀態碼）

常見錯誤

400 錯誤：所有工具都被延遲載入

400 錯誤：缺少工具定義

Claude 找不到預期的工具

提示快取

串流

批次請求

限制與最佳實踐

限制

何時使用工具搜尋

最佳化提示

使用量