Skip to content

MP020: description-too-short

The tool description is below the minimum character count.

At a glance
Category description
Default severity warning
Auto-fixable no
LLM-gated no
Stable since v0.1.0

What this rule checks

mcpolish strips whitespace from the tool description and compares its length to a minimum threshold (default 50 characters). If the description is shorter than the threshold, MP020 fires.

An empty description fails MP001 first; MP020 only fires on present-but-short descriptions.

Why it matters

Wang et al. (2026) section 4.2 measured the effect of description length. Descriptions under 50 characters were 3.4 times more likely to cause wrong-tool selection in the head-to-head test. Below 50 characters there usually is not enough room to say both what the tool does and when to use it.

50 is a soft threshold. A good description usually lands around 100-300 characters.

Example: code that triggers this rule

@mcp.tool()
def get_value(key: str) -> str:
    """Reads the value."""
    return key

The docstring is 19 characters. MP020 fires.

Example: how to fix it

@mcp.tool()
def get_value(key: str) -> str:
    """Use this when the user wants the latest value for a known key.

    Args:
        key: The key. Example: "user:42:name".

    Returns: the value as a string.
    """
    return key

Configuration

[tool.mcpolish.MP020]
min_chars = 80     # stricter

When to disable this rule

Almost never. Even a one-line description should clear 50 characters. If your team uses descriptions in another language with shorter average word length, you may need to drop the threshold.

How the check works under the hood

mcpolish does len(description.strip()) and compares to the configured threshold. The check is straightforward and offline.

  • MP001 require-tool-description: fires when the description is empty.
  • MP021 description-too-long: fires on overly long descriptions.
  • MP023 no-trigger-condition: short descriptions usually fail this too.

References