ツール検索

セッションにたくさんの MCP サーバーやコア以外のプラグインツールをつないで いると、それらの JSON スキーマだけで毎ターンのコンテキストウィンドウを かなり食ってしまいます。ユーザーが実際に頼んだ内容に関係するツールが ほんの数個しかない場合でも同じです。

ツール検索は、その問題に対して Hermes が用意した、任意で有効にできる 段階開示のしくみです。有効になると、モデルから見えるツール一覧では MCP ツールとプラグインツールが 3 つの橋渡しツールに置き換わり、モデルは必要に なったときだけ個別ツールのスキーマを読み込みます。

しくみ

そのターンでツール検索が有効になると、後回しにされたツールの代わりに、 モデルには次の 3 つのツールが見えます。

tool_search(queries, limit?)   — search the deferred-tool catalog (one or more queries)
tool_describe(names)           — load the full schemas for one or more tools
tool_call(name, arguments)     — invoke a deferred tool

やり取りは、たとえば次のように進みます。

Model: tool_search(["create a github issue", "send a slack message"])
  → { results: [ { query: "create a github issue",
                   matches: ["mcp_github_create_issue", ...] },
                 { query: "send a slack message",
                   matches: ["mcp_slack_post_message", ...] } ],
      tools: { mcp_github_create_issue: { description: "...",
                                          required: ["title"], ... },
               mcp_slack_post_message: { ... } } }
Model: tool_describe(["mcp_github_create_issue", "mcp_slack_post_message"])
  → { tools: { mcp_github_create_issue: { parameters: { ... } },
               mcp_slack_post_message: { parameters: { ... } } } }
Model: tool_call("mcp_github_create_issue", { title: "...", body: "..." })
  → { ok: true, issue_number: 42 }

tool_search に渡したクエリは、それぞれ独立に同じカタログへ照会されます （limit はクエリごとに効きます）。クエリごとのまとまりに載るのはツール名 だけで、一致した各ツールの説明と必須パラメーター名は、共有の tools マップに 一度だけ入ります。クエリは語幹に落として扱われるので、「issues」でも create_issue が見つかります。一致が 0 件だったクエリのまとまりには、 つないでいるサーバーをまとめた available_sources が付きます。言葉が 引っかからなかっただけなのに、その機能自体がないと取り違えないためです。 tool_describe は、要求された名前をすべて 1 回の呼び出しで解決します。 知らない名前は not_found に入れて報告され、残りの一括処理は失敗しません。

モデルが tool_call を呼ぶと、Hermes は 橋渡しの層を外して、 モデルが直接呼んだ場合とまったく同じように本来のツールを実行します。 ツール呼び出し前のフック、ガードレール、承認の確認、 そして呼び出し後のフックは、すべて本来のツール名に対して動きます。 tool_call に対してではありません。CLI とゲートウェイの実行ログでも 橋渡しの層は外れるので、見えるのは本来のツールであって橋渡しではありません。

いつ有効になるか

ツール検索は 段階的な開示 を使います。後回しにできる（MCP・プラグインの） ツールが *ひとつでも* あれば橋渡しは有効になります。カタログの大きさで変わるのは、 カタログのどこまでを見せ続けるかであって、スキーマを後回しにするかどうかではありません。

一覧の予算は min(threshold_pct% of context, listing_max_tokens) です。 判定はツール一覧を組み立てるたびにやり直されるので、セッションの途中で MCP サーバーを足したり外したりすると、次の組み立てのときに段階が変わります。

設定

tools:
  tool_search:
    enabled: auto       # auto (default), on, or off
    threshold_pct: 5    # listing budget as a percentage of context
    search_default_limit: 5
    max_search_limit: 25
    listing: auto       # embed a grouped name+description catalog manifest
    listing_max_tokens: 4000

1 回の呼び出しで渡せる配列の上限は、設定ではなく内部の安全弁です。上限を 超えた呼び出しはエラーを返すので、モデルは数を減らして呼び直せます。

一覧がある理由

一覧がないと、後回しにされた能力は *見えなく* なります。実際のベンチマークでは、 モデルが目に見えるコアツールで代用したり（後回しの GitHub ツールを探さずに ターミナルで gh を実行する）、tool_search を呼ばずに「そんな機能はない」と 言い切ったりする様子が観測されました。この一覧は、スキルのやり方をツールにも 持ち込んだものです。どの能力もつねに名前で見つけられるようにしつつ、 パラメーターの完全なスキーマは後回しのままにします。目当てのツール名が 一覧に載っていれば、モデルは tool_search を飛ばして tool_describe に 直行でき、往復を 1 回減らせます。

