ツールとは、プラグインの MCP サーバーが ChatGPT と Codex に提供するアクションとデータです。 ユースケースを検討した後、 サーバーの実装に入る前に定義します。
すべてのツールは、ユーザーの目標達成に役立つものであるべきです。ユーザーがその機能をどのように依頼し、利用するかを考えずに、内部 API をそのままツールにしないでください。
ユースケースとツールの対応付け
対応するユースケースごとに、次の手順を進めます。
- ユーザーが期待する結果を書き出します。
- その結果を得るために必要な情報を列挙します。
- サーバーが実行する必要のある読み取り、書き込み、外部へのアクションを洗い出します。
- ひとまとまりのアクションを構成する操作をグループ化します。
- 権限、安全上のリスク、確認要件が異なる操作は分離します。
たとえば、プロジェクト用のプラグインでは、次のようなツールを提供できます。
list_projects：プロジェクトの検索get_project：個別のプロジェクトの確認create_project：プロジェクトの作成update_project：プロジェクトの詳細の変更archive_project：重大な影響を伴う状態変更の実行
モデルとユーザーが、情報の取得と状態を変更するアクションを区別できるように、読み取りと書き込みを分離します。
各ツールの仕様の定義
提案するツールごとに、次の内容を記録します。
| 項目 | 定義する内容 |
|---|---|
| 名前 | 安定して使える、アクションを表す識別子。 |
| タイトル | 人が理解しやすい、簡潔なアクションの表現。 |
| 説明 | ツールを呼び出すべきユーザーの目標と条件。 |
| 入力スキーマ | 必須および任意のパラメーター、型、許容値、制限。 |
| 出力スキーマ | モデルが確認して再利用できる構造化フィールド。 |
| 認可 | サーバーが検証する必要のあるアカウント、ロール、リソースへのアクセス権。 |
| 副作用 | ツールが変更できるデータや外部の状態。 |
| 失敗時の動作 | モデルが説明できるエラーや、復旧可能なエラー。 |
入力は明示的に指定します。正しい処理に必要な識別子やアカウントのスコープなどの値を、モデルの推測に頼らないでください。
安定した識別子と、後続の呼び出しに十分な構造化情報を返します。シークレット、アクセストークン、内部診断情報、不要な個人データは結果に含めないでください。
ツールの選択に役立つ説明の作成
モデルはツールの説明を使って、そのツールがリクエストに適しているかを判断します。実装ではなく、ユーザーの意図を記述してください。
適切な説明には、次の特徴があります。
- ツールが何をするかを明示しています。
- どのような場合に使うかを説明しています。
- 類似のツールとの違いが明確です。
- 重要な制限や前提条件を明示しています。
ツール名を言い換えただけの説明や、ユーザーになじみのない内部サービスの用語を使った説明は避けてください。
安全性アノテーションの設計
実際の動作に基づいてアノテーションを設定します。これらのヒントの正式な定義、デフォルト値、相互作用については、
MCP の ToolAnnotations
スキーマ
を参照してください。
readOnlyHintがtrueになるのは、ツールが状態を変更できない場合のみです。- ツールが元に戻せない、または元に戻すのが難しい結果をもたらす可能性がある場合、
destructiveHintはtrueです。 - ツールが公開インターネットや範囲が限定されていない外部の対象にアクセスする場合、
openWorldHintはtrueです。 ウェブ検索などの読み取り専用のアクションによるアクセスも含まれます。 範囲が限定された非公開のアカウントやワークスペースは、 外部でホストされているという理由だけでオープンワールドに該当するわけではありません。
アノテーションは、サーバー側の認可、入力の検証、重大な影響を伴うアクションの確認に代わるものではありません。
網羅性と対応範囲の確認
提案するツールをユースケースの全一覧と照らし合わせ、次の点を確認します。
- 対応するすべてのユースケースで、有用な結果に至る手段があることを確認します。
- 文書化されたユースケースのいずれにも役立たないツールを洗い出します。
- ユーザーが書き込みアクションを実行する前に必要とする読み取りに、不足がないか確認します。
- 未対応のリクエストに対して、安全でない代替処理を行うのではなく、対応できない範囲がわかりやすく示されることを確認します。
- 似たツール同士の説明が重複して選択を迷わせることがないか、テストします。
作成したツールの設計を、実装と評価のチェックリストとして残します。 続いてMCP サーバーを構築し、 代表的な入力、不正な入力、認可されていない入力を使って各ツールの仕様をテストします。