この記事は、WebMCPでサイトの機能をAIに公開しようとしている、開発担当者と企画担当者に向けて書いています。テーマは、ツールの実行が失敗したときの「エラーの返し方」です。読み終えると、どんな失敗を想定し、何を返し、どこで人に引き継ぐかを、自社で決められるようになります。なお、WebMCPはW3Cのコミュニティグループが進める草案で、内容が変わり続けています。この記事は2026年10月時点の草案とChromeの資料に基づきます。
なぜエラー設計が重要なのか
人が使う画面では、失敗は目に見えます。赤い文字が出る、ボタンが動かない、ページが戻る。人はそれを見て、入力をやり直すか、あきらめるかを自分で決めます。
AIエージェントは違います。頼りになるのは、ツールから返された内容だけです。返事が「失敗しました」の一言なら、何が悪いのか分かりません。同じ操作を繰り返すか、別の手を探すか、利用者に尋ねるか。その選択の材料がないまま、エージェントは次の一手を決めることになります。
つまり、エラーの文面は、AIにとっての「画面」です。丁寧に設計しておけば、AIは自力で立て直せます。雑に作れば、利用者の前で同じ失敗を繰り返すかもしれません。人間向けのサイトで、エラー表示を整える作業と同じ考え方です。
失敗の種類と、仕様に出てくるエラー名
草案には、ツールの実行が失敗したときのエラーとして、NotFoundError、DataError、OperationError、AbortErrorの4つが出てきます。まず、サイトの側で想定しておきたい失敗を、4つに分けて整理します。
| 失敗の種類 | 起きる場面 | 名前から読み取れる対応 |
|---|---|---|
| 対象がない | 呼ばれたツールや、探した予約・商品が存在しない | NotFoundError |
| 入力の誤り | 日付の形式が違う、必須の項目が欠けている | DataError |
| 操作の失敗 | 在庫切れ、通信の不調、サーバー側の不具合 | OperationError |
| 中断 | 利用者や呼び出し側が、途中で取りやめた | AbortError |
右の列は、エラー名の意味からの読み取りです。どの場面でどのエラーが返るかの細かい規則は、草案で確認してください。また、他のオリジンから存在しないツールを呼ぶと、探られるのを防ぐために、存在しない場合でもNotFoundErrorが返る仕様になっています。そのため、呼び出し側から見ると、「ツールがない」理由は区別できません。サイト側のエラー文を考えるときは、この点を覚えておくと混乱しません。
エラー名は、大まかな分類にすぎません。AIが次の手を選ぶ決め手になるのは、サイトが書く説明文です。次の章で、その中身を考えます。
良いエラーメッセージの4つの要素
AIが立て直せるエラーには、次の4つの要素が入っています。短い文で十分です。
- 何が悪かったか。どの項目の、どこが問題かを名指しします。
- どう直せばよいか。正しい形式や、選べる値の例を示します。
- 再試行してよいか。直せば成功するのか、何度やっても同じなのか。
- 人に引き継ぐべきか。AIの判断を超える場合は、利用者に確認するよう促します。
草案の既知の課題にも、関連する話があります。入力のスキーマ（入力項目の形の定義）を厳しくしすぎると、エージェントが止まってしまうことがある、というものです。そのため、executeの側でも入力を検証し、次の手が分かるエラーを返すことが勧められています。スキーマは入口、エラーメッセージは出口の案内、と考えると整理しやすいでしょう。入力の定義については、入力スキーマの書き方も参考になります。
不親切なエラーと親切なエラー（架空の例）
宿の予約ツールを例にします。以下はすべて架空の例で、実在のサービスとは関係がありません。
| 場面 | 不親切な返し方 | 親切な返し方 |
|---|---|---|
| 日付の形式が違う | 入力エラー | 「checkIn」が日付として読めません。「2026-11-03」の形式で、もう一度送ってください。 |
| 部屋が満室 | 予約に失敗しました | 指定の日は満室です。前後2日の空きなら、検索ツールで調べられます。同じ条件の再送は、結果が変わりません。 |
| 一時的な不調 | エラーが発生しました | 処理が一時的に完了しませんでした。少し待って、1回だけ再試行できます。予約は確定していません。 |
| 会員のみの機能 | 権限がありません | この操作は、利用者本人の確認が必要です。画面で本人確認を進めるよう、利用者に伝えてください。 |
親切な側の文は、どれも「事実」「次の手」「再試行の可否」のどれかを含んでいます。長くする必要はありません。むしろ、一つのエラーに指示を詰め込みすぎないことが大切です。
エラーに入れてはいけない情報
親切にしようとして、情報を入れすぎる失敗もあります。エラーの内容は、エージェントを通じて、外部のAIモデルや記録に渡る可能性があります。次のものは、エラーに入れないのが無難です。
- 他の利用者の氏名、メールアドレス、予約の中身
- 内部のシステム名、データベースの構造、ファイルの場所
- 例外の生のメッセージや、スタックトレース（失敗の履歴の記録）
- 「この番号は存在しません」のように、有無を探る手がかりになる表現
草案も、リスクの一つとして、過剰な情報によるプライバシーの漏えいを挙げています。また、ツールの出力に悪意のある指示が紛れる、プロンプトインジェクションも課題です。エラー文に、ユーザーが入力した文字をそのまま埋め込む場合は、特に注意してください。外部から来る文字を含む場合は、注釈のuntrustedContentHint（返す内容が信頼できないかもしれないという目印）を付ける選択肢があります。
詳細な原因は、サイト側の記録に残します。AIに返すのは、次の手を決めるのに必要な分だけです。
中断と、途中状態の扱い
executeには、入力のオブジェクトに加えて、中断用のsignal（AbortSignal）が渡されます。呼び出し側が実行を取りやめると、この信号で知らせが来ます。草案には、中断を知らせるイベントtoolcancelも定められています。
設計で考えるべきなのは、中断された時点で、処理がどこまで進んでいたかです。次の3つを区別しておくと、後始末が楽になります。
- まだ何も変えていない段階なら、そのまま終了してよい。
- 変更の途中なら、元に戻すか、最後まで終えるかを決めておく。
- 外部へ送信した後なら、取り消せないものとして扱い、状況を返す。
中断されたあとに、AIが「予約できたのか」を知りたくなる場面は多いはずです。確認用の読み取りツールを別に用意し、状態を後から調べられるようにしておくと安心です。草案では、読み取りだけのツールにはreadOnlyHintを付けられます。
二重実行と再試行を安全にする
失敗の知らせが届かなかったり、AIが念のためにもう一度呼んだりして、同じ操作が二度実行されることは、十分にありえます。これを安全に受け止める考え方が、冪等性（べきとうせい）です。「同じ操作を何回行っても、結果が一回分と同じになる」性質のことです。
たとえば、次のような工夫が考えられます。
- 予約には、呼び出しごとに固有の識別番号を持たせ、同じ番号の再送は、新しい予約にしない。
- 「更新」は、「追加」より安全に作る。同じ値の上書きなら、何度行っても同じ結果になる。
- 再試行してよい失敗か、してはいけない失敗かを、エラーの文面ではっきり書く。
草案には、実世界への影響や取り消せない操作を示す注釈consequentialHintがあります。購入や送金のような操作に付けると、クライアントの側で確認を必須にできます。ただし、草案の本文は、実行時の確認を必須とは定めていません。確認の仕組みは、クライアント次第です。サイト側でも、二重実行に耐える設計にしておくのが現実的です。ツールそのものの切り分けは、ツール設計の考え方で扱っています。
人に引き継ぐ導線をつくる
Chromeの資料は、WebMCPを、主にローカルのブラウザで人が関わる使い方として想定しています。完全に自動で、画面なしに動かす使い方を、主な対象にしたものではありません。この前提に立てば、エラーの最後の受け皿は人です。
引き継ぎの導線は、次のように用意します。
- AIでは解決できない失敗の種類を、あらかじめ決めておく（本人確認、支払い、例外対応など）。
- その場合のエラー文に、「利用者に画面での操作を依頼してください」と書く。
- 画面側に、途中までの入力が残っているようにしておく。
- 最終的に問い合わせ窓口へ進める、人間向けの導線も用意する。
AIが失敗しても、利用者が画面で続きをできる。この構えがあれば、AI向けの入口は、安心して公開できます。全体像は、WebMCPとAIエージェント対応サイトの全体像でまとめています。
エラー文を決めるときの進め方
エラーの文面は、思いついた順に書くと、ばらつきが出ます。次の順で進めると、ツールが増えても揃えやすくなります。
1. 失敗の場面を書き出す
ツールごとに、起こりそうな失敗を挙げます。入力が足りない、対象がない、相手のシステムが応答しない、途中で中断された。ここでは、分類を気にせず、数を出すことを優先します。
2. 場面ごとに「次の手」を決める
それぞれの失敗について、AIにしてほしいことを一つ決めます。入力を直して再送する、別のツールで調べる、利用者に尋ねる、何もしないで終える。次の手が決められない失敗は、人に引き継ぐ失敗として扱います。
3. 型をそろえて文にする
「何が悪い」「どう直す」「再試行の可否」の順に、短く書きます。ツールが違っても、語順が同じなら、AIは読み取りやすくなります。用語も統一します。同じ項目を「日付」と「期日」の両方で呼ぶと、混乱のもとです。
4. 実際に失敗させて確かめる
わざと誤った入力を送り、エラーを返させます。Chromeの資料によれば、DevToolsでツールの確認やスキーマの検証ができます。検証用の拡張機能も紹介されています。返ってきた文だけを読んで、次の手が分かるか。自分で確かめてください。
見直しのためのチェックリスト
公開の前に、次の点を確かめてください。すべてに答えられれば、最初の版としては十分です。
- 失敗の種類ごとに、AIがとる次の手を言葉にできているか。
- エラー文に、他人の情報や内部の情報が混ざっていないか。
- 同じ操作を二度呼ばれても、二重に処理されないか。
- 中断されたとき、途中までの変更の扱いが決まっているか。
- 取り消せない操作に、注釈と、人による確認の導線があるか。
- 失敗した内容を、サイトの側で記録し、後から見直せるか。
最後の項目は、運用の話です。どんなエラーが多く出ているかを見れば、説明文や入力の定義の弱いところが分かります。AIの呼び出しは、人の操作とは違う癖で失敗することがあります。数字を見るときも、断定せず、観察しながら直していく姿勢が合っています。
仕組みごとの役割分担を整理する
ここまで出てきた仕組みを、役割ごとに並べます。どれか一つに頼らず、重ねて使うのが基本です。
| 仕組み | 主な役割 | エラーとの関係 |
|---|---|---|
| 入力スキーマ | 受け取る入力の形を定義する | 誤りを入口で減らす。厳しすぎると止まることもある |
| execute内の検証 | 入力を実行側でも確かめる | 次の手が分かるエラーを返す場所 |
| signal | 中断を受け取る | 途中状態の後始末を決める手がかり |
| 注釈（ヒント） | 読み取り専用、信頼できない内容、影響の大きい操作を示す | クライアントが確認や無害化を行う材料になる |
| 画面側の導線 | 人が続きを行う | AIで解決できない失敗の最後の受け皿 |
草案は、宣言した内容と実際の動作が一致する保証がないことも、課題として認めています。たとえば、名前は確認用なのに実際は購入してしまう、という食い違いです。エラー設計も同じで、文面とふるまいがずれないよう、実装のあとに実際の動作と見比べる作業を入れてください。
注意点
- エラー名の使い分けや、返す文面の形式は、草案の更新で変わる可能性があります。実装の前に最新の資料を確認してください。
- 草案には、ツールの内容を自動で更新する仕組みがありません。エラー文を含む説明を変えるときは、登録を解除して、再登録する必要があります。
- エラーの設計は、実際にAIに使わせて、どこで止まるかを観察して直すのが確実です。机上の想定だけでは、見落としが残ります。
- 個人情報や法務にかかわる判断は、専門家への確認が必要です。
Otsumuに相談できること
エラーの種類の洗い出しと、文面の見直しは、自社の開発担当者だけでも始められます。まずは、一つのツールで、失敗の場面を書き出してみてください。
一方で、複数のシステムにまたがる再試行の設計や、人への引き継ぎを含む業務の組み直しは、判断が増えます。そのような場合は、お声がけください。Otsumuは、AIを前提に事業と業務を組み直す、AIファーストの事業再構築を支援しています。
具体的な開発についてはAIエージェント開発を、ご相談はお問い合わせをご覧ください。
この記事について
この記事は、Otsumu株式会社が執筆しました。確認日は2026年10月20日です。WebMCPの仕様は変動中のため、最新の情報は参照元でご確認ください。参照元：W3C Web Machine Learning Community Groupの仕様草案、Chromeの公式資料、提案のリポジトリ。
執筆：Otsumu株式会社 ／ 編集日 2026.10.20