MP021: description-too-long¶
The tool description is above the maximum character count.
At a glance¶
| Category | description |
| Default severity | note |
| Auto-fixable | no |
| LLM-gated | no |
| Stable since | v0.1.0 |
What this rule checks¶
mcpolish strips whitespace and compares the description length to a maximum (default 1500 characters). Anything longer fires MP021.
Why it matters¶
Anthropic's internal tool-use evaluation, cited in Wang et al. (2026) section 6, found that descriptions beyond roughly 1500 characters burn context tokens without measurable improvement in selection accuracy. After a point, more words about a tool do not help the agent pick it; they just push other tools' descriptions out of the visible context.
This rule defaults to note severity because long descriptions are a softer issue than missing ones.
Example: code that triggers this rule¶
A tool with a docstring that runs to about 1800 characters. The first 1500 characters do useful work; the rest is implementation detail that belongs in a separate document.
Example: how to fix it¶
Split the description into:
- A short header that explains when to call the tool.
- Args descriptions.
- A short Returns line.
Move the long implementation notes into a separate docs/tools/<name>.md page that humans read. The agent only sees the description; humans can follow a link.
Configuration¶
When to disable this rule¶
If your tools genuinely need long descriptions (highly conditional triggers, many cases), raise the threshold or disable the rule. The cost is context tokens, which you can measure separately.
How the check works under the hood¶
mcpolish does len(description.strip()) and compares to the threshold. Pure static check; no LLM involved.
Related rules¶
- MP020 description-too-short: the opposite end of the spectrum.
- MP024 jargon-density: long descriptions sometimes pile on acronyms; MP024 catches that.
References¶
- Wang et al., 2026. arXiv:2602.18914, section 6 discussion.
- Anthropic tool-use guidance (internal eval).