Claude Code 的工具搜尋：代理程式如何找到所需的 MCP 工具

如果你已將多個 MCP 伺服器連接到 Claude Code，工具搜尋就能讓它依需求載入所需工具，而不必事先載入所有定義。啟動時，代理程式會收到延後載入工具的名稱和伺服器指示，接著從目錄中搜尋所需項目。這有助於它處理大量工具：Anthropic 的文件指出，一次載入超過 30-50 個工具時，選擇準確度會下降。這是一般性指引，並非對你目前工作階段的測量結果。模型支援時，工具搜尋預設為啟用，但平台、代理伺服器或設定可能會將它停用。

Ailoot 文件：API、金鑰與設定。

未使用工具搜尋時，context 會發生什麼事#

每個連接的 MCP 伺服器都會將其工具加入代理程式可呼叫的項目清單。未使用工具搜尋時，工具定義（名稱、說明和參數結構描述）會預先載入 context。工作階段開始時，伺服器會在背景連線。如果需要使用尚未完成連線的伺服器所提供的工具，Claude Code 會透過內部的 WaitForMcpServers 工具等待。你可以針對每個連線，分別評估特定伺服器會增加多少工具和 token。

Anthropic 的官方文件提供了兩個約略數字（一般性數據，未說明測量方法）：

• 50 個工具可能會占用 1 萬至 2 萬個 context token；
• 一次載入超過 30-50 個工具時，選擇合適工具的準確度會下降。

如何從設定評估工具搜尋#

若要了解工具搜尋是否應在目前工作階段中運作，請檢查下列條件：

• 目前回應所使用的模型 — Sonnet/Haiku/Opus 4.5 或更新版本：可使用此機制；較舊的模型：無法使用；
• ANTHROPIC_BASE_URL 是否設為非標準主機 — 若是，除非透過 ENABLE_TOOL_SEARCH 明確啟用，否則此機制預設為關閉；
• ENABLE_TOOL_SEARCH 變數的值 — false 會完全停用此機制；auto/auto:N 只有在定義的總量達到門檻時才會啟用；
• 是否設定了 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS — 如果沒有組織的受管理設定，即使使用者已設定 ENABLE_TOOL_SEARCH，此變數仍會讓工具搜尋維持關閉；
• 設定中的 permissions.deny 是否封鎖了 ToolSearch 工具 — 這項限制會停用搜尋；
• 使用的平台 — Azure 上的 Microsoft Foundry 部署無法使用此機制；在 Google Cloud Agent Platform 上，其行為則取決於 Claude Code 版本和模型。

這項檢查能讓你根據設定評估狀態，但無法觀察工作階段內的實際情況。Agent SDK 文件的 MCP 章節和工具搜尋章節，並未說明介面中有直接顯示「工具搜尋：開啟/關閉」的指示器。這兩份文件沒有提到此指示器，並不能證明它在其他地方不存在。

例如，你可以在啟動工作階段前設定變數：ENABLE_TOOL_SEARCH=auto:15 claude。若要確保特定伺服器的工具一律載入，請在該伺服器的設定中使用 alwaysLoad: true 欄位。所有伺服器類型都可使用此欄位；其條件和限制詳見下方的 alwaysLoad 章節。

工具搜尋的運作方式#

啟用工具搜尋時，工作階段啟動後載入至 context 的只有延後載入工具的名稱和伺服器指示。伺服器指示會說明該伺服器適用於哪些工作。當某項工作需要尚未載入 context 的功能時，代理程式會自行搜尋目錄，尋找合適的工具。

Agent SDK 文件更詳細地說明了搜尋機制：預設情況下，單次搜尋會從目錄載入最多五個相關性最高的工具。在 SDK 壓縮代理程式找到這些工具時所用的訊息之前，這些工具會在工作階段後續的回合中繼續提供使用。壓縮後，先前探索到的工具可能會從 context 中移除，代理程式會在下次需要時再次搜尋。目錄最多支援 10 000 個工具。Claude Code 本身的 MCP 文件沒有提供這些具體數字，但說明了相同的延後載入原則。

根據 Agent SDK 文件，每次搜尋都會增加一次額外的往返。文件沒有明確說明該往返究竟包含哪些內容。至於 Claude Code，MCP 文件也說明了錯誤回報方面的差異：未使用工具搜尋時，Claude Code 不會將伺服器連線失敗的資訊告知模型。啟用搜尋後，模型會收到哪些伺服器連線失敗，以及錯誤內容為何的資訊。

Claude Code 不會限制單一伺服器可提供的工具數量。實際限制取決於該工作階段的 context window 預算。

設定工具是管理 AI 代理程式 context 的工作之一。

工具搜尋預設為停用的情況#

此機制預設為啟用，但是否運作取決於模型、API 主機和平台。

模型。 工具搜尋需要支援 tool_reference 區塊的模型：Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5 或更新版本。對於較舊的模型，Claude Code 會預先載入工具定義。

