TDQS

TDQS, the Tool Definition Quality Score, is an open standard for grading how well an MCP tool definition communicates to an AI agent, together with a CLI, a web playground and an HTTP API that apply it. It was built by Glama, which runs a large MCP server registry, and it comes from a practical observation. Agents pick tools by reading their descriptions, and the registry's data shows that well-described tools get selected about 2.6 times more often than poorly described ones. The idea is to give tool descriptions the kind of lint step that code has had for decades.

The problem is that nobody had a shared definition of a good tool description. Server authors write whatever comes to mind, agents misfire on ambiguous tools, and there's no lint step in the loop. TDQS gives that step a rubric. The framework scores each description on six weighted dimensions, purpose clarity at 25 percent, usage guidelines at 20, behavioral transparency at 20, parameter semantics at 15, conciseness and structure at 10, and contextual completeness at 10, with additional server-level checks such as naming consistency, disambiguation between tools and whether the tool count is appropriate. The dimensions are documented individually on the site, each with an explanation of what a strong description looks like, so the score comes with the guidance needed to improve it.

Scores map to tiers. An A needs 3.5 or higher, a B needs 3.0 and is the passing bar, C starts at 2.0, D at 1.0, and anything below that is an F. Alongside the model-based score there's a deterministic lint pass that checks definitions against the specification without any inference, which is the part you can run offline and in CI without credentials. The split is practical. Lint catches structural problems, such as missing descriptions or definitions that break the specification, at zero cost, and the model-based score judges the harder questions of clarity and completeness that a rule can't decide. A B is the pass line used in the CI examples, though the gate is configurable.

The CLI runs as npx mcp-tdqs on Node 22 or newer, or uvx tdqs on Python 3.10 or newer. You point it at a JSON file or stdin, a running MCP server process, or a remote HTTP server, and get results as JSON, Markdown or text, optionally written to a file. Lint needs nothing else. Scoring needs a model, either an OpenAI-compatible endpoint you configure through environment variables or the hosted mode where tdqs.dev runs the model using account credits. The docs include CI workflows that lint every pull request and score release branches with a failure gate set to the tier you choose.

The API lives at tdqs.dev under v1 with three endpoints. One runs lint and returns immediately, one queues a full report with model scoring, and one fetches a report by id. Keys come free from an account created with GitHub sign-in, each account gets 30 calls a day across its keys, posting a job costs a call while polling is free, and a request can carry up to 200 tools within a 1 MB limit. The scoring model itself isn't disclosed in API responses. Reports are retrievable later by id, so a CI job can post a report and fetch the result when the model stage finishes, and requests are rate limited rather than priced, which suits occasional checks and CI more than bulk scanning.

It's for people who build MCP servers and want agents to choose and use their tools correctly, for platform teams curating a catalogue of internal tools, and for anyone benchmarking tool quality across the ecosystem. The playground is the quickest way to see what the rubric rewards, and the corpus page shows scores across more than 228,000 tools from over 15,000 servers, which gives a sense of where a typical description lands. Because the same rubric is applied across the registry, a score is comparable between servers, so a team can set an internal bar and know what it means relative to the rest of the ecosystem.

TDQS is open source, with the specification and implementation on GitHub, the CLI free to run, and the hosted API free within its daily limit. Hosted scoring draws on account credits, and no paid plans are published. As with any rubric, it measures what it measures, so a high score means a description is clear and complete, not that the tool works. Used as a lint gate, though, it's a cheap way to stop the most common description mistakes before an agent ever sees them. The changelog and the flags reference on the site track how the rubric evolves, and the dimensions pages explain what each score is looking for with enough detail to fix a low one.