Skip to content

MP030: param-type-mismatch

The parameter's declared type disagrees with what the description says it accepts.

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

What this rule checks

mcpolish looks at each parameter's type (from the JSON Schema or the Python signature) and the description text. It runs a small set of regexes against the description for words that suggest a particular type:

Description hint Expected type(s)
number, count, amount, quantity, integer, float, size, limit, page, offset, index, ratio, percent integer or number
true/false, yes/no, toggle, enable, disable, whether boolean
list of, array of, sequence of, set of, each item array

If the description has a hint but the declared type does not match, MP030 fires.

Why it matters

Li et al. (2026) found 3,449 of 10,240 servers had a parameter type that disagreed with the description. A typical case: a parameter typed string with a description "number of results to return". The agent sees the type and sends "10" (a string); the function rejects it because it expects an integer.

These cases produce runtime errors that look like agent bugs but are really description bugs.

Example: code that triggers this rule

from mcp import Tool

TOOL = Tool(
    name="paginate",
    description="Use this when the user wants a page of records.",
    inputSchema={
        "type": "object",
        "properties": {
            "limit": {
                "type": "string",
                "description": "number of results to return",
            },
        },
        "required": ["limit"],
    },
)

The description has the word number. The type is string. MP030 fires.

Example: how to fix it

Either change the type:

"limit": {
    "type": "integer",
    "description": "number of results to return",
    "example": 10,
},

Or change the description to match the type:

"limit": {
    "type": "string",
    "description": "Cursor token returned from the previous call.",
},

Configuration

MP030 has no knobs in v1. To skip:

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

When to disable this rule

If your parameter descriptions intentionally talk in domain-specific terms that overlap with the heuristic keywords (e.g. a limit field that legitimately accepts a percentage as a string), the rule will fire. Disable and trust your code review.

How the check works under the hood

For each parameter, mcpolish runs the three keyword regexes against the description. The union of matches is the expected type set. If the declared type is non-empty and not in the expected set, the rule fires.

  • MP002 require-param-description: a missing description hides MP030 because there is nothing to match.
  • MP031 param-meaning-mismatch: the LLM-gated version that catches subtler disagreements.

References