ax-check rule

AXC-D003: Description only restates the name

Every meaningful word in the description already appears in the name, so the description adds nothing an agent can use.

ax-check is a checker being prepared for release. This page documents the rule ahead of that release; see all 50 rules.

Severitywarn
KindHeuristic. A pattern match: a prompt to look, not a verdict.
Modeax-check lint
Applies toMCP tool lists, OpenAPI, SKILL.md, CLI help
Pattern tagsdescription, selection
Fix in one lineSay what the item does in task language, what it needs and what it returns, not just its name again.

Every meaningful word in the description already appears in the name. “Gets user.” for get_user, or “Manage customers” for a customers command, adds nothing an agent did not already know. The agent still has to guess what the item needs, what it returns and when to use it.

What it checks

ax-check compares the words of the description with the words of the item’s name. When the description contributes no new content word, it reports the item.

Why it matters

The name is the first thing an agent reads. The description exists to add what the name cannot: the task in plain language, the inputs, the result and the limits. A description that repeats the name wastes the one field built for that job.

Anthropic’s skill authoring guidance (vendor guidance) says the description “should include both what the Skill does and when to use it.” The tool descriptions guide asks for the same in task language.

How to fix

Say what the item does in task language, what it needs and what it returns. Name the object it acts on and any important limit, such as a page size or a scope.

Example

Before

Usage: billing <command> [options]

Commands:
  invoices    Invoices
  customers   Manage customers
  sync        Run sync

After

Usage: billing <command> [options]

Commands:
  invoices    List, create and void invoices for one customer account
  customers   Look up, add and archive customer records
  sync        Pull new payments from the bank feed into the ledger (safe to repeat)

How ax-check detects it

  1. The name is split into words at underscores, hyphens, dots, spaces and camelCase boundaries, so getUserById, get_user and dns.records all become separate words.
  2. The description is split into words. Common stop words (“the”, “a”, “for”, “returns” and similar) and bare numbers are removed.
  3. Words that describe the kind of item rather than what it does are also removed: tool, command, subcommand, endpoint, operation, function, method, API, CLI, utility, helper, skill, run, execute, call, invoke, manage, handle, perform, and their plural or third-person forms.
  4. Both sides pass through a light stemmer, so “users” matches “user” and “deletes” matches “delete”.
  5. The rule fires when every remaining description word is in the name. It also fires when nothing remains, for example “Runs the command.”

This rule runs only when AXC-D002 did not fire. When it fires, AXC-D015 (description too short) is not reported for the same item, so one weak description gives one finding.

Known false negatives: one extra vague word is enough to pass. “Gets user data” passes for get_user, although “data” adds little. The rule does not judge quality, only whether anything new was said.

Known false positives: a very long, descriptive name, such as list_unpaid_invoices_for_customer, can make an accurate one-line description look like a restatement. Even then, adding the limits or the result usually helps. Silence the rule with --disable AXC-D003 if the finding does not apply.

Sources

Records in the AX evidence register that share a pattern tag with this rule. A shared tag means the record is about the same pattern, not that it tests this rule. Read the evidence class before the number.