Skip to content

MP022: missing-example

Free-form parameters (string, object, array) should have an example value.

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

What this rule checks

For each tool parameter whose JSON Schema type is string, object, or array, mcpolish looks for an example. An example can be:

  • An example (or examples) field on the JSON Schema property.
  • The word Example: inside the parameter's description text.

If neither is present, MP022 fires once per parameter.

Numeric and boolean parameters do not trigger MP022. Their type is enough hint for the agent.

Why it matters

Wang et al. (2026) section 4.4 lists "missing example" as a top-3 description smell by effect size. A free-form parameter is open-ended; an example anchors the agent to a concrete shape. Example values reduce arg-shape errors by a noticeable margin.

Example: code that triggers this rule

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

    Args:
        query: Keywords describing what to look for.

    Returns: a list of matching record ids.
    """
    return [query]

query is a string parameter with a description but no Example: line and no schema-level example. MP022 fires.

Example: how to fix it

Add an example in the docstring:

"""Use this when the user wants to find records by keyword.

Args:
    query: Keywords describing what to look for. Example: "kubernetes".

Returns: a list of matching record ids.
"""

Or, with the Tool() constructor style, in the schema:

inputSchema={
    "type": "object",
    "properties": {
        "query": {
            "type": "string",
            "description": "Keywords describing what to look for.",
            "example": "kubernetes",
        },
    },
    "required": ["query"],
}

Configuration

[tool.mcpolish.MP022]
required_examples = 1     # default. Set to 2 to require two examples.

When to disable this rule

If your free-form parameters are constrained to a known small set of values (which would be better expressed as an enum in the schema), MP022 is noise. Either add the enum or ignore the rule.

How the check works under the hood

mcpolish checks each ParamDecl's has_example flag. For decorator-style tools, that flag is set when the docstring's Args entry for the parameter contains the word example (case-insensitive). For constructor-style tools, it is set when the schema property has an example or examples field.

  • MP002 require-param-description: a param without a description fails MP002 first.
  • MP030 param-type-mismatch: a type-vs-description mismatch should be fixed before adding examples.

References