H繁中版
文件核心功能tool search
<!-- Source: https://hermesbible.com/docs/user-guide/features/tool-search -->

Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/tool-search

Tool Search

當你的 session 掛載了大量 MCP server 或非核心 plugin tools 時，它們的 JSON schema 可能在每一輪都佔據相當比例的 context window ——即使其中只有少數工具與使用者實際詢問的內容相關。

Tool Search 是 Hermes 針對此問題提供的 opt-in 漸進式揭露層（progressive-disclosure layer）。啟用後，MCP 和 plugin tools 會在模型可見的 tools array 中被三個 bridge tools 取代，模型改為按需載入每個特定工具的 schema。

INFO — Hermes 內建工具永遠不會被延遲載入

組成 Hermes 核心功能集的工具（terminal、read_file、write_file、patch、search_files、todo、memory、browser_*、web_search、web_extract、clarify、execute_code、delegate_task、session_search、send_message 以及 _HERMES_CORE_TOOLS 中的其他工具）永遠直接載入。只有 MCP tools 和非核心 plugin tools 才有資格被延遲載入。

運作方式

當 Tool Search 在某一輪啟動時，模型會看到三個新工具取代了被延遲的工具：

tool_search(query, limit?)     — search the deferred-tool catalog
tool_describe(name)            — load the full schema for one tool
tool_call(name, arguments)     — invoke a deferred tool

典型的互動流程如下：

Model: tool_search("create a github issue")
  → { matches: [{ name: "mcp_github_create_issue", ... }, ...] }
Model: tool_describe("mcp_github_create_issue")
  → { parameters: { type: "object", properties: { ... } } }
Model: tool_call("mcp_github_create_issue", { title: "...", body: "..." })
  → { ok: true, issue_number: 42 }

當模型呼叫 tool_call 時，Hermes 會解開 bridge，並以與模型直接呼叫相同的方式分派底層工具。pre-tool-call hooks、guardrails、approval prompts 和 post-tool-call hooks 都是針對真實工具名稱執行 ——而非針對 tool_call。CLI 和 gateway 中的 activity feed 也會解開顯示，讓你看到的是底層工具，而非 bridge。

何時啟動？

預設情況下 Tool Search 以 auto 模式運作：只有當可延遲的工具 schema 佔用至少 10% 的啟動模型 context window 時才會啟動。低於此門檻時，tools array 組裝是純直通的，不會產生額外開銷。

此判斷在每次組裝 tools array 時都會重新評估，因此：

  • 只掛載少數 MCP tools 且使用長 context 模型的 session 永遠不會啟動 Tool Search。
  • 掛載大量 MCP servers 的 session（通常 15+ tools）會開始啟動它。
  • 在 session 中途移除 MCP servers 後，下一次組裝時會正確恢復為直接揭露。

設定

tools:
  tool_search:
    enabled: auto       # auto (default), on, or off
    threshold_pct: 10   # percentage of context — only used in auto mode
    search_default_limit: 5
    max_search_limit: 20
參數預設值說明
enabledautoauto 在超過門檻時啟動；on 只要有至少一個可延遲工具就永遠啟動；off 完全停用。
threshold_pct10auto 模式啟動的 context 長度百分比。範圍 0–100。
search_default_limit5模型呼叫 tool_search 時未指定 limit 時回傳的結果數。
max_search_limit20模型透過 limit 可請求的硬性上限。範圍 1–50。

你也可以使用傳統的布林值格式：

tools:
  tool_search: true   # equivalent to {enabled: auto}

何時不該使用

Tool Search 用每個固定的每輪 token 成本（三個 bridge tool schemas，約 300 tokens）加上至少一次額外往返（search → describe → call），換取延遲 schema 所省下的 token。當你有很多工具且每輪只使用少數幾個時，這是明確的收益；但當你工具總數很少時，它就變成了開銷。

auto 預設值已為你處理了這種情況。如果你無條件設定 enabled: on，在小型工具集上預期會有輕微的每輪成本。

無法消除的權衡

這些來自 prompt-cache 完整性不變量 ——它們是任何漸進式揭露設計的固有特性，而非此實作的特定問題：

  • 冷工具需要一次額外往返。 模型第一次需要某個延遲工具時，會花費一到兩次額外的模型呼叫來搜尋並載入 schema。靜態端的 token 省下是真實的，但有一部分會在運行時回吐。
  • 延遲 schema 沒有快取優勢。 載入的 tool_describe 結果會進入對話歷史（因此在後續輪次中確實會被快取），但它永遠不會受益於 system-prompt 快取前綴。
  • 模型品質的依賴性。 Tool Search 假設模型能為它想要的工具撰寫合理的搜尋查詢。較小的模型在這方面表現較差；Anthropic 公佈的數據（Opus 4 有/無 tool search 時 49% → 74%）顯示了改進空間，但也表明仍有約 26 個百分點的準確度是檢索失敗。
  • 工具集變更會使快取失效。 在 session 中途新增或移除工具會改變 bridge tools 的描述（其中包含延遲工具的數量）和目錄，因此 prompt cache 會失效。這與任何工具集編輯帶來的權衡相同。

實作細節

  • 檢索方式： 基於 BM25 的 tokenized tool name + description + parameter names 搜尋。當 BM25 沒有回傳正分結果時，退回至對 tool name 的 literal substring match，以防止 zero-IDF 退化情況（例如在每個工具名稱都包含 "github" 的目錄中搜尋 "github"）。
  • 目錄在各輪之間無狀態。 每次組裝時都從目前的 tool-defs list 重新建立 ——沒有 session-keyed 的 Map。這避免了儲存的目錄與即時工具登錄不同步的那類 bug。
  • 目錄範圍限定於 session 的工具集。 tool_search、tool_describe 和 tool_call 只能看到和呼叫 session 實際授予的工具。被限制在特定工具集子集的 subagent、kanban worker 或 gateway session 無法透過 bridge 發現或呼叫該子集之外的工具 ——延遲目錄是 session 自身已啟用/停用工具集中可延遲部分的切片，而非整個程序登錄。
  • 無 JS sandbox。 Hermes 使用較簡潔的 "structured tools" 模式（search / describe / call 作為純函數）。某些其他實作提供的 JS-sandbox "code mode" 具有大面積的攻擊面；我們選擇略過它。

另請參閱

  • tools/tool_search.py — 實作原始碼
  • tests/tools/test_tool_search.py — 回歸測試套件
  • 原始實作 PR 中的 openclaw-tool-search-report PDF，包含塑造此設計的研究

Web Dashboard

tool gatewaytools