When an agent calls the wrong MCP tool, the server’s tool definitions may be part of the problem: names, descriptions, and input schemas are the interface the agent uses to choose a tool and supply arguments. A linter can flag omissions and ambiguities in that interface, but its score is a diagnostic—not evidence that the agent will perform better or that the tool is safe.
The title describes a particular linter, but no repository, rubric, example report, or evaluation results are available to establish what that implementation checks or how it performs. The practical approach is to separate static definition checks from task-based testing, and judge changes by what happens on realistic agent tasks.
Why might an agent call the wrong MCP tool?
An MCP client discovers tools through the server’s tools/list interface. The tool name, description, and input schema help the agent infer what each tool does and what arguments it needs. If two tools sound alike, a description omits a key limitation, or a parameter is unexplained, the agent may select the wrong tool or send invalid arguments.
Definition clarity is only one possible cause. A large exposed toolset can also make selection slower, more confusing, and more expensive. Google Cloud’s MCP overview describes toolsets as a way to expose logical subsets instead of loading every tool at once.
#1 Best Overall
What can an MCP tool linter score?
A useful linter can assess whether definitions communicate enough for an agent to make an informed choice and construct a valid call. Keep its static findings separate from behavioral evidence: a definition can look complete and still fail in use, while a low score does not by itself prove an agent will fail.
Static checks: inspect the definition
- Purpose: Does the description say what the tool does, rather than merely restating its name?
- Selection cues: Does it distinguish the tool from nearby alternatives and explain when it should be used?
- Parameters: Are parameter names and descriptions understandable, with required inputs and constraints represented clearly in the schema?
- Limitations: Does the definition make important boundaries or unsupported cases clear?
- Consistency: Do the prose and input schema agree, or does the description invite arguments the schema cannot accept?
These are sensible diagnostic dimensions, not a complete list of requirements imposed by MCP. The 2026 study by Mohammed Mehedi Hasan, Hao Li, Gopi Krishnan Rajbahadur, Bram Adams, and Ahmed E. Hassan proposes a description rubric. Its abstract refers to six components; its reported intervention discussion includes purpose, guidelines, limitations, parameter explanation, and examples. Treat that work as a proposed evaluation method, not an official protocol standard.
Behavioral checks: test actual calls
A static report cannot establish that an agent chooses correctly. Run realistic tasks with the server and inspect the agent’s decisions, arguments, results, and recovery behavior. Anthropic’s engineering guidance, “Writing effective tools for AI agents—using AI agents”, recommends evaluating tools with real-world tasks and reviewing 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.”
What does existing evidence say about MCP tool descriptions?
The 2026 study by Hasan, Li, Rajbahadur, Adams, and Hassan analyzed 856 tools across 103 MCP servers. The collection was based on servers reported in prior literature as of 2025-08-20. In that dataset, the authors’ FM-based scanning identified at least one description smell in 97.1% of analyzed descriptions, and 56% did not state the tool’s purpose clearly. These are findings from that particular sample and method, not a census of MCP tools.
Recommended Free Tools
The study also tested description augmentation. The authors report median task success increasing by 5.85 percentage points and partial goal completion by 15.12%, alongside a 67.46% increase in execution steps; performance regressed in 16.67% of cases. The result is a useful caution: adding detail may help in some contexts, but it can also increase work or harm performance. Those figures describe the paper’s experiments, not the results of the unnamed linter in this article. See the study for its scope and method.
How should you validate a lint finding?
- Choose representative tasks. Include ordinary requests, boundary cases, and tasks that require choosing among similar tools.
- Record the baseline. Save the tool definitions and run the tasks before changing them. Preserve transcripts showing the prompt, selected tool, arguments, and result.
- Inspect each finding. Ask what an agent could not infer from the existing name, description, and schema. A warning is useful only if it points to a concrete ambiguity or omission.
- Revise narrowly. Add relevant purpose, selection guidance, constraints, or parameter explanations. Avoid irrelevant prose that makes the definition longer without making tool choice or argument construction clearer.
- Rerun the same tasks. Compare correct tool selection, invalid-parameter errors, task completion, unnecessary or repeated calls, execution steps, and runtime.
- Review failures as well as averages. A change that improves a summary metric may still break a particular task. Keep the before-and-after traces so the trade-off is visible.
This follows Anthropic’s guidance to use realistic tasks and inspect transcripts rather than relying on a score alone. If no task comparison was run, report the linter’s output as a static assessment—not as evidence of improved agent performance.
What a tool score cannot tell you
It cannot prove runtime behavior
A linter sees a definition, not necessarily what the server actually does. It cannot establish that implementation behavior matches the description, that results are correct, or that errors are handled safely. Those require runtime tests.
It cannot turn annotations into guarantees
MCP tool annotations such as readOnlyHint, destructiveHint, idempotentHint, and openWorldHint communicate behavioral hints; they are not proof of behavior. The MCP project’s tool-annotations guidance, dated 2026-03-16, says clients should treat annotations as untrusted unless they come from a trusted server. It summarizes the interface this way: “Every property is a hint.” The statement concerns annotation properties, not every part of an MCP schema. The post also describes cautious defaults when annotations are absent: potentially non-read-only, destructive, non-idempotent, and open-world behavior.
Free tools Windows power users keep installed
One-click scans. No signup required.
Best Value
It cannot fix an oversized toolset
If an agent has too many tools to choose from, clearer descriptions may not be enough. Consider exposing a focused logical subset for the task. Google Cloud’s MCP overview discusses toolsets for this purpose; the appropriate grouping depends on the server and workflow.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.How do other tool-evaluation approaches compare?
Microsoft documents an MCP evaluation workflow that scores tool names, descriptions, parameter names and descriptions, and schema structure, then provides an overall score and action items. The documentation says it runs a coding-agent CLI locally under the user’s account and that schema data is not sent to Microsoft through that process. This is an adjacent documented approach, not evidence about the unnamed linter in the title. Details are in Microsoft’s tool evaluation documentation.
When comparing any linter or evaluation workflow, check what it actually does rather than judging by a headline score:
Quick Recap
- Which metadata and schema rules does it inspect?
- Are findings deterministic, model-judged, or a combination?
- Does it stop at static checks, or test task outcomes?
- Can it explain each finding and suggest a specific, actionable correction?
- Does it disclose false-positive and false-negative behavior, supported schema or specification versions, runtime, and cost?
Checklist for clearer, more testable MCP tools
- Give each tool a name and description that make its purpose distinguishable from similar tools.
- Explain when the tool is appropriate and note consequential limitations.
- Make parameter names, types, required values, and constraints understandable in the schema.
- Check that the prose does not promise inputs or behavior the implementation does not support.
- Expose only the tools relevant to the agent’s task where the server or client supports that choice.
- Use lint output to find candidates for review, then validate changes with realistic tasks and call traces.
- Treat annotations and quality scores as signals, not guarantees of implementation correctness or safety.
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.
