Skip to content

MP003: require-return-schema

The tool should declare an outputSchema or mention what it returns.

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

What this rule checks

MP003 fires when both of these are true:

  1. The tool does not declare an outputSchema.
  2. The tool's description has no return-related word (returns, yields, response, output).

If either is present, the rule is silent.

Why it matters

Wang et al. (2026) Table 4 reports that 3,093 of 10,831 servers had no documentation about what a tool returns. Without that, the agent does not know how to use the result. It often resorts to defensive guesses or calls more tools to confirm.

A short Returns: ... line is enough. A full outputSchema is better.

Example: code that triggers this rule

@mcp.tool()
def ping_host(host: str) -> None:
    """Use this when the user wants to verify a host is reachable.

    Args:
        host: Hostname or IP to check. Example: "example.com".
    """
    print(host)

The description has no Returns: line and the tool has no outputSchema. MP003 fires.

Example: how to fix it

Option A: add a Returns: line.

"""Use this when the user wants to verify a host is reachable.

Args:
    host: Hostname or IP to check. Example: "example.com".

Returns: True when the host responded, False otherwise.
"""

Option B: declare an outputSchema (only available with the Tool() constructor style in v1).

Configuration

MP003 has no knobs. To skip it:

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

When to disable this rule

If your team's convention is to put return information in the function's type hints only (e.g. -> str), MP003 will fire on every tool. Either add Returns: lines or ignore the rule project-wide. The type hint is useful but not visible to the agent at decision time.

How the check works under the hood

The rule looks at each tool. If output_schema is set, the rule is silent. Otherwise mcpolish runs a regex against the description for the words returns, yields, response, or output. Match silences the rule. No match fires it.

  • MP001 require-tool-description: an empty description fails MP001 first.
  • MP020 description-too-short: a short description often lacks return info.

References