tool-schema-design

ツールスキーマの設計

曖昧または破壊的な選択肢よりも、安全で意図した呼び出しをモデルが選びやすくします。

使用する場面

• 関数呼び出し、MCP、プラグイン、または内部エージェントツールを追加または改訂するとき。
• 過負荷な API 操作を、モデルが利用できるアクションに分割するとき。
• 誤ったツール選択、不正な引数、または捏造されたフィールドを減らすとき。
• 認可、確認、冪等性、エラーの動作を文書化するとき。

入力

対応するユーザーの意図、バックエンド操作のセマンティクス、必要な認証情報、実行者とテナントのスコープ、副作用、可逆性、レイテンシ、レート制限、障害モード、プロバイダー固有のスキーマ制約を収集します。代表的な有効リクエストと無効リクエストを用意します。

出力要件

以下を作成します。

1. ツール境界の判断と重複の分析。
2. 使用条件と非使用条件を明示した、モデル向けの名前と説明。
3. 制約、例、未知のフィールドの扱いを含む有効なパラメーターのスキーマ。
4. 副作用、確認、認可、冪等性、タイムアウト、エラーに関する契約。
5. 正常系、境界値、敵対的入力、ツール選択のテスト。
6. 検証結果とプロバイダー固有の制限事項。

ワークフロー

1. ツールごとに、一貫したユーザーの意図を1つ定義します。権限、副作用、または必須フィールドが異なるモードはツールを分割し、名前が区別できない小さすぎるツールセットは避けます。
2. 動詞で始まる安定した名前を選びます。ツールの機能、呼び出す条件、呼び出さない条件、変更する状態を説明に記載します。
3. バックエンド SDK をそのまま反映するのではなく、ユーザーの意図に基づいてパラメーターを設計します。不可欠なフィールドのみを必須にし、選択肢が固定されている場合は列挙型を使用し、数値と長さの範囲を設定して、形式と単位を説明します。組み合わせと変更のパターンについては、schema-patterns.md を参照してください。
4. 実行環境が対応している場合は、未知のフィールドを拒否します。条件によって形状が異なる場合は、説明文だけに依存せず、別々のツールまたは明示的なスキーマ分岐で表現します。
5. 実行者の ID、認可スコープ、信頼できるテナントコンテキストはサーバー側に保持します。実行環境がすでに把握している秘密情報やクレームをモデルに要求しないでください。
6. JSON 形状の外で実行セマンティクスを定義します。読み取り専用か変更を伴うか、確認レベル、冪等性キー、再試行の安全性、タイムアウト、部分的な成功、補償アクションを定めます。
7. 簡潔で構造化された結果と、安定した機械可読エラーコードを返します。入力無効、認可拒否、確認が必要、競合、レート制限、依存関係の障害、未知の障害を区別します。
8. 隣接するツールとのツール選択をテストし、有効、省略、追加、境界値、悪意のある入力、古い入力を使って実行をテストします。

スキーマを実行環境に組み込む前に、python3 scripts/validate_tool_schema.py tool.json --strict を実行します。構造上のエラーは常に失敗になります。strict モードでは、自由形式のコマンド実行、呼び出し元が制御する権限フラグ、認証情報のパラメーター、任意の URL／パス、許容範囲が広すぎる未知のフィールド、有用な上限の欠如など、レビューで指摘された事項も失敗になります。structurally_valid が示すのは JSON の形状のみです。strict_pass: true であっても、セマンティクス上の安全性、認可、サンドボックス、プロバイダーとの互換性、実装を保証するものではありません。

安全性と権限

• ツールの実装で認可を強制します。セキュリティ境界としてモデル向けの説明に頼ってはいけません。
• 購入、メッセージ送信、デプロイ、削除、権限変更など、重大な影響を伴う変更には明示的な確認を必須にします。
• ユースケースとサンドボックス上必要な場合を除き、秘密のパラメーター、生の認証情報、制限のないシェルコマンド、任意の URL やファイルパスを公開しないでください。
• 許可リスト、スコープを限定した識別子、ドライラン、冪等性キー、可逆的な操作を優先します。
• ツールの出力をモデルのコンテキストに戻す前に、信頼できない入力として扱います。

検証

• 同梱の構造／ヒューリスティックバリデーターや汎用 JSON Schema バリデーターだけでなく、対象プロバイダーでスキーマを解析・検証します。
• すべての必須フィールドが宣言されていること、すべての列挙値が選択可能であること、配列に項目の形状が定義されていること、不明なフィールドの扱いが実装と一致していることを確認します。
• このツール、隣接するツール、またはいずれのツールも選択すべきでない場合を想定した対照的なプロンプトを実行します。
• 拒否された呼び出しや確認が必要な呼び出しによって、副作用が発生しないことを検証します。
• 実装の動作、返されるエラー、ドキュメントの間に差異がないか比較します。

障害への対応

• プロバイダー間でスキーマ機能に違いがある場合は、サポートされている範囲に絞り、実行時検証で失われる制約を記録します。
• ツールの選択が曖昧な場合は、名前と説明を明確にするか、区別できないツールを統合します。プロンプトの順序に依存してはいけません。
• 不正な呼び出しが続く場合は、ネストを簡素化し、冗長なフィールドを削除し、スキーマの制約とサーバー側の検証を追加します。
• 変更処理がタイムアウトした場合は、再試行する前に冪等性キーで操作のステータスを照会します。
• バックエンドの動作が契約に反する場合は、重大な操作をフェイルクローズし、リリース前にアダプターを修正します。

例

「アシスタントがカレンダーの予定を再設定できるようにする」場合は、予定の検索と変更を分けます。変更ツールには reschedule_calendar_event という名前を付け、不透明な予定 ID、タイムゾーン情報を含む開始・終了日時、冪等性キーを必須にします。アカウント ID はサーバー側で管理し、不明なフィールドは拒否します。参加者に通知される場合は確認を必須にし、プレビューまたは更新後の予定と、安定したステータスを返します。また、タイムゾーンの欠落、終了日時が開始日時より前の場合、古い予定、権限のないカレンダー、重複した再試行、「予定を作成する」などの類似プロンプトをテストします。