ドキュメントの一覧

採点の読み方

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、forecall 0.6.0): 多くのツールに繰り返される注意書きを、ツールごとではなく 1 回だけ数えるようにしました。forecall dump のファイルからサーバーの instructions も読みます。そうした注意書きのないサーバーの点は v1 と同じです。
  • v1(2026-10-02、forecall 0.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 不明 記載なし。未計測

静的な採点ではそもそも分からないことは、はじめにに書いています。