ツールのエラーメッセージをAIが読んで直せる形にする:失敗の返し方の設計

公式資料で確認できること

エラーの返し方について、公式資料から確認できたのは次の範囲です。

• MCPの仕様(確認したのは2025-06-18版)では、ツールのエラーは2種類に分かれます。未知のツール名や不正な引数などは JSON-RPC のプロトコルエラー、API失敗や業務ロジックのエラーは結果に isError: true を付けて返す「ツール実行エラー」です。仕様の例は Failed to fetch weather data: API rate limit exceeded という1文で、文面の書き方までは規定していません(MCP Tools仕様)。より新しい版が出ている可能性があるため、実装時は最新版を確認してください。
• Claude APIのドキュメントは、tool_result に is_error: true を付けてエラーを返す方法を説明しています。例では、天気情報サービスのAPIが利用できないことを、HTTP 500とともに返しています。引数が不正な場合、Claudeは2〜3回修正して再試行してから、ユーザーに謝る動きをするとも書かれています(Handle tool calls)。

つまり、エラーを「失敗」と「失敗の中身」に分けて返す枠組みは用意されていますが、中身の設計は作る側に任されています。以降の型と判断表は、この空白を埋めるための編集上の提案です。

エラー文の型

プレーンテキストで十分です。AIが読む文なので、行頭のラベルを固定して、毎回同じ順で書きます。

エラー種別: 入力不正 | 見つからない | 候補が複数 | 認証 | 混雑 | 一時障害 | 権限 | 状態不明
何が起きたか: 1文で事実だけ
原因: 分かっている範囲。推測なら「推測」と書く
直し方: 変える引数と、使える値や形式の例
再試行: 不可 | 同じ内容で可(N秒後) | 引数を直せば可 | 確認後のみ | 人の操作が必要 | 不明(追加確認が必要)
副作用: なし | あり(内容) | 不明(確認方法)

各行の意図は次のとおりです。

• エラー種別:AIが分岐するための札です。自由文だけだと、種別の判断を毎回モデルに任せることになります。
• 直し方:「path は /data/reports/ 配下の相対パスで指定」のように、引数名と正しい形を入れます。
• 再試行:次の行動を示す行です。「不可」と明記して繰り返しを避けるよう伝え、呼び出し側でも再試行を制御します。
• 副作用:書き込み系ツールでは必須です。タイムアウト時に「実行されたのか不明」だと、再試行で二重実行になる恐れがあります。

失敗の種類ごとの判断表

種別ごとに、再試行の可否と次の行動の目安をまとめます(編集上の提案です。上限回数などは、ご自身のシステムに合わせて決めてください)。書き込み系では、未実行と確認できるか、同じ要求を繰り返しても重複処理されない仕組みがある場合に限り再試行します。

• 入力不正、再試行：引数を直せば可、AIに期待する次の行動：指摘された引数を直して1回再試行、人に回す条件：直し方を2回試しても同じエラー
• 見つからない・候補が複数、再試行：引数を直せば可、AIに期待する次の行動：一覧・検索ツールで候補を探す、人に回す条件：候補が複数あり選べない
• 認証・権限、再試行：同じ条件では不可、AIに期待する次の行動：許可された認証更新手段があれば使い、それ以外は状況を報告、人に回す条件：権限付与や再ログインが必要
• 混雑(レート制限)、再試行：待てば可、AIに期待する次の行動：指定秒数だけ待って同じ内容で再試行、人に回す条件：数回待っても解消しない
• 一時障害、再試行：同じ内容で可、AIに期待する次の行動：間隔を空けて限定回数だけ再試行、人に回す条件：上限回数に達した
• 状態不明(書き込み中の中断)、再試行：確認後のみ、AIに期待する次の行動：まず読み取りツールで結果を確認、人に回す条件：確認手段がない

「混雑」と「一時障害」は待てば直る可能性がありますが、「認証・権限」は認証状態や権限を変えずに繰り返しても、通常は解消しません。ここを区別して書くだけで、空回りの多くは減らせるはずです。ただし、これは設計上の見込みであり、私が実測したものではありません。

書き換え例

以下はすべて説明用の例で、実在のツールや実行結果ではありません。

例1:入力不正

悪い例:Error: invalid argument

エラー種別: 入力不正
何が起きたか: read_file の path が許可範囲外です。
原因: path に絶対パス「/etc/hosts」が渡されました。
直し方: プロジェクト直下からの相対パス(例: reports/2026-09.csv)で指定してください。
再試行: 引数を直せば可
副作用: なし

例2:混雑

悪い例:429

エラー種別: 混雑
何が起きたか: 1分あたりの呼び出し上限に達しました。
原因: 短時間に search_orders を連続で呼びました。
直し方: 引数の変更は不要です。
再試行: 同じ内容で可(30秒後)
副作用: なし