API 主機。 當 ANTHROPIC_BASE_URL 變數指向第三方主機時，Claude Code 會停用工具搜尋：大多數代理伺服器不會轉送特殊的 tool_reference 區塊。若你是透過自己的閘道或代理伺服器連接 Claude，而非直接連到 Anthropic 的位址，就適用此情況。停用的原因是使用非標準的 ANTHROPIC_BASE_URL；訂閱付款方式本身不會造成此情況。你可以明確設定 ENABLE_TOOL_SEARCH 來覆寫此行為。如果代理伺服器本身不支援 tool_reference 區塊，強制啟用此機制會導致請求錯誤。在這種情況下，不會改為預先載入定義。

部署平台。 工具搜尋無法在 Azure 上託管的 Microsoft Foundry 部署中運作：伺服器會拒絕請求，而且 ENABLE_TOOL_SEARCH 無法覆寫此限制。在 Google Cloud Agent Platform 上，Claude Code 版本 2.1.221 之前，所有模型的此機制都預設為關閉，除非明確設定 ENABLE_TOOL_SEARCH=true。從該版本起，Opus/Sonnet/Haiku 4.5 或更新版本預設會啟用此機制。對於此平台上較舊的模型，因伺服器基礎架構會拒絕必要的內部標頭，Claude Code 仍會預先載入所有工具。

ENABLE_TOOL_SEARCH 變數有五種可能的設定：

• 未設定 — 標準行為，但不包括上述例外情況；
• true — 在支援此機制的模型上啟用，但有兩種例外情況：Azure Foundry，以及較舊的 Agent Platform 模型；透過不支援 tool_reference 區塊的代理伺服器傳送的請求會失敗；
• auto — 當工具定義的總量占 context window 不到 10% 時，Claude Code 會預先載入工具；達到此門檻後，便切換為延後載入；
• auto:N — 原則相同，但可手動指定百分比門檻；
• false — 完全停用此機制，並預先載入所有工具。

此外還有 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 變數：若已設定，工具搜尋就會維持關閉，使用者設定 ENABLE_TOOL_SEARCH 也不會改變此狀態。例外情況是，自 Claude Code 版本 2.1.227 起，組織可透過受管理設定維持工具搜尋的啟用狀態。

alwaysLoad 的功能及其對 context 和啟動的影響#

伺服器設定中的 alwaysLoad: true 欄位適用於所有伺服器類型。使用後，該伺服器的所有工具都會在啟動時載入至 context，不受 ENABLE_TOOL_SEARCH 設定影響。代理程式不需要在使用前先搜尋這些工具。

一律載入工具會造成兩項影響。每個預先載入的工具都會占用部分 context，而這些 context 原本可用於任務本身。此外，工作階段啟動時會等待此伺服器連線，並遵守標準的五秒逾時設定。

例外情況是具有有效快取項目的遠端伺服器：它會直接從快取提供工具，不必連線，也不會延遲啟動。除非帳戶已在功能逐步推出期間啟用探索快取，否則此快取預設為關閉。你也可以透過 MCP_DISCOVERY_CACHE=1 明確啟用。只有在快取已啟用且包含有效項目時，才適用快速啟動的例外情況。即使代理程式透過搜尋工作時不需要這些工具，設定了 alwaysLoad 的工具仍會一直占用 context。

如果你要撰寫自己的 MCP 伺服器：伺服器指示能協助 Claude 理解何時該搜尋其工具，作用方式與 Skills 類似。Claude Code 預設會將每個工具的說明和每個伺服器的指示截斷至 2048 個字元，因此請將重要細節放在最前面。

選擇如何擴充 Claude Code，考量的不只是已連接的 MCP 伺服器數量。Claude Code：一次保留多少個擴充功能和Claude Code 該選什麼：Skills、Subagents、MCP 還是 Plugins這兩篇指南，會依不同工作探討 Skills、Subagents、MCP 和 Plugins。若要逐步設定特定 MCP 伺服器，請參閱MCP 伺服器 for Claude Code：可直接使用的組合。

接下來#

對於少於約 10 個、且定義可輕鬆放入 context 的工具，Agent SDK 文件指出，一次全部載入通常更快。不過，在 Claude Code 的預設行為中，若變數未設定且沒有遇到上述限制，工具搜尋就會啟用，MCP 工具會延後至搜尋時載入，但設定了 alwaysLoad 的伺服器除外。

在此情況下，你可以明確設定 ENABLE_TOOL_SEARCH=auto：只要工具定義的總量不到 context window 的 10%，就會預先載入；達到門檻後，便會啟用搜尋。如果你確定工具集合不會增加，也可以設定 ENABLE_TOOL_SEARCH=false。如上所述，這會讓 Claude Code 停止向模型回報伺服器連線失敗。

其他情況下，請在環境變更時再次檢查運作條件：

• 如果工作階段使用的是較舊模型，請切換至 Sonnet/Haiku/Opus 4.5 或更新版本；
• 如果連線使用非標準的 ANTHROPIC_BASE_URL，只有在代理伺服器本身會轉送 tool_reference 區塊時，才明確設定 ENABLE_TOOL_SEARCH=true；
• 確認部署平台不在例外清單中：Azure Foundry，或使用較舊模型的 Google Cloud Agent Platform。

如果符合條件，且設定未封鎖搜尋，就可以連接所需的 MCP 伺服器。只有在工作階段的每一回合都需要其工具時，才使用 alwaysLoad；其餘伺服器則交由搜尋載入。

如果你需要透過 Ailoot 使用 AI 模型，請看看 Ailoot。