Skip to content

MP001: require-tool-description

Every tool must have a non-empty description.

At a glance
Category schema
Default severity error
Auto-fixable yes (safe)
LLM-gated no
Stable since v0.1.0

What this rule checks

mcpolish reads each tool's description (from a description= argument or a function docstring). If the description is missing, empty, or whitespace-only, MP001 fires.

For decorator-style tools, the docstring is treated as the description when no description= argument is given.

Why it matters

Wang et al. (2026) section 4.2 measured what happens when an MCP tool has no description at all. In head-to-head selection against a clean tool, the empty-description tool was picked 52 percentage points less often. The description is the agent's main input at decision time; without it, the agent has only the tool name to work with, which is often not enough.

Example: code that triggers this rule

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("notes")


@mcp.tool(description="")
def add(x: int = 0) -> int:
    return x + 1

The explicit empty description="" and the missing docstring leave the description empty. MP001 fires.

Example: how to fix it

@mcp.tool()
def add(x: int = 0) -> int:
    """Use this when the user wants to add one to a number.

    Returns the number plus one.
    """
    return x + 1

The docstring becomes the description. MP001 stops firing.

Configuration

MP001 has no configurable knobs. To skip it entirely:

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

When to disable this rule

Almost never. Even an internal tool benefits from a one-line description. The only case where disabling makes sense is when you are using mcpolish purely for one other rule and want to mute everything else.

How the check works under the hood

For each ToolDecl in the IR, mcpolish strips whitespace from description and checks the length. Zero length fires the rule.

For FastMCP tools, the discoverer pulls description= first, then falls back to the function's docstring. If both are missing or empty, the IR sees an empty string and MP001 fires.

Auto-fix

The safe autofix inserts a placeholder docstring under the function. It does not invent a real description; the placeholder reads TODO: describe what this tool does and when an agent should call it. Apply with:

mcpolish lint . --fix

After running the fix, edit the placeholder into a real description.

  • MP020 description-too-short: fires once you have a description but it is too brief.
  • MP023 no-trigger-condition: fires when a description never says when to pick the tool.

References