タスク単位のエージェントAPIは、操作が何を達成するか、いつ使うか、いつ使わないか、どのような効果を持つかを説明します。エンドポイントshapeだけで分かるのは、リクエストの送り方です。ツールを選ぶモデルには両方が必要です。
「セマンティック」という言葉は、実際の役割より大げさに聞こえるかもしれません。実際に行う変更は単純です。データベーステーブルや内部サービスの境界ではなく、ユーザーのタスクを中心にツールを設計します。
有効なエンドポイントでも曖昧になり得る
次のREST操作を考えてみます。
POST /users/{id}/status
{"value":"inactive"}
method、path、body、responseを完全に文書化しても、inactiveがログイン停止、請求停止、担当解除、削除予約、単なるCRMラベル変更のどれを意味するかは分かりません。
人間の開発者は周辺ドキュメントを読み、この曖昧さを一度解消します。モデルは実行のたびに複数のツールから選ぶ可能性があります。
呼び出し可能な契約に意図を含める
弱いツール：
set_user_status
Set a user's status.
タスク単位のツール：
suspend_workspace_member
Temporarily block one member from signing in to this workspace.
Use when an administrator asks to suspend access without deleting the account.
Do not use for billing cancellation, workspace deletion, or permanent data removal.
2番目の説明は、タスク、権限、効果、対象外をモデルへ伝えます。スキーマでも、必要に応じてworkspace、member、reason、approvalまたはoperation IDを特定する必要があります。
MCPツール仕様は、各ツールに名前、説明、入力スキーマ、任意の出力スキーマ、annotationを持たせます。ただし、境界そのものを代わりに書いてはくれません。
一つのタスクを最小限の有用な結果へ対応付ける
次の手順を選ぶエージェントに、バックエンドの完全なresponseが必要なことはほとんどありません。次の判断に必要なフィールドを返します。
注文検索では、次のような結果になります。
{
"orderId": "1842",
"status": "shipped",
"estimatedDelivery": "2026-09-02",
"canCancel": false
}
内部データベースのcolumn、プロバイダーのtoken、200 KBのpayloadを返して、モデルに答えを再発見させないでください。REST APIからMCPへのガイドでは、複数の内部呼び出しを一つのタスク結果へまとめる変換レイヤーを紹介しています。
副作用と失敗時の動作を明示する
各ツールについて次を文書化します。
- 読み取り、書き込み、支出、送信、削除のどれを行うか
- どの呼び出し元とリソースの認可を適用するか
- 承認が必要か
- 操作を安全に再試行できるか
- 次のアクションを変える安定した失敗
- どの結果フィールドが正式な情報か
ツールのannotationは、クライアントがリスクを表示する助けになります。ただし、信頼できないサーバーからのannotationは、クライアント側でも信頼できないものとして扱う必要があります。実際の制限はポリシーとバックエンドで強制してください。
似たツールの境界を明確にする
重複するツールには、明示的な除外条件が必要です。サーバーがsearch_customers、find_contacts、query_accountsを公開するなら、それぞれの説明に担当するentityとタスクを記載します。明確な違いを書けない場合は、ツールを統合するか一つを削除します。
誤ったツール選択のデバッグガイドでは、システムプロンプトを変える前に、ツール一覧と呼び出しトレースから調べます。
選択と実行を別々にテストする
各ツールを選ぶべきプロンプトと、どちらも選ぶべきでないプロンプトを作成します。ツール一覧、説明、モデル、設定を固定し、何も実行する前に選択を記録します。
その後、有効、不正、未認可、反復した入力で実行をテストします。選びやすいツールでも、安全に呼び出せるとは限りません。
最も近い組み合わせから書き換える
説明に共通する単語が最も多い二つのツールを見つけます。それぞれのタスク、使用条件、除外条件、副作用、次の手順に必要な結果を書きます。それでも違いが曖昧なら、実装上の境界がエージェント向けインターフェースへ漏れています。
以下のプロンプトは、この曖昧さのテストを行い、焦点を絞った評価セットを作成します。