Skip to content

MP002: require-param-description

Every parameter must have a description.

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

What this rule checks

For each parameter in each tool, mcpolish checks whether a description is attached. For decorator-style tools, the description is parsed from the docstring's Args: block (Google-style). For low-level Tool() constructors, the description is read from the JSON Schema property's description field.

If a parameter has no description, MP002 fires once per missing parameter.

Why it matters

Wang et al. (2026) section 4.4 found 1,285 of 10,831 servers had at least one undocumented parameter. The agent reads parameter descriptions to decide what to pass. A parameter named limit could be a count, a percentage, or a row identifier; the description disambiguates.

Example: code that triggers this rule

@mcp.tool()
def search_records(query: str, limit: int = 10) -> list:
    """Use this when the user wants to find records by keyword."""
    return []

The function has two parameters, neither described. MP002 fires twice.

Example: how to fix it

@mcp.tool()
def search_records(query: str, limit: int = 10) -> list:
    """Use this when the user wants to find records by keyword.

    Args:
        query: Search keywords. Example: "kubernetes".
        limit: Maximum number of results to return.
    """
    return []

The Google-style Args: block ties each parameter to a description. MP002 stops firing.

Configuration

MP002 has no knobs. To skip it entirely:

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

When to disable this rule

If your team uses NumPy-style or plain-prose docstrings, the discoverer cannot find descriptions and MP002 will fire on every parameter. In that case either rewrite the docstrings in Google style, write a custom converter, or ignore MP002.

How the check works under the hood

The discoverer parses the docstring's Args: block by looking for lines like name: description.... Each matched name gets the matching description attached to its ParamDecl. Tools registered through Tool() constructors get descriptions straight from the JSON Schema property.

If a parameter has no entry in the Args block and no schema description, its ParamDecl.description is None and MP002 fires.

  • MP022 missing-example: fires when a parameter has a description but no example value.
  • MP030 param-type-mismatch: fires when description and type disagree.

References