When an agent calls the wrong MCP tool, the problem may be in the tool definitions it sees: names, descriptions, and input schemas are the cues it uses to decide what to call and how to supply arguments. A linter can flag missing or unclear cues, but its score is a diagnostic—not proof that the agent will choose correctly or that the server is safe.
The title suggests a specific linter, but no repository, rubric, report, or evaluation results are available to substantiate a first-person build story. Rather than invent one, this guide explains what a useful MCP tool linter should inspect, how to validate its findings, and what the available evidence does—and does not—show.
As an Amazon Associate I earn from qualifying purchases.
Why an agent may call the wrong MCP tool
An MCP client discovers tools through tools/list. The tool names, descriptions, and input schemas then help the agent distinguish among available actions and construct arguments. If two tools sound alike, a description omits the intended use, or a parameter is poorly explained, the agent may select an unsuitable tool or provide invalid input. The definitions are therefore part of the interface, not just documentation.
Unclear descriptions are only one possible cause. Exposing a large number of tools can also make an agent slower, less reliable, or more expensive. Google Cloud describes toolsets as a way to expose logical subsets of tools rather than loading everything at once: Google Cloud’s MCP overview.
#1 Best Overall
What a tool-definition linter should check
A useful linter separates things it can inspect in the definition from outcomes that require running an agent. Static checks can identify omissions and inconsistencies; only task-based evaluation can show whether a particular agent, with a particular set of tools, can use them effectively.
| Check | What to look for | What it cannot establish alone |
|---|---|---|
| Name and purpose | Whether the name and description make the tool’s purpose distinguishable from related tools. | Whether an agent will choose it correctly in a real task. |
| Usage guidance and limits | Whether the description explains when to use the tool, important constraints, and relevant failure conditions. | Whether those limits are enforced by the implementation. |
| Input parameters | Whether parameter names and descriptions explain expected values, formats, and meaning, and whether the schema is coherent. | Whether the server accepts the values or behaves as the description promises. |
| Examples | Whether examples clarify a non-obvious call or argument, when examples are included. | Whether the examples represent all valid cases. |
| Consistency | Whether the description, parameter explanations, and schema agree with one another. | Whether the tool’s runtime behavior matches its metadata. |
These are candidate review areas, not an official MCP scoring standard. A score should be accompanied by the specific finding, its rationale, and an actionable revision. If checks are model-judged rather than deterministic, the report should make that distinction clear; readers also need to know which schema or specification versions are supported.
How to test whether tool descriptions make sense to an agent
Static checks tell you what looks incomplete or ambiguous. To find out whether a change helps, evaluate the tools on realistic tasks and inspect what the agent actually did. Anthropic recommends examining transcripts and tool-call metrics; it notes that “lots of tool errors for invalid parameters might suggest tools could use clearer descriptions or better examples.” See Anthropic’s guidance on writing effective tools for AI agents.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Build a varied task set. Include real tasks that should use each tool, tasks that distinguish it from similar tools, and cases where no tool should be called.
- Run the same tasks before and after a definition change. Keep the prompt, available tools, and evaluation conditions consistent so the comparison is meaningful.
- Inspect traces, not just the final answer. Record which tool was selected, what arguments were passed, whether calls failed, and whether the agent made redundant calls.
- Track task outcomes and costs. Compare success and partial completion alongside errors, number of execution steps, and runtime. A description that increases success may still add unnecessary calls.
- Review linter findings against the evidence. Check whether flagged issues correspond to observed failures and whether unflagged definitions still cause problems. This is how you find both false positives and false negatives.
A convincing report pairs a specific finding with the original definition, the proposed revision, and task-level results. Without that comparison, the score indicates a potential documentation issue; it does not demonstrate improved agent performance.
What an empirical study found—and what it does not prove
A 2026 study by Mohammed Mehedi Hasan, Hao Li, Gopi Krishnan Rajbahadur, Bram Adams, and Ahmed E. Hassan analyzed 856 tools across 103 MCP servers. The collection was based on servers reported in prior literature as of 2025-08-20. Using its own FM-based scanning method, the study identified at least one description smell in 97.1% of the analyzed descriptions, and found that 56% did not state their purpose clearly. These are findings from that study’s sample and method, not a census of all MCP tools. The paper is available at arXiv:2602.14878.
The authors also tested augmenting descriptions. In their evaluation, augmentation improved task success by a median 5.85 percentage points and partial goal completion by 15.12%, while increasing execution steps by 67.46%; performance regressed in 16.67% of cases. The mixed results matter: adding detail can help an agent understand a tool, but can also increase work or hurt a task. These figures belong to the study’s intervention and evaluation, not to any unnamed linter.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Why a high score is not a safety or correctness guarantee
A linter checks what can be inferred from tool metadata. It cannot prove that the server implementation matches that metadata, that a tool behaves correctly, or that its effects are safe. Runtime tests and appropriate operational controls remain necessary.
Tool annotations make this distinction especially important. The MCP project’s blog says, “Every property is a hint,” referring to properties in the tool-annotation interface. Annotations shipped in spec revision 2025-03-26 and include title, readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The project says clients should treat them as untrusted unless they come from a trusted server; absent annotations imply cautious assumptions about potentially non-read-only, destructive, non-idempotent, and open-world behavior. A quality score cannot turn these hints into guarantees. See the MCP project’s explanation of tool annotations.
Other MCP tool-evaluation approaches
There are adjacent examples, but they should not be mistaken for an unnamed linter. Microsoft documents an evaluation workflow that scores tool names, descriptions, parameter names and descriptions, and schema structure, then provides an overall score and action items. Its documentation says the workflow runs a coding-agent CLI locally under the user’s account and that schema data is not sent to Microsoft by that process: Microsoft’s MCP tool evaluation documentation.
For organizational context, Microsoft also documents management of agent tools: Agent tools overview. Evaluation and administrative controls address different questions; neither substitutes for checking how an agent performs on the tasks you care about.
Quick Recap
A practical checklist before trusting a linter score
- Does the report identify the exact name, description, parameter, or schema issue behind each finding?
- Can you tell which checks are deterministic and which rely on model judgment?
- Does the tool state its supported MCP or schema versions?
- Does it offer a concrete, explainable fix rather than only a number?
- Have you tested revisions on realistic tasks and reviewed the call traces?
- Are you measuring errors, redundant calls, task outcomes, and execution cost—not just description quality?
- Have you considered whether exposing fewer, more relevant tools would address the confusion better than rewriting descriptions?
- Are runtime behavior and safety reviewed separately from metadata quality?
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →
