あなたのMCPサーバーには秘密のスコアリング問題がある

あなたのMCPサーバーはデモでは完璧に動く。そりゃそうだ、デモを作ったのはあなた自身なのだから。プロンプトを吟味し、ツールが発火し、結果がきれいに返ってきた。みんな頷いた。リリースだ。

そして本番がやってくる。

本番では、LLMが30%の確率で間違ったツールを選ぶ。ユーザーが奇妙な結果を報告する。エージェントはfetchを呼ぶべきところでsearchを呼ぶ。エポックタイムスタンプが必要なところに日付文字列を渡す。最も強力なツールをいつ使えばいいか分からないので、完全に無視する。

何が変わった？コードは何も変わっていない。ハンドラーは正常。ロジックも正常。問題はずっとそこにあった——デモはスクリプト化されていて本番はそうではないから、気づかなかっただけだ。デモでは入力を制御できる。本番では、LLMがあなたの15個のツールの中からユーザーの曖昧なリクエストに合うものを判断しなければならない。そしてそのステップで、あなたが思っている以上に頻繁に失敗している。

これが秘密のスコアリング問題だ。サーバーにバグがあるのではない。言語モデルがツールについて実際の判断を下さなければならないときにだけ現れる品質ギャップがあるのだ。

ほとんどのMCP開発者が内面化していないことがある。LLMはあなたのコードを決して読まない。ハンドラーのロジックも、バリデーションルールも、丁寧なエラーハンドリングも見ない。見るのは名前、説明文、スキーマだけだ。

それだけ。あなたのツールと、それを使うかどうかを判断する知性との間のインターフェースはそれが全てだ。

2つのツールの説明文が似ていれば、LLMは当てずっぽうで選ぶ。確認を求めない。曖昧さを指摘しない。1つ選んで先に進む。あなたの説明が「ドキュメントを検索する」で、別のツールが「ドキュメントを見つける」と言っていたら、LLMは本質的にコイントスしているのと同じだ。

説明文が曖昧なら、LLMは意図を幻覚する。仮定で空白を埋める。「ユーザー設定を管理する」は、設定の読み取り、書き込み、削除、エクスポートのどれでもあり得る。LLMは1つの意味を仮定し、誰にも言わずにそれにコミットする。

ツール選択はコードの問題ではなく、言語の問題だ。エンジニアの本能はハンドラーをデバッグすることだ。実際の修正はほぼ常にテキストにある——ツールが何をし、いつ使うべきかを説明する20語。ほとんどのチームはスタックトレースを読むのに忙しくて、そこを見ることはない。

品質スコアは1つの数字ではない。もしそうなら、料理とサービスと雰囲気を区別せずにレストランに1つの評価をつけるようなもので、無意味だ。

本当の品質スコアは6つの次元から成る。それぞれ独立して測定可能で、それぞれが単独でツールの信頼性を崩壊させる力を持つ。

説明の明確さ：説明はツールが何をするか、いつ使うか、いつ使わないかを説明しているか？レスポンス形式を指定しているか？ここで40点は「LLMはこのツールを定期的に誤用する」を意味する。90点は「LLMはほぼ常にこのツールを正しく選ぶ」を意味する。

スキーマの完全性：パラメータは精密に型付けされているか？必須フィールドは本当に必須か？値が制約されているところでenumが使われているか？

命名の一貫性：ツールは予測可能なパターンに従っているか？create_userとdelete_userがあるのにfetch_all_documentsがあると、その不一致がモデルに認知的負荷を生む。

重複の検出：同じユーザーリクエストにもっともらしく一致するツールはいくつあるか？高い重複は、間違ったツール選択の最大の予測因子だ。

エラーの文書化：ツールは失敗時に何が起こるかを説明しているか？

例のカバレッジ：説明に使用例があるか？例は説明の段落よりも価値がある。LLMの理解を具体的なパターンに固定するからだ。

具体的に示そう。各次元で40点と90点がどう見えるか。

説明の明確さ40点：「データベースを検索する。」90点：「全インデックス済みドキュメントに対する全文検索。関連性順に上位10件を返す。ユーザーが内容でドキュメントを見つけたい時に使用。正確なIDでの検索には使用しない——代わりにget_documentを使用。タイトル、スニペット、関連性スコアを返す。」

スキーマの完全性40点：「query」という1つのパラメータがstring型、制約なし。90点：「query」は空でないstring、最大長500。オプションの「limit」はinteger、最小1最大100デフォルト10。オプションの「date_range」は開始と終了がISO 8601日付。

命名40点：search、getDoc、user_remove、ListAllItems。90点：search_documents、get_document、remove_user、list_items。パターンはverb_noun、一貫して。

重複40点：search_documents、find_documents、query_documentsが全て存在し、微妙に異なることをする。90点：各ツールが明確で重複しない目的を持つ。

違いは常に具体性だ。曖昧なツールは失敗する。正確なツールは動く。そして40点と90点の差は通常、書き直しではない——午後いっぱいの丁寧な編集だ。

ほとんどのチームは間違ったレイヤーをデバッグする。ツール選択の失敗を見て、すぐにコードに向かう。ハンドラーをより寛容に書き直す。リトライロジックを追加する。より高価なモデルに切り替える。MCP の上に精巧なルーティングレイヤーを構築して、その下の曖昧さを補おうとする。

すべて高くつき、遅く、原因ではなく症状に対処している。

実際の修正は大抵、ツール説明への20語の編集だ。「ドキュメントを管理する」を「提供されたタイトルとボディから新しいドキュメントを作成する。ドキュメントIDを返す。新規作成にのみ使用——既存ドキュメントの更新にはupdate_documentを使用」に変える。

その編集は30秒かかった。ツール選択エラーの丸ごと一カテゴリを排除する。コード変更なし。モデルアップグレード不要。リトライロジック不要。

品質スコアリングは、どの20語を変えるべきか正確に教えてくれる。問題を起こしている特定のツールの、失敗している特定の次元を指し示し、代わりに何を書くべきかの具体的な提案をしてくれる。漠然とした「AIが混乱し続ける」を、正確な「search_documentsの説明がレスポンス形式に言及しておらず、34%の失敗はLLMが結果を誤解釈したことに遡る」に変換する。

だから測定が重要なのだ。スコア自体が価値あるからではなく、見えない問題を見える、修正可能なものに変換するからだ。これを理解したチームはハンドラーの書き直しをやめ、説明の書き直しを始める。日数ではなく分単位で修正をリリースする。そしてツールがただ動く——コードが良いからではなく、言語が良いからだ。