エージェントのツールコンテキストを調整

このガイドでは、二層のツールサーフェスを扱う実務 — 実行が何を送信するかの確認、その変更、そしてエージェントが誤ったツールに手を伸ばしたときの診断 — を扱います。なぜこのような仕組みになっているのかについては、ツールコンテキストとプロンプトキャッシュをお読みください。

実行が実際に送信するものを確認する

会話を開き、会話ヘッダーのコンテキスト使用量インジケーターをタップします。これは何も実行することなく、次のディスパッチが送信するのとまったく同じサーフェスを再構築します。さらに表示（または /context コマンド）で完全なコンテキストエクスプローラーが開き、そこで各ツールを確認できます。

ここでは 2 つのセグメントが重要です:

ツール定義と MCPと動的ツール — 常駐セットで、各ツールの実際のトークンコストが示されます。
オンデマンドで読み込まれるツール — 遅延インデックスです。各エントリに課されるのはその名前だけです。リクエストが運ぶのは名前だけだからです。エントリを開くと完全な説明とスキーマが表示されるので、実行がそれを引き込んだ場合にどれほどコストがかかるかを確認できます。

遅延セグメントが空の場合、このサーバーでは遅延が無効です。cc_server CLI の --tool-deferral を確認してください。

事前に読み込むツールを変更する

常駐セットは設定ではなくポリシーです — それは ModeToolPolicy（packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart）にあり、すべての実行に適用されます:

residentBuiltins — ファイルとシェルの語彙。
residentDiscovery — search_tools と list_my_tools。これらは削除しないでください。エージェントが他のすべてに到達する手段だからです。
residentMcpTools — リクエストごとにスキーマに見合う価値がある、わずかな Control Center ツール。
モードごとのブロック。特定のモードがほぼ毎ターン使うツールのためのものです。

編集する際のルールは 2 つです:

大半の実行が使う場合にのみツールを追加します。 すべての名前は、すべての実行のすべてのリクエストで、永久にそのスキーマ分のコストを伴います。使われるときには重要でも全体としてはまれなツールは、遅延される側に属します — エージェントはそれでもそれを見つけられます。

ツールの実際の名前を使用します。 どのツールにも一致しない常駐名は無効です。エラーも警告も出ず、そのツールは単に遅延されるだけです。test/tooling/resident_tool_names_test.dart がこれを検出し、さらに各モードを常駐ツール 40 個未満に保ちます。これがこの取り組みの要点です — その範囲を超えると、ツール選択は目に見えて悪化します。

モードの必須および固定の動詞は自動的に追加されるので、モード自身の出力動詞を列挙する必要は決してありません。

誤ったツール選択を診断する

エージェントが誤ったツールを使った、または何かを行えないと主張したときは、3 つのうちどれが起きたのかを突き止めます。

1. 探したか?

各実行は、読み込んだ遅延ツールとそのきっかけ — 名前による直接呼び出し、または search_tools クエリ — を記録します。その実行のイベントストリーム（設定 → ワークスペース → エージェント → エージェント → ログ → 表示）を開き、[harness] loaded N deferred tool(s) を探します。

何も記録されておらず、エージェントがケイパビリティが存在しないと言った — 一度も探していません。これはプロンプトの問題であり、検索の問題ではありません。遅延インデックスはシステムプロンプトにあり、検索が空の結果を返すまでケイパビリティが存在しないと宣言しないよう指示されています。
検索は記録されたが、何も読み込まれなかった — 真の検索ミスです。手順 2 に進みます。
ツールは読み込まれたが、誤ったものが使われた — 見つかったツールが似すぎています。手順 3 に進みます。

2. 検索ミスを修正する

search_tools は名前、説明、引数名で照合します。ミスはほとんどの場合、説明にエージェントが使った言葉が含まれていないことを意味します。

それらを追加します。説明は検索インデックスなので、削るのではなく長くします — 内部的な名詞だけでなく、オペレーターが実際に入力する語彙（“assign”、“hand off”、“give to”）を書きます。トークンを節約するために説明を削ると、検索ヒットと選択精度の両方を失い、スキーマに比べればほとんど節約になりません。

適切なツールが存在するのに順位が低い場合、そのための引数が limit です。ツール自身の説明が、惜しいが見つからない検索を広げるようエージェントに指示しています。

3. 似たツールを修正する

2 つのツールの説明が、違いをすでに知らない人には同じように読めるなら、モデルは推測しています。それらを、区別するための引数を持つ 1 つのツールに統合します。

ticket_relation と ticket_pr_link はこのパターンに従っています。それぞれが、区別するための引数を通じてリンクとリンク解除を処理します。1 回の呼び出しの内部で、リクエストの完全なコンテキストとともに行われる選択は、似た 2 つの説明の間で行われる選択よりも信頼できます。

異なる承認ゲート、異なる監査、または異なるレンダリングが必要な場合は、ツールを分けたままにします — これらは、統合すると実際のコストが生じる理由です。

プロンプトキャッシュが機能していることを確認する

キャッシュヒット率は オブザーバビリティ → インサイト に キャッシュ率 として表示されます。健全な長時間実行の会話は高い値を維持します。低い状態が続く場合、毎ターン何かがプレフィックスを書き換えています。

よくある原因を、可能性の高い順に示します:

プロンプトの早い段階にある非決定的なもの。 タイムスタンプ、リクエスト ID、または順序が変わる形で反復されるセットでも起こります。
会話の途中でのモデルまたは推論の程度の変更。 どちらもプレフィックスを変えます。ここでは特にサブエージェントを誤りやすいです。コストを節約するために子を低い推論の程度で実行すると、失われるキャッシュ共有のコストが節約分を上回ることがあります。
頻繁な圧縮。 圧縮は設計上履歴を書き換えるため、そのコストは実在します。対処法は、頻繁かつ浅くではなく、まれに深く圧縮することです。

--tool-deferral=off で遅延を無効にするのは、動作の変化が二層のサーフェスに由来するかどうかを切り分けるための有効な A/B です。遅延が存在する前のリクエストを正確に再現するので、無効にしても動作が続く場合、そのサーフェスが原因ではありません。