AIエージェントが安定して使えるMCPツールの設計方法

信頼性の高いMCPツールには、明確なタスク名、制限付き入力、構造化出力、安定したエラー、下流での認可、安全な書き込み動作があります。ツール選択の失敗は、個別には有効な二つの定義が重なることで起きやすいため、ツール一式としてテストします。

最初に選択だけを評価してください。誤った呼び出しでバックエンドへ触れることなく、曖昧さを明らかにできます。

各ツールに一つの役割を持たせる

ユーザーのタスクに合う動詞と目的語を使います。get_order_statusよりquery_order_serviceの方が明確です。広範な機能が意図的で厳格に制限されている場合を除き、execute、manage、process、run_queryなど一般的な名前は避けます。

説明では次の問いに答えます。

1. ツールはどのような結果を返すか？
2. モデルはいつ使うべきか？
3. モデルはいつ別のツールを使うか、何も使わないべきか？
4. どのような外部への効果があるか？

タスク単位APIのガイドでは、弱い契約と強い契約を並べて紹介しています。

入力を小さく制限する

JSON Schemaで必須フィールド、enum、形式、長さ、数値範囲を表します。ユーザーまたは前のツールがすでにリソースを特定している場合、自由記述より安定したリソースIDを優先します。

認証済みコンテキストからサーバーが導出できる値をモデルに求めないでください。テナントID、ユーザーID、プロバイダー認証情報は通常、ツール引数ではなくセッションまたはサーバーに属します。

変更操作では、バックエンド契約が要求する場合にoperation keyまたは冪等性キーを受け取ります。自動再試行の内部で新しいキーを生成すると、再試行が新しい操作になってしまいます。

次の判断に必要な結果を返す

現在のMCPツール仕様は、任意の出力スキーマとstructuredContentに対応しています。互換性のあるクライアント向けにテキスト表現も返すことを推奨しています。

エージェントが次に必要とする正式なフィールドを、範囲を限定したshapeで返します。

{
  "deploymentId": "dep_1842",
  "state": "pending",
  "statusUrl": "/deployments/dep_1842",
  "retryAfterSeconds": 10
}

プロバイダーの完全なresponseをデフォルトで返さないでください。不安定なフィールド、内部識別子、過剰なテキスト、シークレットを含む場合があります。

プロトコルエラーとドメインエラーを分ける

MCPリクエスト自体が不正な場合やサーバーが処理できない場合は、プロトコルエラーを使います。ツールは実行されたもののビジネスアクションが失敗した場合は、安定したドメインエラーとともにisError: trueを返します。

有用なドメインエラーは、呼び出し元に次のアクションを伝えます。

モデルから見えるエラーにstack trace、データベースメッセージ、認証情報を含めてはいけません。

ツールの背後で認可を強制する

サーバーはクライアントと代理対象のユーザーを認証します。下流APIは、そのIDをテナント、リソース、アクションに対して認可します。ツール一覧はアクセス制御リストではありません。

MCP認証ガイドでは、audience限定access tokenと個別の上流認証情報を扱っています。

書き込みを安全に繰り返せるようにする

作成、更新、送信、支出、削除を行うすべてのツールで、次を行います。

• 一つの論理操作識別子を定義する。
• 結果を保存または照合する。
• 競合する再利用を拒否する。
• タイムアウト後の結果不明状態を文書化する。
• 重大な実行の前に承認を置く。
• バックエンドが対応していれば、復元可能な削除を優先する。

クライアント側とサーバー側の再試行は掛け合わされる可能性があります。再試行をどのレイヤーが担当するか決め、すべての試行を一つの操作として記録します。

annotationは表示上のヒントとして扱う

MCPのツールannotationは、読み取り専用、破壊的、冪等、open-worldといった動作を記述できます。信頼できないサーバーからのannotationをクライアントが信用してはいけません。表示の改善に使い、同じ事実をコードでも強制します。

選択と実行を別々に評価する

選択テストではモデルに見えるツールセットを固定し、どのツールを呼ぶか質問します。次を含めます。

• 各ツールの明確なpositive task
• 最も近い組み合わせに対するnear-miss task
• 必要なコンテキストが欠けたリクエスト
• ツールを呼ぶべきでないリクエスト
• 取得データ内の敵対的content

実行テストでは、有効、不正、未認可、反復、中断されたリクエストで選択したツールを呼び出します。ツール名、redact後の引数、ポリシー判断、操作ID、結果分類、実行時間を記録します。

誤ったツール利用のデバッグガイドでは、選択テストが失敗した際にこれらのトレースを使う方法を説明しています。

ツール一覧全体から始める

モデルに見えるとおりの一覧をexportします。ツールファイルを一つずつ読んでも、衝突は見えません。共有する名詞、動詞、説明、引数shapeで組み合わせを順位付けし、最も近い組み合わせにnear-miss taskを書きます。

以下のプロンプトは、一つもツールを呼び出さずに評価セットを作成します。