Skip to content

MP031: param-meaning-mismatch

An LLM judge says the parameter name, type, and description disagree on meaning.

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

What this rule checks

For each parameter, mcpolish sends the tool name, parameter name, JSON Schema type, and description to a configured LLM judge. The judge is asked: do the name, type, and description agree on what the agent should pass?

A MISMATCH: <reason> reply fires MP031.

Why it matters

MP030 catches keyword-level mismatches (string typed param with the word "number" in the description). It misses subtler cases where every piece individually is sensible but the combination is ambiguous. For example, a parameter named since, typed integer, described as "the cutoff value" leaves the agent unsure whether to pass epoch seconds, days ago, or something else. MP031 catches that.

Li et al. (2026) found that around 33 percent of servers analysed had at least one such mismatch.

Example: code that triggers this rule

@mcp.tool()
def list_events(since: int = 0) -> list:
    """Use this when the user wants recent events.

    Args:
        since: cutoff value. Example: 1700000000.

    Returns: a list of events.
    """
    return [since]

The name since plus type integer plus description cutoff value is ambiguous between epoch seconds, days ago, an event id, and several others. With --llm, MP031 fires.

Example: how to fix it

Disambiguate:

"""Use this when the user wants recent events.

Args:
    since: Unix epoch seconds. Events at or after this time are returned.
        Example: 1700000000.

Returns: a list of events sorted by time, newest first.
"""

Now name, type, and description tell the same story.

Configuration

MP031 is off by default. Enable with:

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

To disable:

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

When to disable this rule

The LLM judge has some false-positive rate. If MP031 fires on a parameter you believe is unambiguous, file a counter-example and disable in the meantime.

How the check works under the hood

mcpolish sends a short prompt per parameter. The judge is asked for OK or MISMATCH: <reason>. Verdicts cache in ~/.cache/mcpolish/llm.db. Failed LLM calls return OK (graceful degradation).

The prompt asks the judge to consider all three pieces (name, type, description) as a whole and only fire when at least one piece would confuse the agent.

  • MP030 param-type-mismatch: static keyword version.
  • MP002 require-param-description: a missing description hides MP031.

References