Skip to content

MP023: no-trigger-condition

The description should tell the agent when to pick this tool.

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

What this rule checks

A useful description includes a trigger condition: a phrase like "use this when...", "best for...", "call this if...". mcpolish looks for any one of those phrases in the description. If none are present, MP023 fires.

The phrase list (case insensitive):

use this when, use it when, call this when, call this if,
call it when, call it if, invoke this when, invoke this if,
useful when, useful for, appropriate when, appropriate for,
best for, only when, only if, prefer this when, when the user

Why it matters

Wang et al. (2026) section 4.5 calls descriptions without trigger language "passive descriptions". Their experiment shows a 6.8 percentage point increase in wrong-tool selection on passive descriptions. The agent reads the description and asks "is this for me?". A trigger phrase answers that question directly.

Example: code that triggers this rule

@mcp.tool()
def list_open_tickets() -> list:
    """Returns a JSON array of open ticket records pulled from the database."""
    return []

The description states what the tool does, but never says when to pick it. MP023 fires.

Example: how to fix it

@mcp.tool()
def list_open_tickets() -> list:
    """Use this when the user wants every open ticket. Returns a JSON array
    of ticket records pulled from the database.
    """
    return []

Adding "Use this when..." is enough to silence the rule.

Configuration

MP023 has no knobs in v1. To skip it:

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

When to disable this rule

If your team writes descriptions in another language, the English-only regex misses your trigger phrases and MP023 fires on every tool. Either disable, or open an issue with the language's equivalents to add to the regex.

How the check works under the hood

mcpolish runs a single regex against the description text. Match silences the rule. No match fires it.

The regex is intentionally generous; it includes the most common trigger constructions in English-language MCP servers. It does not catch all possible phrasings, which is why this rule defaults to note severity.

  • MP020 description-too-short: a short description usually has no trigger condition.
  • MP026 ambiguous-description: the LLM-gated version of "the description does not tell the agent enough".

References