I open-sourced a linter for MCP tool descriptions

Description and use

Forecall linter evaluates MCP tool descriptions, identifies missing usage context and confusing pairs, guiding developers to rewrite for clearer agent interactions.

Problem

AI agents need clear, actionable tool descriptions to choose and use MCP tools correctly, but many servers provide minimal or ambiguous descriptions.

Outcome

The linter identifies 69% of tools lacking usage context and flags confusable pairs, guiding developers to rewrite descriptions for clearer agent interactions.

Workflow

• 1. Run npx forecall dump -o memory.json -- npx -y @modelcontextprotocol/server-memory to dump a server’s tool list.
• 2. Run npx forecall lint memory.json to score the tools and generate a report.
• 3. Review the report for low scores, confusable pairs, and missing fields.
• 4. Refactor tool descriptions based on feedback (e.g., add usage context, examples).
• 5. Re-run the linter to verify improvements.
• 6. Integrate forecall lint into CI with --fail-under 60 to enforce quality thresholds.

Evidence

AI agents choose an MCP tool by reading three things: its name, its description and its input schema.

Source

Forecall’s linter checks exactly that, and its code is now public under Apache-2.0: github.com/forecall/forecall-cli.

Source

Average score 43.8 / 100 Tools 9 Confusable pairs 1 Across the server Major confusable_pair delete_entities and delete_relations are easy to mix up.

Source

Use it in CI --fail-under 60 exits with 1 when the average is below 60, and --json prints the report as JSON.

Source

We ran it over the 46 most-used servers on Smithery: 769 of 1,118 tools (69%) never say when to use them.

Source