MCP tool descriptions are becoming a measurable interface. TDQS scores them across six dimensions, flags defects, and lets you fail CI below a chosen tier. Its registry reports 228,369 tools scored and 97% with a defect. https://t.co/cXvCMixuky

TDQS — Tool Definition Quality Score

Source: https://tdqs.dev/ v1.2Open specification## Score how well your MCP tools speak to agents.

The description is the only thing an agent reads before it picks a tool. TDQS grades every definition on six weighted dimensions, explains each point, and turns the result into a tier you can gate a release on — the same numbers in your terminal, in CI, and across Glama’s registry.

Try the playgroundnpx mcp-tdqs

228,369tools scored in the registry15,036MCP servers, every tool graded73.5%of tools clear the passing bar97%of descriptions carry a defect How it works

Deterministic where it can be, judged where it must be.

Code extracts what the schema and annotations already say; a model grades only what the description adds beyond them. Every stage of the pipeline is specified, and the deterministic ones are exact to the digit across implementations.

1. Stage1 ### Context signals Deterministic code reads the schema and annotations: parameter coverage, output schema, behavioural hints, invocation cost, and a hash so the same definition always scores the same.
2. Stage2 ### Hard gates Degenerate definitions — no description, a name restated as a sentence — short-circuit with a flag and a floor score. No model call is spent on them.
3. Stage3 ### Rubric A model grades six dimensions from 1 to 5 against published anchors, and writes a justification for every point. The prompts are the specification, byte for byte.
4. Stage4 ### Post-processing Overrides, flags and smells are applied by code, the weights roll up in integer arithmetic, and the result is a score, a tier, and the reasons.

What the letter means

B is the bar.

The same five thresholds apply to a tool, to a server’s description quality, to its coherence, and to the overall. Gate a release on the tier, and read the justifications to know what to fix.

1. A≥ 3.5genuinely helpful definition
2. B≥ 3.0adequate, the passing bar
3. C≥ 2.0clear gaps
4. D≥ 1.0severely deficient
5. F< 1.0reserved guard tier

Three ways in

One scorer. Browser, terminal, or HTTP.

The reference implementation is a package, on npm and on PyPI; the playground, the CLI and the hosted API all run it. A definition scores the same wherever you send it.

Playground

Sign in with GitHub, paste a tools/list result, and score it through the hosted API from your browser — the same call, headers and allowance a client sees. Every run is a shareable report with a badge.

Open the playground

Command line

Lint and score from your terminal or CI, against a local server, a remote one, or a saved definition set. On npm and on PyPI. Gate a release on the passing tier.

npx mcp-tdqs score --url https://mcp.example.com/mcp --fail-under B

Read the CLI docs

Hosted API

The same scorer over HTTP. Submit definitions, poll the report, embed the result anywhere. Thirty calls a day per account.

curl https://tdqs.dev/api/v1/reports -H 'Authorization: Bearer tdqs_…' -d @tools.json

Read the API docs

Why it matters

Well-described tools get picked about 2.6× more often.

In a study of 856 tools across 103 servers, 97% of descriptions carried at least one defect and 89% never said when the tool should be used. Rewriting descriptions alone lifted task success by about six points. Across Glama’s registry,56.4%of scored tools still carry a smell.

See the calibration corpus Show your score

A badge for your README, a report for your reviewers.

Every scored report has a permanent page and an SVG badge that shows the tier and score. Put it beside the build badge, and the description quality of your server becomes a number people can see.