{"slug": "stop-writing-mcp-tool-descriptions-like-a-human-is-reading-them", "title": "Stop writing MCP tool descriptions like a human is reading them", "summary": "A developer has created a tool to score the semantic density of MCP tool descriptions, arguing that verbose, human-friendly descriptions cause LLM agents to hallucinate and fail. The tool, available at vinkius.com, analyzes verb density, naming uniformity, and overall clarity to help developers write more effective instructions for AI agents.", "body_md": "I've spent the last few years watching developers build incredible MCP servers, only to watch them fall apart in production because of something fundamentally stupid: bad instructions.\n\nYou build a sophisticated integration—maybe it connects to a legacy CRM or a complex billing API. You handle the auth, you manage the sandboxing via V8, you've got your TypeScript types perfectly mapped. Then, at the finish line, you write a tool description that sounds 'nice.' Something like: \"This tool allows you to fetch user information from our database and will return the details as a string.\"\n\nAnd then, when you drop it into Claude Desktop or Cursor, the agent starts hallucinating. It tries to pass `user_id`\n\nwhen you named the parameter `userId`\n\n. It forgets that the output is a string because you didn't explicitly state the return type in an actionable way. It gets lost in the 'fluff.'\n\nThe problem isn't your LLM. The problem is that you are writing for humans, but these tools are being consumed by agents. Agents don't need politeness; they need semantic density.\n\nWhen we talk about function calling in the MCP ecosystem, we aren't just talking about APIs. We are talking about a new kind of Instruction Set Architecture (ISA) where the 'instructions' are written in natural language but executed via high-precision logic.\n\nIn this context, every extra word in your tool description is essentially noise that increases the probability of a parsing error or a reasoning failure. If an agent has to navigate through three sentences of 'context' before it hits an imperative verb, you are wasting its context window and increasing its cognitive load. This is where semantic density comes in.\n\nSemantic density is the ratio of actionable information to total text length. A high-density description uses imperative verbs and provides clear return types, minimizing linguistic noise that can distract an LLM during function calling.\n\nI recently started using a specific tool to audit my own server definitions: the [Tool Description Semantic Density Scorer](https://vinkius.com/mcp/tool-description-semantic-density-scorer). It doesn't just 'feel' like your descriptions are good; it actually measures their structural integrity.\n\nThe first thing the scorer looks at is `calculate_verb_encensity`\n\n. This sounds academic, but in practice, it's about identifying whether your tool description is actually an instruction or just a paragraph of prose.\n\nAn effective MCP tool should be anchored by imperative, action-oriented verbs: `retrieve`\n\n, `update`\n\n, `delete`\n\n, `fetch`\n\n, `calculate`\n\n. If I see descriptions that use passive voice or descriptive fluff like \"is designed to help you...\", the density ratio drops. A high-density string, like \"Retrieve the record and then update it,\" has a much higher concentration of actionable commands relative to its length (roughly 0.28 in our tests). This tells the agent exactly what the operation entails without the need for secondary reasoning.\n\nThere is another way MCP tool calls fail that is almost impossible to catch during a standard unit test: naming inconsistency across parameter lists.\n\nYou might have one parameter as `user_id`\n\n(snake_case) and another as `userAge`\n\n(camelCase). To a human, it's trivial. To an LLM attempting to construct a valid JSON object for a function call, it’s a massive red flag that leads to downstream parsing failures in the integration layer.\n\nThe Scorer uses `analyze_naming_uniformity`\n\nto audit these parameter lists. It checks for casing consistency (e.g., `camelCase`\n\nvs. `snake_case`\n\n) and returns a uniformity score. If your tool definition has even one deviant parameter, it flags it. This is critical when you're building complex tools that rely on consistent patterns across multiple function calls.\n\nThe real meat of this process is the `evaluate_description_clarity`\n\ntool. It acts as a primary aggregator. It doesn't just look at verbs or names in isolation; it computes a weighted clarity score by integrating:\n\nYou can literally run your text through this and get a definitive grade on how reliable that tool will be in an automated environment like Windsurf or Claude Desktop.\n\nIf you are just playing around with MCP in a local sandbox, maybe it doesn't matter. But if you are building production-grade tools—the kind we build at Vinkius that handle real business logic and sensitive data—you cannot afford ambiguity.\n\nWhen an agent has access to your tools, its ability to perform is directly bounded by the precision of your definitions. If your descriptions are 'fluffy,' you're essentially handing a broken manual to a highly skilled worker and wondering why they can't follow instructions.\n\nYou should be linting your tool definitions with the same rigor that you lint your TypeScript code. Check for casing, check for verb density, and ensure return types are explicit. If you don't, you aren't building an agentic tool; you're just hoping for the best.\n\n*MCPs are the music of AI Agents. We built the catalog. Discover Vinkius MCP Catalog.*", "url": "https://wpnews.pro/news/stop-writing-mcp-tool-descriptions-like-a-human-is-reading-them", "canonical_source": "https://dev.to/renato_marinho/stop-writing-mcp-tool-descriptions-like-a-human-is-reading-them-1p2k", "published_at": "2026-08-03 00:38:07+00:00", "updated_at": "2026-08-03 01:22:33.819797+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "natural-language-processing"], "entities": ["MCP", "Claude Desktop", "Cursor", "V8", "TypeScript", "Tool Description Semantic Density Scorer"], "alternates": {"html": "https://wpnews.pro/news/stop-writing-mcp-tool-descriptions-like-a-human-is-reading-them", "markdown": "https://wpnews.pro/news/stop-writing-mcp-tool-descriptions-like-a-human-is-reading-them.md", "text": "https://wpnews.pro/news/stop-writing-mcp-tool-descriptions-like-a-human-is-reading-them.txt", "jsonld": "https://wpnews.pro/news/stop-writing-mcp-tool-descriptions-like-a-human-is-reading-them.jsonld"}}