tdqs — Tool Definition Quality Score: a quality score for MCP tool definitions

The description is the only thing an agent reads when it decides which tool to call. TDQS scores how well that description does its job: six weighted dimensions per tool, four per server, one letter tier, and a written reason for every point. Deterministic code extracts what the schema and annotations already say; a model grades only what the description adds beyond them.

The rubric is open, the prompts are published verbatim, the arithmetic is integer, and the same definition hashes to the same value in every implementation. Glama runs it over every tool in its registry; the reference implementation runs it in your terminal, in CI, or through this site's hosted API.

tool definition
      │
      ▼
[1] context signals ──── deterministic schema/annotation analysis + input hash
      │
      ▼
[2] hard gates ───────── degenerate definitions short-circuit (no LLM call)
      │
      ▼
[3] LLM rubric ───────── six dimensions, 1–5 each, justification per dimension
      │
      ▼
[4] post-processing ──── deterministic overrides, flags, smells
      │
      ▼
TDQS (1.0–5.0) + tier (A–F) + per-dimension breakdown

Per tool, weighted; 1–5 each.

25%

purpose_clarity — Does the description state what the tool does?

20%

usage_guidelines — Does it say when to use this tool vs alternatives?

20%

behavioral_transparency — Does it disclose behavior beyond what annotations already declare?

15%

parameter_semantics — Does it add meaning beyond what the input schema provides?

10%

conciseness_structure — Is it appropriately sized and front-loaded?

10%

contextual_completeness — Given the tool's complexity, is the description complete enough?

Per server, equally weighted; 1–5 each.

25%

disambiguation — Can an agent tell the tools apart?

25%

naming_consistency — Do tool names follow a predictable pattern?

25%

tool_count_appropriateness — Is the surface well-scoped?

25%

completeness — Are there gaps in the surface?

A ≥ 3.5

genuinely helpful definition

B ≥ 3.0

adequate, the passing bar

C ≥ 2.0

clear gaps

D ≥ 1.0

severely deficient

F < 1.0

reserved guard tier

The same thresholds apply to a tool, a server's description quality, its coherence, and the overall. B is the passing bar.

97%

of tool descriptions in a study of 856 tools across 103 servers carry at least one quality defect; 89% never say when the tool should or should not be used.

~260%

more often selected: well-described tools win competitive selection, and rewriting descriptions alone lifts task success by about six points.

228,369

tools across 15,036 servers scored in Glama's registry as of June 2026; 73.5% clear the bar and 56.4% carry at least one smell. See the corpus.

$ npx tdqs lint --command "node ./dist/server.js"
$ npx tdqs score --url https://mcp.example.com/mcp --fail-under B
$ curl https://tdqs.dev/api/v1/lint -H 'Content-Type: application/json' -d @tools.json

Or paste a tools/list result into the playground.

spec(7)dimensionsflagschangelogcli(1)apicorpus