本文へスキップ
ウェブエンジニア問題集
第13章

AIエージェントに手足を与える — ツールとMCPの設計

約10分
この章の目次開く

タスクを適切に切っても、そのタスクに手が届く道具がなければエージェントは何もできません。逆に道具を増やしすぎると、今度はどれを使うべきかの判断がぶれ、説明文だけでコンテキストを食います。

道具の設計は、この2つの間で線を引く作業です。この章では、標準としてのMCPを確認したうえで、ツールをどう設計し、どこまで増やすかを整理します。

学習者学習者

便利そうなMCPサーバーがたくさんあるから、とりあえず全部入れておけばいいのかな？

MCPが標準化したこと

MCP（Model Context Protocol）は、AIアプリケーションを外部システムにつなぐためのオープンな標準です。公式ドキュメントは、これをAIアプリケーションにとってのUSB-Cにたとえています。USB-Cが機器の接続方法を1つに揃えたように、MCPはAIアプリと外部システムの接続方法を揃えます。

解決している問題は組み合わせの爆発です。標準がなければ、AIアプリの数だけ、外部システムの数だけ、個別の連携を書くことになります。標準があれば、サーバー側は1回作れば、対応するどのクライアントからも使えます。実際、多くのAIアシスタントや開発ツールが対応しています。

組み立てる人

つながる先は、データ（ファイルやデータベース）、ツール（検索や計算）、ワークフロー（特化したプロンプト）と幅があります。ここではコーディングエージェントに関係の深いツールを中心に扱います。

ツールはAPIのラッパーではない

Anthropicが2025年9月に公開したツール設計の記事は、最初に典型的な失敗を挙げています。既存のAPIエンドポイントをそのまま包んだだけのツールです。

なぜこれが失敗なのか。同記事の例が分かりやすいので借りると、「アドレス帳の全連絡先を返す」ツールと「連絡先を検索する」ツールの違いです。前者は人間が書くプログラムにとっては素直な設計ですが、エージェントにとっては違います。コンテキスト設計の章で見たとおり、返ってきた結果はすべてコンテキストを消費するからです。

同記事は、ツールを決定的なシステムと非決定的なエージェントのあいだの契約という新しい種類のものだと位置づけています。人間向けのAPIとは設計原理が違う、ということです。

ツールの設計は、機能を露出させる作業ではなく、エージェントが必要な分だけ取れる形を作る作業です。

数は少なく、境界は明確に

同記事の推奨は明快で、よく考えられた少数のツールです。重複したツールや多すぎるツールはエージェントを混乱させる、と警告されています。

設計として弱い設計として強い
APIの1エンドポイント＝1ツールで機械的に生やす実際のユースケース単位でまとめる
list_users と create_event を別々に置き、エージェントに組み立てさせる「予定を入れる」1つのツールが内部で両方を扱う
似た機能のツールが複数並ぶ機能の重複を最小にする
全件を返す検索・絞り込みを前提にする
先生先生

「このツールを使うべきか、隣のツールを使うべきか」でエージェントが迷う状態は、設計側の問題だと考えていい。迷わせない粒度を探すんだ。

トークン効率を設計に組み込む

ツールの応答量は、放っておくと際限なく膨らみます。同記事は、ページング・範囲選択・フィルタリング・切り詰めの組み合わせを実装するよう勧めています。Claude Code自身も、ツール応答に既定で25,000トークンの上限を設けていると述べられています。

これはコンテキスト設計の章で「最も見落とされる消費先はツールの実行結果」と書いたことの、供給側からの対策です。指示ファイルを削るより、応答を絞るほうが効果が大きい場面は珍しくありません。

ツールの応答量に上限を持たせるのは、機能の制限ではなく設計要件です。

名前と説明文はプロンプトである

ツールの説明文は、ドキュメントではありません。エージェントのコンテキストに読み込まれ、振る舞いを直接左右するという意味で、プロンプトの一部です。同記事も、ツールの説明と仕様に対するプロンプトエンジニアリングが、ツール改善の最も効果的な手段のひとつだと述べています。

