Skip to content

MP026: ambiguous-description

An LLM judge says the description is ambiguous about what the tool does or when to call it.

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

What this rule checks

For each tool, mcpolish sends the tool name and description to a configured LLM judge. The judge is asked: given only this description, can a competent agent reliably tell what the tool does and when to call it?

A NO reply fires MP026 with the judge's one-sentence reason.

Why it matters

The static description rules (MP020 through MP025) catch obvious problems: missing, too short, no trigger phrase, jargon, marketing language. They miss subtle cases where the description is well-formed but vague in a way only a careful reader can see. The LLM judge fills that gap.

Example: code that triggers this rule

@mcp.tool()
def handle_thing(x: str = "") -> str:
    """Use this when the input thing needs to be transformed somehow.

    Args:
        x: The thing to handle. Example: "abc".

    Returns: the resulting thing as a string.
    """
    return x

The description passes every static rule. But "handle the thing somehow" tells the agent nothing concrete. With --llm, MP026 fires with a message like description is ambiguous: never says what the transformation is.

Example: how to fix it

Be concrete:

@mcp.tool()
def slugify_title(x: str) -> str:
    """Use this when the user has a long title and wants a URL-safe slug.

    Args:
        x: The original title. Example: "How to use MCP".

    Returns: the lowercase slug. Example: "how-to-use-mcp".
    """
    return x.lower().replace(" ", "-")

Configuration

MP026 is off by default. Enable with:

mcpolish lint . --llm openai:gpt-4o

Or set the default provider in pyproject.toml:

[tool.mcpolish]
llm = "openai:gpt-4o"

To disable:

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

When to disable this rule

If you cannot or do not want to send descriptions to an LLM provider, leave it off. mcpolish does not run MP026 unless you opt in.

How the check works under the hood

mcpolish builds a small prompt with the tool name and description. The prompt asks for a single-line YES or NO: <reason> reply. The LLM client caches the verdict in ~/.cache/mcpolish/llm.db, keyed on the prompt and model. Subsequent runs hit the cache and skip the API call.

A failed LLM call (network, rate limit) is treated as OK, so the rule never blocks a build because the network is flaky.

  • MP020 description-too-short: a too-short description fails statically before MP026 can judge.
  • MP023 no-trigger-condition: trigger language is one of the things MP026 looks for.
  • MP031, MP032: the other two LLM-gated rules.

References