採点の読み方
100 点満点の点数がどう決まるか、サーバー全体で何を見るか、すべての指摘コードとその重大度を説明します。
このページの内容
ツールごとに 100 点満点の点数が付きます。6 つの項目の点の合計です。サーバーの平均点は、ツールの点数の平均を小数 1 桁で示したものです。結果には指摘も並びます。直すべき点で、それぞれに指摘コードと重大度が付きます。
6 つの項目
| 項目 | 配点 |
|---|---|
| 目的 | 20 |
| 使いどころ | 20 |
| 引数 | 25 |
| 戻り値 | 15 |
| 制約と副作用 | 10 |
| 例 | 10 |
- 目的: 説明文があり、ツールが何をするかを書いている(動詞で始めると良い)。説明できるだけの長さがあり、ツールの名前を言い換えただけになっていない
- 使いどころ: いつ使うか、いつ使わないか、代わりに何を使うかを説明文に書いている
- 引数: すべての引数に説明がある。文字列の引数に制約か例がある(
enum、format、pattern、examples、default、minLength、maxLengthのいずれか)。スキーマにrequiredがあり、additionalPropertiesがfalseになっている - 戻り値:
outputSchemaがあるか、何を返すかを説明文に書いている - 制約と副作用:
annotations(readOnlyHint、destructiveHint、idempotentHint)があり、上限、副作用、権限、費用、回数制限などに説明文が触れている - 例: 説明文か引数に例がある
規則は説明文の英語の語を探します。そのため、英語以外で書いた説明文は、内容に見合うより低い点になります。
点の帯
長い一覧をざっと見られるように、点数には天気の記号を添えます。
70 点以上: 晴れ40〜69 点: 曇り40 点未満: 雨
大事なのは数字で、記号はそれを分けているだけです。
サーバー全体
ツールを並べて初めて分かる問題もあります。
- ツールが多すぎる: 25 を超えると、モデルはツールを見分けにくくなり始め、40 を超えると選ぶ正確さが落ちます。
- 説明がほぼ同じ組: 説明文の語の大半が同じ組か、名前が似ていて説明文もある程度似ている組で、違いが名前とスキーマにしかないものです。結果には似ている順に 12 組を表示し、総数も数えます。ツールごとのカードには、そのツールと説明文がほぼ同じツールを示します。それぞれの説明文に、もう一方を使うのはどんなときかを書いてください(例: 「ファイル名の検索には使わない。それには
find_filesを使う」)。この一文で説明文の似方が下がるので、たいていは組として指摘されなくなります。この指摘は文が似ていることを言うもので、モデルが取り違えることを言うものではありません。私たちの計測では、名前とスキーマが違えば、いまのモデルはこうした組でも正しく選びました。 - 説明文がまったく同じ: 同じ説明文のツールは、名前とスキーマでしか区別できません。
- 多くのツールに繰り返される注意書き: 20 語以上の同じ文が、3 ツール以上かつ半分以上のツールにあるもの(全ツールの説明文に貼られた範囲の注意書きなど)です。規則 v2 からは、採点の前にその部分を各ツールの説明文から除くので、注意書きがすべてのツールに加点されることも、ツールどうしを似せることもなくなり、代わりにサーバーに 1 つ指摘が付きます。注意書きはサーバーの
instructionsに 1 回だけ書いてください。MCP の仕様は、instructions にツールの説明と同じことを書かないよう求めています。 - サーバーの instructions:
forecall dumpで書いたファイルには instructions が入っていて、リンターは、サーバーに instructions があるか、クライアントが読む長さに収まっているかを検査します。Claude Code は既定で最初の 2,048 文字しかモデルに渡さないので、何のためのサーバーかを最初に書いてください。素の tools/list からはサーバーに instructions があるか分からないので、何も言いません。
重大度
- 重大: 説明文に、モデルがそのツールを選ぶ手がかりがありません。最初に直してください。
- 要対応: 正しい場面で選び、正しく呼ぶためにモデルが必要とする情報が、説明文にありません。
- 軽微: 戻り値や制約など、モデルの助けになる情報が足りません。
重大度は、文に何が欠けているかの順位です。モデルがどう動くかの予測ではありません。
指摘があるだけでは CLI は失敗しません。平均点が低いときに CI を止めるには、--fail-under を指定します(CLI で採点する)。
指摘コードの一覧
指摘コードは、Web でも CLI でも、CLI の --json の出力でも同じです。下の文は例で、実際の結果には本当の数や名前が入ります。
ツールごとの指摘
| コード | 重大度 | 結果に出る文(例) |
|---|---|---|
no_description | 重大 | 説明文がありません。 |
restates_name | 要対応 | 説明文が名前の言い換えになっています(4 語)。 |
too_short | 要対応 | 説明文が短すぎます(5 語)。 |
no_usage_context | 要対応 | いつ使うか、いつ使わないかが書かれていません。 |
destructive_unmarked | 要対応 | 破壊的な操作の可能性がありますが、destructiveHint が付いていません。 |
generic_name | 要対応 | 名前が汎用的な語だけでできています。 |
bad_name_chars | 要対応 | 名前に、英数字と _、-、. 以外の文字が含まれています。 |
param_no_description | 要対応軽微 | 説明のない引数: path、recursive |
too_long | 軽微 | 説明文が長めです(430 語)。選択の精度は上がりますが、手数とトークンが増えます。 |
loose_string_param | 軽微 | 制約も例もない文字列の引数: query |
no_required | 軽微 | `required` が指定されていないため、すべての引数が任意になっています。 |
params_not_in_description | 軽微 | 引数が 3 つ以上あるのに、説明文がどの引数にも触れていません。 |
vague_boolean | 軽微 | 真偽値の引数 recursive の意味が分かりにくくなっています。 |
no_return_info | 軽微 | 何が返るかが書かれていません。 |
no_constraints | 軽微 | 制約・副作用・認証・回数制限の記述がなく、annotations もありません。 |
long_name | 軽微 | 名前が長すぎます(48 文字)。 |
deprecated | 軽微 | 説明文に deprecated とあります。後継のツールを名指しし、tools/list から外すことを検討してください。モデルは、そのツールの役目を頼まれても避けます。 |
id_source_missing | 軽微 | 必須の id 系の引数に、値をどこから得るかが書かれていません: page_id、parent。返してくれるツールや場所を書かないと、モデルは先に探しにいきます。 |
サーバー全体の指摘
| コード | 重大度 | 結果に出る文(例) |
|---|---|---|
identical_description | 重大 | 次のツールの説明文がまったく同じです: search_pages、search_docs |
repeated_note | 要対応 | 7 個のツールに同じ注意書き(123 語)が繰り返されています: 「IMPORTANT - PubMed Database Scope: This server provides access to PubMed, which…」。サーバーの instructions に 1 回だけ書き、各ツールの説明にはそのツールだけがすることを書いてください。注意書きはツールの点数に数えません。 |
too_many_tools | 要対応 | ツールが 52 個あります。40 を超えると、モデルの選択の精度が落ちます。 |
confusable_pair | 軽微 | get_block と retrieve_block は説明文がほぼ同じで、違いは名前とスキーマにしかありません。それぞれの説明文に、もう一方を使うのはどんなときかを書いてください。 |
confusable_pair_total | 軽微 | 説明がほぼ同じ組は全部で 57 組あります(上位 12 組を表示)。 |
many_tools | 軽微 | ツールが 31 個あります。25 を超えると、モデルがツールを見分けにくくなり始めます。 |
instructions_long | 軽微 | サーバーの instructions は 2904 文字です。Claude Code は既定で最初の 2,048 文字しか読みません(Codex 0.154.0 は全部読みます)。何のためのサーバーかを最初に書いてください。 |
instructions_missing | 軽微 | サーバーに instructions がありません。何のためのサーバーで、いつ使うかを、そこに 1 回だけ書いてください。Claude Code と Gemini CLI は、ツールの説明より先に instructions を読みます。 |
採点の規則の版
結果には、採点に使った規則の版が必ず出ます。点数か項目が変わりうる変更をしたら版を上げるので、点数は同じ版どうしで比べてください。指摘コードを足したり文を直したりするだけでは、版は変わりません。版ごとに何を変えたかは、リンターのリポジトリの CHANGELOG にあります。
- v2(2026-10-09、
forecall0.6.0): 多くのツールに繰り返される注意書きを、ツールごとではなく 1 回だけ数えるようにしました。forecall dumpのファイルからサーバーの instructions も読みます。そうした注意書きのないサーバーの点は v1 と同じです。 - v1(2026-10-02、
forecall0.1.0〜0.5.0): 公開 8 サーバーの調査から作った規則です。
クライアントが instructions をどこまでモデルに渡すかは、分かっている範囲で次のとおりです。
| クライアント | instructions の扱い | 根拠 |
|---|---|---|
| Claude Code | 読む。既定で 2,048 文字で切る | 公式ドキュメント(2026-10-09) |
| Codex CLI 0.154.0 | 全部読む(少なくとも 20,000 文字まで) | Forecall が合言葉を埋めたサーバーで計測(2026-10-09) |
| Gemini CLI | システムの指示に追記する。上限の記載なし | 公式ドキュメント(2026-10-09) |
| Cursor | 不明 | 記載なし。未計測 |
静的な採点ではそもそも分からないことは、はじめにに書いています。