以前からある真偽値の書き方も使えます。

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

使わないほうがよい場合

ツール検索は、後回しにしたスキーマぶんの節約と引き換えに、毎ターン一定の トークン費用（橋渡しツール 3 つのスキーマとカタログの一覧）と、まだ読み込んで いないツールでの少なくとも 1 往復（describe → call）を支払います。 段階 1 では一覧がすべての能力を見せているので、探すための往復はたいてい なくなり、モデルは tool_describe へ直行します。実際のベンチマークでは、 一覧ありのモードは、そのまま全部読み込む方式と同じくらいタスクを成功させながら、 橋渡しだけの構成より費用が少なくて済みました。

小さなツール群で以前のような常時読み込みの挙動にしたいときは、 enabled: off にしてください。

消えないトレードオフ

次の点は、プロンプトキャッシュの整合性を保つという前提から来るもので、 この実装に固有ではなく、段階開示という設計そのものに付いて回ります。

• まだ読み込んでいないツールでは往復が 1 回増える。 後回しのツールが

最初に必要になったとき、スキーマを探して読み込むためにモデル呼び出しが 1〜2 回余分にかかります。静的な側でのトークン節約は本物ですが、 その一部は実行時に払い戻す形になります。

• 後回しのスキーマにはキャッシュの恩恵がない。 読み込んだ

tool_describe の結果は会話履歴に入るので、以降のターンではキャッシュに 乗ります。ただしシステムプロンプトのキャッシュ接頭辞の恩恵は受けません。

• モデルの実力に左右される。 ツール検索は、欲しいツールに対して

モデルがまともな検索語を書けることを前提にしています。小さいモデルほど これが苦手です。公表されている Anthropic の数値（Opus 4 でツール検索 あり 74%、なし 49%）は伸びしろを示す一方で、なお約 26 ポイントぶんは 探し出せずに終わっていることも示しています。

• ツール構成をいじるとキャッシュが無効になる。 セッションの途中で

ツールを足したり外したりすると、橋渡しツールの説明文（後回しツールの 件数を含みます）とカタログが変わるので、プロンプトキャッシュが無効に なります。これはツール構成をいじるとき全般に共通するトレードオフです。

実装の詳細

• 検索: ツール名、提供元の名前（そのツールが属する MCP サーバーや

プラグインのツール群。おかげで "linear" で検索すれば、ツール名自体に サービス名が入っていなくてもそのサーバーのツールが見つかります）、説明、 パラメーター名をトークン化した上での BM25 です。索引にも検索語にも Snowball の語幹処理（英語）をかけるので、語形が変わっても一致します （「issues」で create_issue が見つかります）。どの検索語もどの文書にも 当たらないときは、ツール名に対する部分一致にフォールバックします （たとえばトークンが github のところを "hub" で検索した場合）。

• 並列実行でも橋渡しの層は外れる。 一括実行の計画は、tool_call の

リテラルな橋渡し名ではなく *本来の* ツールを見て同時実行の可否を決めます。 そのため supports_parallel_tool_calls: true で並列を有効にした MCP サーバーは、橋渡し経由で呼ばれても同時実行を保ちますし、tool_search や tool_describe の照会も、読み取り専用のツールと同じようにまとめて 同時に走ります。

• カタログはターンをまたいで状態を持たない。 組み立てのたびに現在の

ツール定義一覧から作り直します。セッションをキーにした Map は使いません。 保存したカタログが実際のツール登録内容とずれていく、という類のバグを これで避けています。

• カタログはセッションのツール群の範囲に閉じている。 tool_search、

tool_describe、tool_call が見たり呼んだりできるのは、そのセッションに 実際に与えられたツールだけです。サブエージェント、かんばんのワーカー、 ゲートウェイのセッションが一部のツール群に絞られている場合、橋渡しを使って その外のツールを見つけたり呼んだりはできません。後回しカタログは、 プロセス全体の登録内容ではなく、そのセッション自身で有効・無効にした ツール群のうち後回しにできる部分だけです。

• JS サンドボックスは使わない。 Hermes は、より単純な「構造化ツール」

方式（search / describe / call をただの関数として扱う）を採っています。 ほかの実装にある JS サンドボックスの「コードモード」は面が広すぎるので、 見送っています。

関連

• tools/tool_search.py — 実装
• tests/tools/test_tool_search.py — 回帰テスト一式
• 設計のもとになった調査については、最初の実装 PR にある

openclaw-tool-search-report の PDF