具体的な指針は3つです。

  • 新しく入ったメンバーに説明するつもりで書く。前提を共有していない相手に伝わる粒度にする
  • 引数名を曖昧にしない。user ではなく user_id のように、何を渡すのかが名前で分かるようにする
  • エラー応答も設計する。不透明なエラーコードを返すのではなく、具体的で実行可能な改善を伝える。正しくフォーマットされた入力の例を返すのが有効

エラー応答の設計は見落とされがちですが、効果が大きい部分です。エージェントは失敗から回復しようとするので、回復の手がかりが応答に含まれているかどうかが、そのまま成功率に効きます。

前に進む人

MCPを増やすことは、入力の経路を増やすこと

ここは必ず押さえてください。MCPサーバーを1つ足すことは、依存パッケージを1つ足すのと同じ性質を持ちます。そして、通常の依存パッケージにはない固有のリスクがあります。

ツールポイズニングと呼ばれる攻撃です。OWASPが攻撃手法として掲載しているもので、ツールのメタデータ（説明文など）に悪意ある指示を埋め込むものです。攻撃の流れはこうです。

これは権限設計の章で扱った致命的な三要素の、「信頼できないコンテンツへの露出」を自分から増やしている状態にほかなりません。ツールの説明文は、エージェントが必ず読むテキストです。そこに攻撃者が書き込めるなら、これほど確実な経路はありません。

学習者学習者

そこまで気にするなら、MCPは使わないほうがいいってこと？

そうではありません。npmのパッケージを使わない開発者がいないのと同じです。使わないという判断ではなく、依存として扱うという判断をしてください。入れる前に出所を見る、入れたら棚卸しする、使っていないものは外す。通常の依存管理と同じ規律が要る、というだけの話です。

評価で回す

ツール設計は一発で決まりません。同記事が勧めているのは、まず動くものを作ってローカルで試し、評価を用意してから変更の効果を測るという進め方です。実際のユースケースから評価タスクを作り、プログラムとして実行し、エージェントの思考過程を分析して改善する、という反復です。

面白いのは、この分析自体をエージェントに任せられる点です。やり取りの記録を読ませて、どこでツールの使い方に迷ったかを洗い出させる。設計の改善サイクルそのものを自動化できます。

よくあるハマりどころ

入れっぱなしにする。 使っていないツールも、定義がコンテキストを消費し続けます。定期的な棚卸しが要ります。

APIをそのまま生やす。 既存のエンドポイント数だけツールが並ぶと、粒度も命名もエージェント向きになりません。

応答を絞らない。 上限のないツールは、1回の呼び出しでコンテキストを使い切ることがあります。

出所を確認せずに入れる。 便利さだけで判断すると、信頼できない入力の経路を自分から開くことになります。

説明文を後回しにする。 動くようになった時点で満足しがちですが、説明文の改善は最も費用対効果の高い作業のひとつです。

ちゃんと使うためのポイント

  • MCPはAIアプリと外部システムをつなぐ標準。サーバー側は1回作れば多くのクライアントで使える
  • ツールはAPIのラッパーではない。全件返すのではなく、必要な分だけ取れる形にする
  • よく考えられた少数のツールを目指す。重複はエージェントを迷わせる
  • 応答量の上限は設計要件。ページング・絞り込み・切り詰めを組み込む
  • 名前と説明文はプロンプト。エラー応答には回復の手がかりを入れる
  • MCPサーバーは依存パッケージと同じ。出所を確認し、権限を絞り、棚卸しする
  • ツールポイズニングは実在する攻撃で、クライアント側の防御は当てにしない
  • 評価を用意してから改善する

次の章では、ここまでで整えた道具を使って、エージェント自身に成果を検証させる仕組みを作ります。良い道具は、エージェントが自分の間違いに気づくためにこそ効きます。

参考リンク