Reference
Grading Methodology
Every grade on MCP Playground is computed from a fixed set of rules applied to the server's live response. This page documents every rule, the scoring formula, and grade thresholds — so you know exactly what to fix.
How It Works
- 1Connect — We open a live connection to the server using the MCP SDK and call initialize, tools/list, resources/list, and prompts/list.
- 2Lint — Each tool, resource, prompt, and the server itself is checked against the rules below. Each violation is recorded with a severity.
- 3Score — We start at 100 and deduct points per violation. A bonus of +5 is added if every tool has a description of at least 20 characters.
- 4Grade — The numeric score is mapped to a letter grade using fixed thresholds.
Scoring Formula
score = 100
score −= 15 × (number of errors)
score −= 5 × (number of warnings)
score −= 1 × (number of infos)
score += 5 if all tools have descriptions ≥ 20 chars
score = clamp(score, 0, 100)
score = 0 if server has no tools, resources, or prompts
Grade Thresholds
A
Excellent
90 – 100
B
Good
75 – 89
C
Needs Work
60 – 74
D
Poor
40 – 59
F
Critical
0 – 39
All Lint Rules
Rules are applied per-item (each tool, resource, or prompt is checked independently) plus once at the server level.
🔧 Tool Rules
Applied once per tool. Tools are the most important capability — LLMs rely on descriptions to decide which tool to call.
| Rule ID | Severity | Points | What & Why |
|---|---|---|---|
tool-no-description | error | −15 pts | Missing tool description LLMs pick the right tool based on its description. Without one, the tool is effectively unusable by an AI agent. |
tool-short-description | warning | −5 pts | Description is under 10 characters A very short description gives models almost no signal. Add context about when and why to use this tool. |
tool-long-description | warning | −5 pts | Description exceeds 500 characters Overly long descriptions increase token cost for every call. Aim for under 300 characters. |
tool-description-is-name | warning | −5 pts | Description just repeats the tool name This adds no information. Replace it with a meaningful explanation of what the tool does. |
tool-no-schema | warning | −5 pts | Missing inputSchema Without a schema, clients don't know what arguments to send and can't generate a form. |
tool-schema-not-object | info | −1 pt | inputSchema type is not 'object' The MCP spec expects an object schema at the top level. Most clients will work, but this is non-standard. |
prop-no-description | warning | −5 pts | A parameter has no description Models and users need descriptions to understand what each parameter does. Applied per parameter. |
prop-no-type | warning | −5 pts | A parameter has no type Without a type, clients can't validate input or generate the right form field. Applied per parameter. |
tool-no-required | info | −1 pt | No required parameters defined If the tool has parameters, consider marking the essential ones as required so clients know what's mandatory. |
required-not-in-properties | error | −15 pts | A required field is missing from properties The schema lists a field as required that doesn't exist in properties — this is a schema bug. |
tool-empty-schema | info | −1 pt | Tool accepts no arguments Noted for visibility. If this tool should take inputs, add a properties object to the schema. |
tool-name-convention | info | −1 pt | Tool name uses unusual characters Some clients have trouble with names that aren't snake_case or kebab-case. |
📄 Resource Rules
Applied once per resource.
| Rule ID | Severity | Points | What & Why |
|---|---|---|---|
resource-no-name | warning | −5 pts | Missing resource name A descriptive name helps users and clients understand what this resource provides. |
resource-no-description | warning | −5 pts | Missing resource description Without a description, clients can't explain to users what this resource contains. |
resource-no-mimetype | info | −1 pt | No MIME type specified A MIME type (e.g. text/plain, application/json) lets clients render content correctly. |
💬 Prompt Rules
Applied once per prompt.
| Rule ID | Severity | Points | What & Why |
|---|---|---|---|
prompt-no-description | error | −15 pts | Missing prompt description Users need to know what a prompt does before they run it. This is a critical metadata gap. |
prompt-arg-no-description | warning | −5 pts | A prompt argument has no description Argument descriptions help users fill in the right values. Applied per argument. |
🖥️ Server Rules
Applied once at the server level, regardless of tool/resource/prompt count.
| Rule ID | Severity | Points | What & Why |
|---|---|---|---|
server-empty | error | −15 pts | Server exposes no tools, resources, or prompts An empty server has nothing for clients to use. Score is automatically 0. |
server-no-name | warning | −5 pts | No server name in initialize response The server name identifies it to clients and shows up in logs and UIs. |
server-no-version | warning | −5 pts | No version in initialize response Versioning helps clients track compatibility and detect breaking changes. |
server-duplicate-tools | error | −15 pts | Duplicate tool names Having two tools with the same name is a schema bug — only one can be called. |
Tips for a Better Grade
Fix any server-level errors first: make sure the server responds, returns a name and version, and exposes at least one tool.
Add descriptions to all tools. Even a single sentence is enough to clear the most impactful error rule.
Add descriptions to each tool parameter. This clears the prop-no-description warnings which cost 5 points each.
Add types to all parameters, keep descriptions under 300 characters, and make sure all tools have descriptions ≥ 20 characters to earn the +5 bonus.
Check your server
Run the linter on any live MCP server at /lint, or see how your server ranks in the Quality Dashboard.
The grading logic is open source. View schema-linter.ts on GitHub →