MP024: jargon-density¶

Descriptions packed with all-caps acronyms are hard for agents to read.

At a glance¶


Category	description
Default severity	note
Auto-fixable	no
LLM-gated	no
Stable since	v0.1.0

What this rule checks¶

mcpolish counts the all-caps tokens in the description (at least two characters, all uppercase letters and digits). It divides that count by the total token count. If the ratio is above a threshold (default 25 percent), MP024 fires.

A small whitelist of common technical acronyms is excluded automatically: API, URL, JSON, XML, HTTP, HTTPS, MCP, SQL, ID.

The rule only fires when the description is long enough to be meaningful (default 8 tokens minimum).

Why it matters¶

Descriptions heavy with internal acronyms ("Calls RPC via TKN UFS using XYZ ABC") work fine inside the team that wrote them. Outside that team, the agent sees unfamiliar words with no signal. mcpolish flags descriptions where the all-caps share is high enough to suggest the author was writing for insiders.

Example: code that triggers this rule¶

@mcp.tool()
def relay(x: int = 0) -> int:
    """Use this when the user wants to dispatch via TKN over UFS using XYZ
    ABC FOO BAR PDQ NPC encoding. Returns int."""
    return x

Eight all-caps tokens out of roughly twenty. Ratio is 40 percent. MP024 fires.

Example: how to fix it¶

Expand the acronyms on first use:

"""Use this when the user wants to dispatch a message through the internal
token service (TKN), routing across the unified field store (UFS). Returns
the routed message id as an integer."""

Now the proportion of all-caps tokens is well under the threshold.

Configuration¶

[tool.mcpolish.MP024]
max_ratio = 0.40
min_tokens = 12
allow = ["MCP", "K8S", "AWS", "GCP", "YAGNI"]

When to disable this rule¶

If your domain genuinely lives in all-caps (some hardware or finance domains), set allow to include your acronyms or raise max_ratio. The rule defaults to note severity because false positives are expected.

How the check works under the hood¶

mcpolish tokenises the description using \b[A-Za-z][A-Za-z0-9_]+\b. For each token, it matches the regex ^[A-Z][A-Z0-9_]{1,}$ and excludes whitelisted words. It computes len(allcaps_tokens) / len(all_tokens). If that exceeds max_ratio and there are at least min_tokens tokens, the rule fires.

MP020 description-too-short: short descriptions skip MP024.
MP025 useless-qualifier: another description-quality rule.

References¶

Wang et al., 2026. arXiv:2602.18914, section 4.5 discussion on description clarity.