誤ったツールを使うAIエージェントをデバッグするには、モデルが見た正確なツール一覧とコンテキストを再構築し、何も実行せずに選択をテストします。多くの失敗は名前、説明、引数shapeの重複やコンテキスト不足から生じますが、traceから、呼び出し自体は正しく結果が悪かったと分かる場合もあります。
どの段階が失敗したか特定できるまで、プロンプトを変更しないでください。
現在のMCPツール仕様では、名前、説明、入力schema、任意の出力schemaがクライアントから見えます。これらは観測可能な契約なので、隠れたモデル推論のせいにする前に調べます。
失敗を正確に分類する
- 誤った選択： 別の表示ツールの方がタスクに一致した。
- 誤った引数： 選択したツールは正しいが、ID、enum、scope、必須fieldが誤っていた。
- 早すぎる呼び出し： 必要なコンテキストや承認を集める前に、正しいツールを使った。
- 誤解を招く結果： ツールはバックエンドを正しく呼んだが、曖昧、古い、不正なresponseを返した。
- 安全でない実行： 選択は正しいが、ツールの背後で認可、冪等性、承認が失敗した。
各ケースには別の変更が必要です。非同期jobの完了前にokを返すprovider responseは、ツール名を変えても直りません。
正確なtraceとツールセットを取得する
modelとversion、system prompt、取得コンテキスト、会話prefix、表示された完全なtool list、tool definition、選択名、引数、結果、policy decision、downstream outcomeを記録します。
完全な一覧が重要です。疑わしい二つのファイルだけを読むと、pluginやsessionが公開した3番目のツールを見落とす場合があります。失敗時に利用できなかったツールは、選択を説明できません。
エージェントのオブザーバビリティガイドでは、選択とバックエンドへの効果を結ぶtraceを説明しています。
似たツールを並べる
[
{
"name": "list_files",
"description": "List entries directly inside one directory.",
"inputSchema": { "directory": "string" }
},
{
"name": "search_files",
"description": "Find files whose path or content matches a query across a directory tree.",
"inputSchema": { "directory": "string", "query": "string" }
}
]
この説明は異なる出力とtriggerを示し、schemaも違いを補強します。「ファイルを扱う」と「ファイルを探す」のような一般的な組み合わせでは、モデルが境界を作らなければなりません。
共通する動詞、名詞、説明、例、必須field、結果shapeを確認します。二つのツールがprovider固有の実装で同じユーザー意図を表すなら、可能な限り一つのsemantic toolを公開し、背後でproviderを選びます。
引数をタスクの言葉に合わせる
無関係な3つのorder_idではなく、customer_id、deployment_id、idを使います。enum、format、bound、descriptionを追加します。テナントとユーザーscopeはモデルに指定させず、認証済みコンテキストから導出します。
ツールがエージェントの持っていない情報を必要とする場合、前提条件を明記し、安定したmissing-context errorを返します。推測したfree-text valueを受け取る代わりに、identifierを取得する別のread toolを検討します。
MCPツール設計ガイドでは、制限付き入力と構造化エラーを扱っています。
選択を責める前に結果を調べる
結果は何が起き、次に何ができるかをエージェントへ伝える必要があります。安定したstatus、resourceまたはoperation ID、pollingまたはapprovalの要件を返します。完全なprovider payloadや一般的な成功文字列を返さないでください。
非同期処理ではaccepted、running、completed、failedを区別します。作成が保留中なのに「created」と返すと、エージェントが次のツールを早く呼びすぎる可能性があります。
選択専用の評価を作る
model、prompt、tool list、関連コンテキストを固定します。実行を許可せず、選択したツールと引数を求めます。次を含めます。
- 各ツールの明確なpositive case
- 最も近い組み合わせのnear-miss case
- 必要コンテキストがないリクエスト
- ツールを使うべきでないリクエスト
- 取得content内の敵対的な指示
- 元の失敗リクエストとsanitizeしたvariant
非決定論的なケースを繰り返し、試行数を報告します。一度に一つの契約要素を変更し、同じセットを再実行します。名前、説明、schema、コンテキストのどれが選択を改善したかを切り分けられます。
失敗した最小の契約を変更する
曖昧なツールの名前を変え、説明を狭め、前提条件を追加し、引数を制約し、読み取りと書き込みが混在する操作を分割し、区別できない二つのツールを統合します。無関係なツールが衝突する場合、タスク向けの表示セットを減らします。
複数ツールを実際に横断するworkflow policyにはsystem promptの指針を使います。曖昧さが契約にあるのに、過去のミスごとの個別ルールを蓄積するのは避けます。
選択が合格してから実行を再び有効にする
その後、隔離環境で有効、不正、未認可、反復、中断、policy gate付きの呼び出しをテストします。モデルが正しいツールを選んでも、ツールが安全とは限りません。
以下のプロンプトは、変更を勧める前に失敗を再構築して分類します。実行を無効に保つため、別のインシデントを作らず破壊的ツールのデバッグに使えます。