Skip to content

MP033: duplicate-tool-description

Two tools in the same server share the same description.

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

What this rule checks

mcpolish normalises every tool's description (lowercase, collapse whitespace) and groups tools by the normalised string. Any group with two or more tools fires MP033 once per tool in the group.

Short descriptions (under 20 characters after normalisation) are skipped to avoid noise on tools that happen to share a one-word placeholder.

Why it matters

If two tools share an identical description, the agent has no signal to choose between them. It has to guess from the name alone, which is exactly the failure mode mcpolish is trying to prevent. Wang et al. (2026) section 4.3 lists duplicate descriptions among the highest-impact smells because they reduce the agent's signal-to-noise ratio to almost zero.

This rule runs across files, so two tools defined in different modules of the same server still match.

Example: code that triggers this rule

@mcp.tool()
def list_items_a() -> list:
    """Use this when the user wants the complete list of items owned by them."""
    return []


@mcp.tool()
def list_items_b() -> list:
    """Use this when the user wants the complete list of items owned by them."""
    return []

Both tools share an identical description. MP033 fires twice (once per tool), each diagnostic naming the other.

Example: how to fix it

Differentiate the descriptions:

@mcp.tool()
def list_items_a() -> list:
    """Use this when the user wants only ACTIVE items they own. Returns a
    list of item ids. For archived items, use `list_items_b`."""
    return []


@mcp.tool()
def list_items_b() -> list:
    """Use this when the user wants only ARCHIVED items they own. Returns a
    list of item ids. For active items, use `list_items_a`."""
    return []

Or merge the two tools into one with a parameter that toggles the filter.

Configuration

MP033 has no knobs. To skip:

[tool.mcpolish]
ignore = ["MP033"]

When to disable this rule

Almost never. Duplicate descriptions are a real bug. If you genuinely have two tools that do the same thing, you have one tool too many.

How the check works under the hood

mcpolish collects every tool's description, normalises with lower() + collapse-whitespace, and groups by the normalised string. For each group with multiple members, the rule emits one diagnostic per member naming the others.

  • MP012 inconsistent-verb-pattern: another in-server consistency check.
  • MP010 generic-tool-name: duplicates often have generic names.

References