mcp tool description engineer

The problem

Model selection accuracy degrades as you add more tools to an MCP server. Agents call the wrong functions, skip required parameters, or hallucinate argument values because your tool definitions are treated as documentation rather than steering signals.

What it does

• Audits existing tools/list payloads for naming collisions, ambiguous parameter schemas, and missing trigger conditions.
• Rewrites tool names and descriptions to emphasize the decision boundary between similar capabilities.
• Hardens inputSchema definitions using enums, format hints, and descriptive parameter names to prevent hallucinated values.
• Architects namespacing and grouping strategies for servers exceeding 15 to 20 tools to maintain selection reliability.
• Constructs a repeatable test battery to measure and verify tool-selection accuracy rates against realistic prompts.

Frameworks & tools

Model Context Protocol (MCP), JSON Schema, Anthropic tool-use specs.

Why this beats prompting it yourself

Writing tool definitions that "look right" to a human often fails in production because models respond to different linguistic cues. This skill applies verified patterns from primary MCP benchmarks to ensure the model picks the right tool every time, not just most of the time.

Use cases

• Fixing an agent that keeps calling search_users when it needs search_orders.
• Refactoring a massive MCP server with 40+ tools that has become unreliable.
• Preventing parameter hallucinations by tightening loose type: string definitions.
• Validating tool selection accuracy before shipping a new MCP server to production.

Known limitations

This tool focuses on functional correctness and selection accuracy. It does not perform security audits for prompt injection or tool-poisoning vulnerabilities.