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 playgroundv1.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.
tdqs score
$ npx tdqs score --command "node ./dist/server.js" --fail-under B
github-mcp · 4 tools · specification 1.2
list_issuesA4.6
create_issueA4.1
search_codeB3.2
get_file_contentsC2.4
smell get_file_contents · usage_guidelines 2 — never says when to reach for it instead of search_code
overall A 3.7 · quality 3.6 · coherence 4.0
✓ passes B
- 228,369
- tools scored in the registry
- 15,036
- MCP servers, every tool graded
- 73.5%
- of tools clear the passing bar
- 97%
- 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.
- Stage 1
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.
- Stage 2
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.
- Stage 3
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.
- Stage 4
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 is measured
Ten dimensions, one letter.
Six weighted dimensions grade each tool; four more, equally weighted, judge the server as a whole. Every score comes with a written reason, and every dimension has a page with its anchors.
Per tool · weighted
- Purpose Clarity25%Does the description state what the tool does?
- Usage Guidelines20%Does it say when to use this tool vs alternatives?
- Behavioral Transparency20%Does it disclose behavior beyond what annotations already declare?
- Parameter Semantics15%Does it add meaning beyond what the input schema provides?
- Conciseness & Structure10%Is it appropriately sized and front-loaded?
- Contextual Completeness10%Given the tool's complexity, is the description complete enough?
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.
- A≥ 3.5genuinely helpful definition
- B≥ 3.0adequate, the passing bar
- C≥ 2.0clear gaps
- D≥ 1.0severely deficient
- 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.
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 tdqs score --url https://mcp.example.com/mcp --fail-under BHosted 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.jsonWhy 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 corpusShow 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.