例3:認証

悪い例:Request failed

エラー種別: 認証
何が起きたか: アクセストークンの有効期限が切れています。
原因: 認証サーバーが 401 を返しました。
直し方: AI側では直せません。
再試行: 人の操作が必要(再ログイン後に再開)
副作用: なし

例4:検索結果が複数

悪い例:Ambiguous

エラー種別: 候補が複数
何が起きたか: 顧客名「山田」に一致する顧客が3件あります。
原因: 名前だけでは1件に絞れません。
直し方: customer_id(例: C-1042)を指定してください。候補は list_customers で取得できます。
再試行: 引数を直せば可
副作用: なし

例5:書き込み中のタイムアウト

悪い例:Timeout

エラー種別: 状態不明
何が起きたか: create_invoice の応答を30秒以内に受信できず、呼び出し側が待機を終了しました。
原因: 不明。サーバー側の処理が進行中か完了済みの可能性もあります。
直し方: この例では、作成時に渡した request_id=REQ-1042 で get_invoice_status を呼び、処理状態を確認してください。
再試行: 確認後のみ。未実行が確定するか、同じ request_id で重複作成を防げる場合に限ります。検索で見つからないだけなら再試行せず、人に確認を求めてください。
副作用: 不明(get_invoice_status で処理状態を確認。確認できなければ人に回す)

例5が型の価値を最もよく示します。「Timeout」とだけ返すと、AIは善意で再実行し、請求書が二重に作られるかもしれません。

実装と運用で気をつける点

• 返すのはツール実行エラーとして:MCPでは、API失敗や入力データの誤りは isError: true の結果に入れる分類です。結果の content に上の型を入れ、呼び出し側がその結果をモデルへ渡します。プロトコルレベルの不正(未知のツールなど)は別経路になる点に注意してください。
• 機密を書かない:スタックトレース、内部のホスト名、トークンの断片はエラー文に入れないでください。「直し方」に必要な情報だけを残します。
• エラー文も信用しすぎない:Claudeのドキュメントは、ツール結果には外部由来の内容が含まれうるため、間接的なプロンプトインジェクションに備えて信頼しないよう警告しています。外部APIのエラー本文をそのまま転記せず、自分で作った定型文に差し替えるのが安全です。
• 再試行の上限は呼び出し側でも持つ:ドキュメントにはClaudeが2〜3回再試行するという記述がありますが、他のモデルや環境では挙動が違いえます。上限は自前のループで管理してください。
• 人の確認:削除や送信など副作用のある操作は、MCP仕様も人が拒否できる仕組みを置くことを推奨しています。「人の操作が必要」と返す条件は、あらかじめ決めておきましょう。

既存のエラー文をAIに見直させる依頼文

手元のツールのエラー文を一覧にして、次の依頼文と一緒に渡します。実行前にコードや文面を必ず自分で確認してください。

あなたはAIエージェント向けツールの設計レビュアーです。
以下は私のツールが返すエラー文の一覧です(機密情報は伏せ済み)。
各エラーについて、次の形式に書き換えてください。
  エラー種別 / 何が起きたか / 原因 / 直し方 / 再試行 / 副作用
ルール:
- 分からないことは推測と明記し、断定しない
- 直し方には引数名と正しい値の例を入れる
- 再試行は「不可・同じ内容で可(待ち時間)・引数を直せば可・確認後のみ・人の操作が必要・不明(追加確認が必要)」から選ぶ
- 書き込み系は、実行されたか不明な場合の確認方法を書く。確認手段が不明なら、その旨を明記して人に回す
- 未実行の確認や重複処理を防ぐ仕組みがない書き込みは、再試行可にしない。確認用の関数や引数を創作しない
- トークン、内部URL、個人情報をエラー文に含めない
最後に、情報が足りず書き換えられなかったエラーと、追加で知りたい情報を列挙してください。

【ツール名と役割】
【エラー文の一覧】

AIが出した書き換え案は、そのまま採用せず、実際にそのエラーを起こして文面と一致するかを人が確認します。「直し方」に書かれた関数名や値が実在するかも、必ず確認してください。

導入の手順

1. 直近のログから、エージェントが同じ呼び出しを繰り返した失敗を3〜5件選びます。
2. 上の型で書き換えます。まず「再試行」と「副作用」の2行だけでも入れます。
3. 同じ場面を再実行し、AIが次の行動を変えるかを見ます。
4. 変わらない場合は、ツールの説明文(description)側に不足がないかを見直します。

エラー文は、AIにとって次の行動を決める手がかりです。1行の事実に、直し方と再試行の可否を足し、呼び出し側の制御と合わせて空回りを減らす設計にします。