ax-check rule

AXC-D015: Description too short

The description has fewer than six words, too few to say what the item does and when to use it.

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

Severitywarn (info for CLI help)
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 lineExpand to at least one full sentence of purpose and one of when to use it.

The description has fewer than six words. That is too few to say what the item does, what it needs and when an agent should choose it. A short description is not wrong in itself, but it almost always leaves out the information an agent uses to choose.

What it checks

ax-check counts the words in each description and reports any description with fewer than six. It looks at the MCP tool description, the OpenAPI operation summary and description together, the SKILL.md frontmatter description and the one-line description of each CLI subcommand.

Why it matters

An agent chooses between tools by reading their descriptions. A description such as “Creates an invoice.” tells the agent the action, but not what the invoice needs, what comes back or when another tool is the better choice. The agent then guesses, or asks the user for information the description could have given.

Guidance for skills says the same. The Agent Skills specification says the description “Describes what the skill does and when to use it.” Anthropic’s skill authoring guidance (vendor guidance) says the description “should include both what the Skill does and when to use it.” Five words rarely carry both.

CLI subcommand lists are often kept to one short line by design, so this rule is information only for CLI help.

How to fix

  • Write at least one full sentence of purpose: what the item does, to what, and what it returns.
  • Add one sentence of when to use it, and ideally one of when not to.
  • Keep reference detail (every option, every error) out of the description; put it in the schema or the docs.

Example

Before

{
  "name": "create_invoice",
  "description": "Creates an invoice."
}

After

{
  "name": "create_invoice",
  "description": "Create a draft invoice for one customer and return its invoice ID. Use this when the user asks to bill a customer for work already done. Do not use this to send an invoice; use send_invoice after the draft is checked."
}

How ax-check detects it

A word is a run of letters or digits, and it may contain apostrophes and hyphens, so “read-only” counts as one word. A description with fewer than six such words is reported, and the finding gives the count.

Each description gets at most one of three related findings, in this order: a placeholder (AXC-D002), a description that only restates the name (AXC-D003), or a short description (this rule). A missing or empty description is reported by AXC-D001 instead (by AXC-D022 for skills).

Known false positives: a very simple item can be fully described in five words, for example “Return the server version string.” Known false negatives: six or more words of filler pass this rule. Other rules (AXC-D004, AXC-D005 and AXC-D006) look for the content a good description needs.

If the finding does not apply, silence it with --disable AXC-D015.

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.