MCP サーバーのディレクトリ Smithery で利用回数の多いサーバーを 46 個選び、計 1,118 ツールの説明文を調べました。769 ツール（69%）が「いつ使うか」を書いていません。 「何を返すか」が説明文にないツールも 507 個（45%）ありました。似た説明文が並んで取り違えやすいツールの組は、15 サーバーで計 90 組見つかっています。
69% という数字は、前回の調査とまったく同じです。そのときは公開サーバー 8 つの 126 ツールを調べ、87 ツールが「いつ使うか」を書いていませんでした。対象を 9 倍に広げても、割合は変わりませんでした。
調べるのに使ったのは、筆者が作っている MCP のツール説明文の静的リンター Forecall です。
調べ方：Smithery の上位 50 サーバーの説明文を、文字だけで判定した
2026 年 10 月 8 日に、Smithery の公開レジストリの一覧の先頭 500 件（API が返す既定の順）から、重複を除いて利用回数の多い順に 50 個を選び、各サーバーのツール定義を集めました。これを Forecall の CLI（forecall 0.3.2）で採点しています。50 個のうち 4 個は、ツールが 200 個を超えていて CLI の上限に当たったので除きました。残りの 46 サーバー、1,118 ツールが対象です。
一つ注意があります。Smithery の API が返すツール定義には、入力スキーマの required（必須の引数）や出力スキーマが含まれていません。そのため Forecall の総合点は本来より低く出ます。この記事では総合点を使わず、説明文の文字だけで決まる指摘に絞って数えました。 具体的には、「いつ使うか」の有無、説明文に戻り値が書かれているか、説明文が短すぎないか、似た説明文の組の 4 つです。
7 割のツールが「いつ使うか」を書いていない
| 指摘 | ツール数 | 割合 |
|---|---|---|
| 「いつ使うか」がない | 769 | 69% |
| 説明文に戻り値がない | 507 | 45% |
| 短すぎる、または名前の言い直し | 101 | 9% |
サーバー単位で見ると、もっと偏っています。46 サーバー中 16 サーバーは、すべてのツールに「いつ使うか」がありませんでした。8 割以上のツールに欠けているサーバーまで含めると、半分の 23 サーバーになります。
「いつ使うか」は、エージェントが似たツールの中から 1 つを選ぶときの決め手です。ないと、モデルは名前と説明文の雰囲気で選ぶしかありません。
全ツールに同じ注意書きを付けると、ツールの見分けがつかなくなる
取り違えやすい組がいちばん多かったのは PubMed です。7 ツールしかないのに、21 組、つまりすべての組み合わせが「取り違えやすい」と判定されました。似ている順に並べた上位 12 組では、説明文の語の重なりが 0.73〜0.94 あります。
原因は、7 ツールすべての説明文に付いている長い注意書きです。
IMPORTANT - PubMed Database Scope: This server provides access to PubMed, which ONLY indexes biomedical and life sciences literature including: …
各ツールの違いは冒頭の 1 文（「論文を検索する」「メタデータを取る」「関連論文を探す」など）にしかありません。それが同じ注意書きの中に埋もれています。
サーバー全体に共通する注意は、各ツールの説明文ではなく、サーバーの instructions（初期化のときにクライアントへ渡す説明）に 1 回だけ書くのが向いています。ツールの説明文には、そのツールにしかないことを書きます。
「返信を送る」と「返信の下書きを作る」が、ほぼ同じ文で書かれている
Gmail では 7 組が取り違えやすいと判定されました。いちばん似ていたのは次の 2 つで、語の重なりは 0.92 です。
| ツール | 説明文の冒頭 |
|---|---|
| Gmail_ReplyToEmail | Send a reply to an email message, optionally with one or more file attachments. |
| Gmail_WriteDraftReplyEmail | Compose a draft reply to an email message, optionally with one or more file attachments. |
2 文目以降は、添付ファイルの渡し方の同じ説明が続きます。違いは「Send」と「Compose a draft」の数語だけです。
この 2 つを取り違えると、下書きを作るつもりがメールを送ってしまいます。取り消せない操作を含むツールこそ、「下書きでよいときは Gmail_WriteDraftReplyEmail を使う」のように、使い分けを 1 文で書いておくべきです。
良い例：Brave Search は、ツール同士のつなぎ方を書いている
一方で、Brave Search の説明文は、ほかのツールとの関係をはっきり書いています。web 検索の brave_web_search はこうです。
Performs web searches using the Brave Search API and returns comprehensive search results with rich metadata. To chain into local-POI enrichment, pass
result_filter=locationsand feed the resultinglocations.results[].idvalues intobrave_local_search.
何を返すか、次にどのツールへどの値を渡すかが書いてあるので、エージェントは複数のツールを順に使えます。Brave Search は 8 ツールすべてが説明文に戻り値を書いていて、取り違えやすい組も 0 でした。
直し方：3 つのことを 1 文ずつ書く
今回の結果から、説明文を直すときの優先順位は次のとおりです。
- 使いどころを 1 文書く：「Use this when …」に加え、似たツールがあれば「for …, use X instead」と書きます。
- 共通の注意はサーバーの instructions に移す：全ツールに同じ段落を貼ると、ツールの違いが埋もれます。
- 似たツールの違いを言葉にする：送るのか、下書きか。消すのか、外すのか。取り消せない操作ほど明記します。
自分のサーバーは、次のコマンドで確かめられます。1 行目でサーバーから tools/list を取り出し、2 行目で採点します。どちらも手元だけで動き、結果をどこにも送りません。
npx forecall dump -o tools.json -- <サーバーを起動するコマンド>
npx forecall lint tools.json
Streamable HTTP のサーバーなら、npx forecall dump https://example.com/mcp > tools.json のように URL を渡します。
まとめ：説明文の弱点は、規模を広げても同じだった
8 サーバーでも 46 サーバーでも、ツールの 7 割が「いつ使うか」を書いていませんでした。人気のあるサーバーでも事情は同じです。直すのに大きな手間はかかりません。使いどころの 1 文と、似たツールとの違いの 1 文を足すだけで、エージェントが選び間違える余地は大きく減ります。
この調査は、データを入れ替えて続ける予定です。次は、公式の MCP Registry に載っているリモートのサーバーを、スキーマまで含めて採点します。