# 採点の読み方

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 組を表示し、総数も数えます。ツールごとのカードには、そのツールと取り違えやすいツールを示します。
- **説明文がまったく同じ**: 同じ説明文のツールは、まったく見分けられません。

## 重大度

- **重大**: モデルがそのツールを選ぶ手がかりがありません。最初に直してください。
- **要対応**: モデルが間違った場面で選んだり、間違って呼んだりしやすい状態です。
- **軽微**: 戻り値や制約など、モデルの助けになる情報が足りません。

指摘があるだけでは CLI は失敗しません。平均点が低いときに CI を止めるには、`--fail-under` を指定します（[CLI で採点する](https://forecall.dev/ja/docs/cli#ci)）。

## 指摘コードの一覧

指摘コードは、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 文字）。 |

### サーバー全体の指摘

| コード | 重大度 | 結果に出る文（例） |
|---|---|---|
| `identical_description` | 重大 | 次のツールの説明文がまったく同じです: search_pages、search_docs |
| `too_many_tools` | 要対応 | ツールが 52 個あります。40 を超えると、モデルの選択の精度が落ちます。 |
| `confusable_pair` | 要対応 | get_block と retrieve_block は取り違えやすい組です。 |
| `confusable_pair_total` | 要対応 | 取り違えやすい組は全部で 57 組あります（上位 12 組を表示）。 |
| `many_tools` | 軽微 | ツールが 31 個あります。25 を超えると、モデルがツールを見分けにくくなり始めます。 |

## 採点の規則の版

結果には、採点に使った規則の版が必ず出ます。点数、項目、指摘コード、重大度のどれかが変わりうる変更をしたら版を上げるので、点数は同じ版どうしで比べてください。静的な採点ではそもそも分からないことは、[はじめに](https://forecall.dev/ja/docs/getting-started#limits)に書いています。