MCP tool に outputSchema を宣言すると、成功結果は structuredContent を返し、そのJSON objectがschemaへ適合する契約になる。warningを消すために空のobject schemaだけを付けたり、handlerが返していない理想形を先に書いたりすると、モデルへの情報価値がないか、クライアント側の実行時validationで失敗する。

追加手順

まず公開ツールを登録一覧から全件列挙し、各handlerの成功経路で返すstructured dataを確認する。変数参照で返している場合は、その変数を組み立てる箇所とAPI response型まで追う。error結果はschema validation対象外になり得るため、成功経路の安定したトップレベルキーと型を正本にする。

schemaは、後続処理が使う success、action、対象ID、件数、結果配列などのトップレベルpropertiesを明示し、成功時に常に存在するものだけrequiredへ入れる。API追加フィールドを壊したくない場合はトップレベルの追加propertyを許可しつつ、既知キーを空にしない。変化しやすい大きな入れ子はobjectとして許容し、安定した外形から段階的に精密化すると安全である。

強制と検証

ツール登録時に名前に対応するoutput schemaが無ければエラーにし、新規ツールがschemaなしで公開されるのを防ぐ。テストでは登録一覧を単一の基準にして、全ツールが非空のobject schemaを持つこと、JSON Schema validatorが全schemaをコンパイルできること、実際のtools/listでschemaが公開されることを確認する。代表的なtool callはoutput schemaを認識するMCP client経由で実行し、structured resultのvalidationも通す。

モデルに読ませる必要がある情報は、structured dataだけに置かず可読な content にも残す。output schemaは機械利用を安定させる契約であり、すべてのMCP clientがstructured dataをモデルへ渡す保証ではない。