ツールの定義

ツールは、プラグインの MCP サーバーが ChatGPT と Codex に提供する操作やデータです。ユースケースを洗い出し、サーバーを実装する前にツールを定義します。

どのツールも、ユーザーの目的を達成するのに役立つものにします。内部 API をそのままツールにする前に、ユーザーがどのような言葉で依頼し、その機能をどう使うかを考えます。

ユースケースとツールの対応付け

対応するユースケースごとに、次の手順でツールを整理します。

1. ユーザーが期待する結果を書き出します。
2. その結果を得るために必要な情報を列挙します。
3. サーバーが実行する必要のある読み取り、書き込み、外部システムに対する操作を特定します。
4. 一連の処理がユーザーにとって一つの操作に当たる場合は、まとめます。
5. 必要な権限、安全上のリスク、確認の要件のいずれかが異なる操作は分けます。

たとえば、プロジェクト管理用のプラグインでは、次のツールを提供できます。

• list_projects でプロジェクトを探します。
• get_project で個別のプロジェクトの詳細を確認します。
• create_project でプロジェクトを作成します。
• update_project でプロジェクトの詳細を変更します。
• archive_project でプロジェクトをアーカイブします。これは影響の大きい状態変更です。

モデルとユーザーが情報の取得と状態を変更する操作を区別できるように、読み取りと書き込みは別々のツールにします。

ツールごとの仕様

設計するツールごとに、次の項目を記録します。

入力は明示します。識別子やアカウントの適用範囲など、正しく動作するために必要な値をモデルに推測させないでください。

結果には、後続の呼び出しで使える安定した識別子と十分な構造化情報を含めます。シークレット、アクセストークン、内部の診断情報、不要な個人データは含めないでください。

ツールの選択に役立つ説明

モデルはツールの説明をもとに、そのツールがリクエストに適しているかを判断します。実装の詳細ではなく、そのツールでユーザーが何をしたいのかを記述します。

説明を書く際は、次の点を押さえます。

• ツールで何ができるかを明示します。
• どのようなときに使うのかを説明します。
• 類似のツールとの違いを示します。
• 重要な制限や前提条件を明記します。

ツール名を言い換えただけの説明や、ユーザーになじみのないサービス内部の用語を使った説明は避けます。

安全性に関するアノテーションの設計

アノテーションはツールの実際の動作に合わせて設定します。各ヒントの正式な定義、既定値、ヒント間の関係については、MCP の ToolAnnotations スキーマを参照してください。

• readOnlyHint を true にするのは、ツールが状態を変更できない場合に限ります。
• destructiveHint は、ツールの操作によって元に戻せない結果や、元に戻すのが難しい結果が生じ得る場合に true にします。
• openWorldHint は、ツールが公開インターネットにアクセスする場合や、アクセス対象となる外部リソースの範囲が限定されていない場合に true にします。ウェブ検索などの読み取り専用の操作も該当します。アクセス範囲が限定された非公開のアカウントやワークスペースは、外部でホストされているという理由だけでは該当しません。

アノテーションを設定しても、サーバー側での認可や入力検証、影響の大きい操作を実行する際の確認は必要です。

対応範囲と制約の確認

設計したツールをユースケースの一覧全体と照らし合わせます。

1. 対応するすべてのユースケースで、ツールを使って有用な結果を得られることを確認します。
2. 一覧のどのユースケースにも対応していないツールを特定します。
3. 書き込みの前にユーザーが必要とする読み取り操作に抜けがないか確認します。
4. 対応範囲外のリクエストに対して、危険な代替操作を行わず、何に対応できないのかをわかりやすく示せることを確認します。
5. 類似する二つのツールの説明が重なり、モデルが選択に迷うことがないかテストします。

こうしてまとめたツールの設計内容は、実装と評価のチェックリストとして残します。次に、MCP サーバーを構築し、代表的な入力、不正な入力、必要な権限を持たないユーザーからの入力を使って、各ツールが仕様どおりに動作するかテストします。