エージェンティック・ハーネス設計ガイド — Part 4
ツール設計とスキル
読ませすぎない。選ばせすぎない。
1.ツールが選べなくなる、本当の理由
10個のツールなら、全部見せても問題は起きません。しかし接続先が増えて100を超えたあたりから、選択の精度が落ち始めます。
判断の目安
人間のエンジニアがそのツール一覧を見て「どれを使えばいいか分からない」と感じるなら、モデルも同じところで迷います。名前が似ている、説明が抽象的、粒度が揃っていない——これらはすべて、人にとっての分かりにくさがそのままモデルの誤選択になります。
2.ツール定義の4原則
個々のツールをどう定義するか。特別な作法はなく、人が使うAPIの設計とほぼ同じ原則が効きます。
このうち見落とされやすいのが返す識別子です。ランダムなIDだけを返すツールは、後続の判断材料を何も渡していません。「INV-2026-0831-ACME」のように意味が読み取れる値を含めれば、エージェントは中身を再取得せずに判断を進められます。
結果の量に上限を置くことも、単なる保護ではありません。上限があると、設計が意図的になります。「全部返す」が選べないと、何を返すべきかを考えざるを得なくなるためです。
3.エラーは「状態の通知」ではなく「次の行動の指示」
ツール設計で最も効くのに、最も手を抜かれるのがエラーメッセージです。
とくに危険なのが黙って切り詰めることです。1,240件のうち上位50件だけを返し、そのことを伝えなければ、エージェントは50件で全体を判断します。表面上は正常に完了し、結論だけが間違っている——Part 3で扱った「誰も気づけない失敗」と同じ構造です。
4.段階的に見せる — 入口だけを常設する
ツール数の問題への答えが、段階的な読み込みです。全部を常設せず、絞り込みながら降りていきます。
削減幅は大きくなり得ます。Anthropic は「Code execution with MCP」（2025年11月4日）で、必要な定義だけを読み込む方式により 150,000 → 2,000 トークン（98.7% 減）となった例を報告しています。削減幅は接続しているツールの数と規模に依存するため、常にこの比率になるわけではありません。
効果は枠の節約だけではありません。選択肢が少ないほど、選択は正確になります。段階を踏むことで、各段階での判断が「20個から1個」ではなく「5個から1個」になります。
5.往復で呼ぶか、コードで呼ぶか
ツールの呼び方そのものにも選択肢があります。1回ずつ往復して呼ぶか、呼び出しをまとめたコードを書いて実行環境で走らせるかです。
効果が出るのは、中間結果が大きく、かつ最終的に必要なのは集計値だけ——という形の処理です。逆に、往復のたびに人の判断を挟みたい処理には向きません。前節の「必要な定義だけを読み込む」話と合わせて、どちらもツール接続まわりのトークンを削る手段として同じ資料で扱われています。
前提として、コードを走らせる以上は隔離された実行環境が要ります。この方式を選ぶことは、サンドボックスを持つことを意味します。
6.スキル — 繰り返す手順を、外に置く
ここからはスキルの話です。スキルとは、繰り返す仕事の手順を、その都度プロンプトに書くのではなく、呼び出せる形で外に置いたものを指します。
構造はツールの段階的開示と同じです。常に読まれるのはメタデータだけで、本文は関連すると判断されたときに、参照ファイルは実行中に必要になったときにだけ読み込まれます。スキルが100個あっても、常時の負担は100行程度の説明文で済みます。
7.説明文が、呼ばれるかどうかを決める
スキルが機能しない相談の大半は、実装ではなく説明文が原因です。呼ぶかどうかの判断に使われるのは、名前と一行の説明だけだからです。
コツは、利用者が使いそうな言葉を説明文に含めることです。「突合」と書いてあっても、現場が「消込」と呼んでいるなら、その語も入れておく。説明文はドキュメントではなく、検索のためのインデックスに近いものと考えると設計しやすくなります。
スキルが増えてきたら、互いに排他的な文脈は別のスキルに分けることも効きます。1つのスキルに複数の用途を詰め込むと、説明文が抽象的にならざるを得ず、結果としてどの場面でも呼ばれにくくなります。
8.決定性が要るなら、指示ではなくスクリプト
スキルの本文に手順を書くか、スクリプトを同梱して実行させるか。判断基準は単純で、結果が毎回同じであるべきかです。
ここはトークン効率より決定性を優先する場面です。ファイル形式の変換、集計、命名規則の適用——手順が確定しているものは、モデルに毎回組み立てさせる理由がありません。
9.スキルは、運用の中で育てる
最初から完璧な説明文は書けません。実際の依頼と突き合わせて、呼ばれ方を合わせていく必要があります。
この反復を回すために必要なのが、実行の記録です。どのスキルが、どの依頼で、呼ばれたか・呼ばれなかったか。これが残っていなければ、改善の材料そのものが手に入りません。ツールとスキルの設計は、Part 1で挙げた「⑥ 再利用・統制」の記録と、セットで機能します。
10.アンチパターン早見表
ここまでの内容を、実装で見かける形にして並べます。
| よくある実装 | 何が問題か | どうするか |
|---|---|---|
| 全ツールを常に提示する | 枠を食い、似た名前が並んで選択を誤る | 領域→ツール→引数の順に段階的に見せる |
| エラーコードだけを返す | 同じ呼び出しを条件を変えずに繰り返す | 次に取るべき行動を本文で伝える |
| 黙って結果を切り詰める | 「これで全部だ」と判断して先へ進む | 総件数と、絞り込み方を一緒に返す |
| ランダムな識別子だけを返す | 後続の判断に使えず、文脈を復元できない | 意味の読み取れる値を含める |
| 中間結果を毎回モデルに返す | 使い捨ての結果まで枠を食う | まとめて実行し、最終結果だけ返す |
| スキルの説明に「何ができるか」を書く | いつ使うかが分からず、呼ばれない | どういうときに使うかを書く |
| 確定した手順もプロンプトで指示する | 毎回揺れる・遅い・高い | スクリプトとして同梱して実行させる |
| スキルを作って放置する | 想定と違う使われ方に気づけない | 呼ばれ方を記録し、説明文を直し続ける |
Summary
この記事の要点
- 1ツールが選べない原因は、モデルの能力ではなく「全件を常に見せている」設計にあることがほとんど。
- 2人間のエンジニアが迷う一覧は、モデルも迷う。名前・説明・粒度の分かりにくさは、そのまま誤選択になる。
- 3ツール定義は人が使うAPIと同じ原則 — 名前空間、意味の読み取れる識別子、簡潔版と詳細版、結果量の上限。
- 4エラーは「状態の通知」ではなく「次の行動の指示」として書く。
- 5黙って結果を切り詰めない。総件数と絞り込み方を一緒に返さないと、部分で全体を判断される。
- 6ツールは段階的に見せる — 領域 → ツール → 引数仕様。選択肢が少ないほど選択は正確になる。
- 7必要なツール定義だけを読み込む方式で、Anthropic は 150,000→2,000 トークン（98.7%減）の例を報告している。
- 8中間結果が多い処理は、往復ではなくコードで呼ぶ。中間結果は実行環境に留め、最終結果だけを文脈に載せる。
- 9スキルは、繰り返す手順を呼び出せる形で外に置いたもの。常に読まれるのは説明文だけ。
- 10説明文には「何ができるか」ではなく「どういうときに使うか」を書く。現場の語彙を含める。
- 11結果が毎回同じであるべき処理は、指示ではなくスクリプトにする。決定性はトークン効率に優先する。
- 12スキルは書いて終わりではない。呼ばれ方を記録し、説明文を直し続ける。
Sources
出典・参考文献
本記事は、以下の一次資料をもとに整理しています。数値・仕様は各出典の公開時点のものです。
FAQ
よくある質問
多くの場合、原因はモデルの能力ではなく「全件のツールを常に提示している」設計にあります。選択肢が増えるほど枠を食い、似た名前のツールが並んで選択を誤ります。人間のエンジニアが選択肢を見て迷うなら、モデルも迷います。対策はツールを減らすことではなく、領域→ツール→引数仕様の順に、必要になった分だけ見せることです。
「状態の通知」ではなく「次の行動の指示」として書きます。エラーコードだけを返すと、エージェントは同じ呼び出しを条件を変えずに繰り返します。「期間の指定が広すぎます。90日以内に絞るか、取引先を指定して再実行してください」のように、次に取るべき行動を本文で伝えます。結果を切り詰めるときも同様で、黙って切り詰めるとエージェントは「これで全部だ」と判断して先へ進みます。
中間結果が多い処理では有利です。1回ずつ往復して呼ぶ方式では、使い捨ての中間結果まですべてモデルの文脈に載ります。呼び出しをまとめたコードを実行環境で走らせれば、中間結果は実行環境に留まり、最終結果だけが返ります。ただし効果は処理の形に依存し、往復のたびに人の判断を挟みたい処理には向きません。またコードを走らせる以上、隔離された実行環境が前提になります。なおAnthropicは同じ「Code execution with MCP」（2025-11-04）で、必要なツール定義だけを読み込む方式により150,000→2,000トークン（98.7%減）となった例も報告しています。
繰り返す仕事の手順を、その都度プロンプトに書くのではなく、呼び出せる形で外に置いたものです。名前と一行の説明（メタデータ）、手順を書いた本文、参照ファイルやスクリプトの3つがフォルダひとつにまとまっており、必要になった段階だけを読み込む「段階的開示」の構造になっています。
まず説明文です。呼ぶかどうかの判断に使われるのは、名前と一行の説明だけです。「経理まわりの作業を支援します」のような曖昧な説明では、該当する依頼でも呼ばれません。「請求書と入金明細の突合。月次締め、差異調査、入金消込のときに使う」のように、何ができるかではなく“どういうときに使うか”を書きます。
結果が毎回同じであるべき処理は、スクリプトにします。毎回モデルに考えさせると結果が揺れ、遅く、高くつきます。判断が要るところだけモデルに任せ、確定している手順はコードに落とすのが基本です。トークン効率より、決定性を優先する場面と考えてください。
Part 3
耐久実行と再開 — 中断を前提に組む
落ちない設計ではなく、落ちても続きから戻れる設計へ。
Part 5 — 準備中
封じ込めと承認設計 — 境界を先に敷く
隔離強度の選び方、許可リストを「能力の付与」として捉える視点、非同期の承認と束ね承認。
実行基盤を、自社で持ちたい方へ
homulaは、AIエージェント実行基盤の要件定義から設計・構築・運用までを支援しています。ツール設計とスキル運用は、接続先が増えてから作り直すと高くつく領域です。