AIがツールを正しく選べる説明文の書き方:名前・用途・使わない場面を書き分ける

ツール定義の中で説明文が担う役割

ツール定義は大きく「名前」「説明」「入力の形(スキーマ)」に分かれます。MCP(Model Context Protocol)のTools仕様では、nameが一意の識別子、descriptionが機能の説明、inputSchemaが引数のJSON Schemaです。表示用のtitleは任意項目です。

役割を分けると、書く内容が混ざりません。

• 名前、役割：一覧で見分ける、書くこと：対象と動作が分かる語。複数サービスなら接頭辞をつける
• 説明、役割：呼ぶ・呼ばないの判断材料、書くこと：機能、使う場面、使わない場面、制限
• 引数の説明、役割：入力値の組み立て、書くこと：意味、形式、例

Anthropicのガイドは、複数サービスにまたがる場合にgithub_list_prsのようにサービス名を前につけると選択が曖昧になりにくいと述べています。名前だけで区別しようとせず、説明文で境界線を引くのが基本です。

悪い説明と直した説明を並べる

社内サポート用のエージェントに、次の3つのツールを渡す場面を考えます(説明用の架空の構成です)。

例1:検索系ツールの取り違え

悪い説明

search_docs: 検索する
search_tickets: 検索する

どちらも「検索する」だけでは、「返品の手順を知りたい」という依頼にどちらを使うべきか判断できません。

直した説明

名前: docs_search
説明: 社内マニュアル・手順書(公開済みの文書)をキーワードで検索し、
該当文書のタイトルと抜粋を最大5件返します。
使う場面: 手順・ルール・仕様など「決まっていること」を調べるとき。
使わない場面: 個別の問い合わせ対応履歴を調べるとき(tickets_searchを使う)。
文書の更新や作成はできません。

名前: tickets_search
説明: 過去の問い合わせチケットを、顧客ID・期間・状態で検索し、
チケット番号と件名の一覧を返します。
使う場面: 「以前同じ問い合わせがあったか」「この顧客の対応履歴」を調べるとき。
使わない場面: 手順やルールを調べるとき(docs_searchを使う)。
本文の全文は返しません。全文が必要なら件名一覧のあとでtickets_getを使う。

例2:副作用のあるツール

悪い説明

tickets_create: チケットを作る

直した説明

名前: tickets_create
説明: 新しい問い合わせチケットを1件作成します。作成後は取り消せません。
使う場面: 利用者が「起票して」と明示したとき、または
tickets_searchで同じ件が見つからず、利用者が起票に同意したとき。
使わない場面: 調べ物や回答だけで足りるとき。重複の疑いがあるとき
(先にtickets_searchで確認する)。

副作用がある場合は、「取り消せない」「利用者の同意が必要」といった条件も説明に入れておきます。ただし、説明文はあくまでAIへの手がかりです。MCPの仕様は、安全性のため人が呼び出しを拒否できる状態(human in the loop)が望ましいとし、操作の確認を求めるUIを例に挙げています。取り消せない操作は、説明文だけに頼らず、アプリ側の確認でも止めてください。

説明文のひな形

そのままコピーして、角括弧の部分を埋めて使えます。

名前: [サービス名]_[動詞]_[対象]
説明:
[何を対象に、何をして、何を返すか。1〜2文]
使う場面: [依頼の言い回しを2〜3例。例:「〜を調べて」「〜の履歴」]
使わない場面: [紛らわしい依頼を1〜2例]。その場合は[別ツール名]を使う。
入力の注意: [形式、必須項目、省略した場合の動き]
返さないもの・制限: [件数上限、返らない情報、更新できないこと]
副作用: [なし/あり。ありの場合は取り消せるか、事前確認が要るか]

書くときのコツは3つです。

• 「使わない場面」には必ず代替ツール名を添えます。「使わない」だけでは、AIが行き場を失います。
• 使う場面は、抽象語ではなく利用者が実際に言いそうな依頼文で書きます。
• 制限は「返さないもの」として明記します。Anthropicのガイドも、名前から分かりにくい場合は、ツールが返さない情報を書くよう勧めています。

AIに下書きを作らせる依頼文

説明文の初稿は、AIに作らせても構いません。ただし材料はこちらで渡します。

次のツール一覧について、AIエージェントが選択を誤らないよう
説明文を書き直してください。

【ツール一覧(現在の名前・説明・引数)】
(ここに貼る。機密情報や実在の顧客IDは伏せ字にする)

【条件】
- 各ツールに「何をするか」「使う場面」「使わない場面(代替ツール名つき)」
  「返さないもの」「副作用」を入れる
- 似たツール同士は、境界がはっきり分かるように対にして書く
- 一覧にない機能は書かない。分からない点は「要確認」と書いて質問する

「分からない点は質問する」と入れておくと、AIが挙動を想像で補うのを防げます。出てきた下書きは、実際のツールの挙動と人が突き合わせてください。

直したあとの確認手順

書き換えたら、次の手順で確かめます。

1. 依頼文を8〜10個用意します。明らかに片方を使う依頼だけでなく、「どちらとも取れる」依頼を数個混ぜます。
2. 各依頼でAIがどのツールを呼ぼうとしたか(または呼ばなかったか)を記録します。
3. 誤った選択があれば、その依頼文を「使う場面」か「使わない場面」に追記し、再度試します。
4. 取り違えが続く2ツールは、統合できないか検討します。

OpenAIの関数呼び出しガイドは、関数の目的や各引数の形式、出力の意味を明確にし、いつ使うか・使わないかをシステムプロンプトで指定するよう勧めています。また、初見の人が定義だけで正しく使えるか確認する方法や、最初に使える関数を20個未満にするのは「柔らかな提案」であることも記載しています。Anthropicのガイドには、複数サービスにまたがる場合にサービス名を前につけた名前にする方法や、関連操作をまとめる案もあります。どちらが合うかは手順2の記録で判断してください。

外部のツールを使うときの注意

他人が作ったMCPサーバーを接続する場合、その説明文は自分で書いたものではありません。MCP仕様は、ツールの注釈(annotations)は信頼できるサーバー由来でない限り信頼しないものとして扱うよう、クライアントに求めています。仕様が名指ししているのは注釈ですが、説明文もAIが読む入力である以上、接続前に一度は目を通し、意図しない指示や不要な権限が書かれていないか確認するのが安全だと考えます(これは編集部の見立てです)。

公開前チェックリスト

• [ ] 各ツールの説明が3文以上あり、機能と戻り値が書かれている
• [ ] 似たツールには、お互いを名指しした「使わない場面」がある
• [ ] 使う場面が、利用者の実際の言い回しで書かれている
• [ ] 副作用のあるツールに、取り消せるか・確認が要るかが書かれている
• [ ] 引数の説明に、形式と例がある
• [ ] 紛らわしい依頼で、期待どおりのツールが選ばれることを自分の環境で確かめた

最後の項目は、この記事の例では確かめていません。必ず自分のツールとモデルで試してください。