All docs

Read your scores

How a tool's score out of 100 is made, what the checks across the server look for, and every issue code with its severity.

On this page

Each tool gets a score out of 100, the sum of six items. The server's average is the mean of its tools' scores, with one decimal place. Each result also lists issues: what to fix, each with an issue code and a severity.

The six items

ItemPoints
Purpose20
When to use20
Arguments25
Return value15
Constraints and side effects10
Examples10
  • Purpose: the description exists, says what the tool does (starting with a verb helps), is long enough to explain it, and does more than repeat the tool's name.
  • When to use: the description says when to use the tool, when not to, and what to use instead.
  • Arguments: every argument has a description; string arguments have a constraint or an example (enum, format, pattern, examples, default, minLength or maxLength); the schema lists the required arguments and sets additionalProperties to false.
  • Return value: the tool has an outputSchema, or its description says what it returns.
  • Constraints and side effects: the tool has annotations (readOnlyHint, destructiveHint, idempotentHint), and its description mentions limits, side effects, permissions, costs or rate limits.
  • Examples: the description, or an argument, gives an example.

The rules look for English words in the descriptions, so descriptions in other languages score lower than they deserve.

Score bands

A weather sign goes with each score, so that you can scan a long list:

70 and above: clear40–69: cloudybelow 40: rain

The number is what counts; the sign only groups it.

Across the server

Some problems only show when tools are seen together:

  • Too many tools: above 25 tools, models start to tell them apart less well, and above 40 they choose less accurately.
  • Near-identical descriptions: pairs whose descriptions share most of their words, or whose names are alike and descriptions partly alike, so that only the names and schemas tell them apart. A result shows the 12 most similar pairs and counts all of them; each tool's card names the tools whose descriptions are nearly the same as its own. Say in each description when to use the other one instead, for example "Not for file names; use find_files for those." The sentence makes the descriptions less alike, so the pair is usually no longer flagged. The finding says the texts are alike, not that a model mixes the tools up: in our measurements current models chose right between such pairs when the names and schemas differed.
  • Identical descriptions: tools that share one description differ only by name and schema.
  • A note repeated in most tools: the same sentences, 20 words or more, in at least three tools and at least half of them, such as a scope notice pasted into every description. Since rules v2 the note is taken out of each description before scoring, so it neither earns points in every tool nor makes the tools look alike, and the server gets one finding instead. Say it once in the server's instructions: MCP's specification says the instructions should not duplicate the tool descriptions.
  • The server's instructions: a file written by forecall dump carries them, and the linter checks that the server has some and that they fit what clients read. Claude Code passes only the first 2,048 characters to its model by default, so say what the server is for first. A bare tools/list cannot tell whether the server has instructions, so nothing is said about them.

Severity

  • Critical: the description gives a model nothing to choose the tool by. Fix these first.
  • Major: the description leaves out what a model needs to choose the tool at the right time or to call it correctly.
  • Minor: details that would help a model, such as the return value or constraints.

The severities rank what is missing from the text; they do not predict what a model will do.

The issues alone do not fail the CLI; set --fail-under to stop a CI job on a low average (see Score with the CLI).

Issue codes

The codes are the same on the web, in the CLI and in its --json report. The sentences below are examples: a result fills in the real numbers and names.

Issues of each tool

CodeSeverityWhat a result says (example)
no_descriptionCriticalNo description.
restates_nameMajorThe description only restates the name (4 words).
too_shortMajorThe description is too short (5 words).
no_usage_contextMajorSays nothing about when to use it, or when not to.
destructive_unmarkedMajorIt may be destructive, but destructiveHint is not set.
generic_nameMajorThe name is made of generic words only.
bad_name_charsMajorThe name contains characters other than letters, digits, _, - and .
param_no_descriptionMajorMinorArguments without a description: path, recursive.
too_longMinorThe description is long (430 words). It helps selection but costs steps and tokens.
loose_string_paramMinorString arguments with no constraint or example: query.
no_requiredMinorNo `required` list, so every argument is optional.
params_not_in_descriptionMinorThe description mentions none of its 3 or more arguments.
vague_booleanMinorThe meaning of the boolean argument recursive is unclear.
no_return_infoMinorSays nothing about what it returns.
no_constraintsMinorNo constraints, side effects, auth or rate limits described, and no annotations.
long_nameMinorThe name is long (48 characters).
deprecatedMinorThe description says the tool is deprecated. Name the replacement, and consider taking the tool out of tools/list: models avoid it when asked for what it does.
id_source_missingMinorRequired identifiers whose description does not say where the value comes from: page_id, parent. Name the tool or the place that returns it, or models look it up first.

Issues across the server

CodeSeverityWhat a result says (example)
identical_descriptionCriticalThese tools share the same description: search_pages, search_docs.
repeated_noteMajor7 tools repeat the same note (123 words): "IMPORTANT - PubMed Database Scope: This server provides access to PubMed, which…". Say it once in the server's instructions, and let each description say what only that tool does. The note does not count toward the tools' scores.
too_many_toolsMajor52 tools. Above 40, models choose less accurately.
confusable_pairMinorget_block and retrieve_block have nearly the same description; only the names and schemas tell them apart. In each description, say when to use the other one instead.
confusable_pair_totalMinor57 pairs with nearly the same description in all; the top 12 are shown.
many_toolsMinor31 tools. Above 25, models start to tell tools apart less well.
instructions_longMinorThe server's instructions are 2904 characters. Claude Code reads only the first 2,048 by default (Codex 0.154.0 reads them whole). Put what the server is for first.
instructions_missingMinorThe server has no instructions. Say there, once, what the server is for and when to use it: Claude Code and Gemini CLI read the instructions before the tool descriptions.

Versions of the scoring rules

Every result shows the version of the scoring rules it was scored with. Any change that can move a score or an item comes with a new version, so compare scores only within one version. A new or reworded issue code alone does not change the version. What each version changed is in the CHANGELOG of the linter's repository.

  • v2 (2026-10-09, forecall 0.6.0): a note repeated in most tools counts once instead of in every tool, and the server's instructions are read from a forecall dump file. A server without such a note scores the same as under v1.
  • v1 (2026-10-02, forecall 0.1.0 to 0.5.0): the rules from Forecall's research on eight public servers.

How much of the instructions a client passes to its model, by the evidence we have:

Client Instructions Evidence
Claude Code Read; cut at 2,048 characters by default Its documentation (2026-10-09)
Codex CLI 0.154.0 Read whole, at least up to 20,000 characters Measured by Forecall with a codeword server (2026-10-09)
Gemini CLI Appended to the system instructions; no limit documented Its documentation (2026-10-09)
Cursor Unknown Not documented; not measured

What static scoring cannot tell at all is in Getting started.