ax-check rule

AXC-D001: Missing description

A tool, operation, command or skill has no description, so an agent has nothing to choose it by.

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

Severityerror
KindConformance. A finding is a fact about the input.
Modeax-check lint
Applies toMCP tool lists, OpenAPI, SKILL.md, CLI help
Pattern tagsdescription, selection, discovery
Fix in one lineWrite a description that says what the item does, when to use it and when to use a neighbour instead.

A tool, operation, command or skill has no description. An agent chooses what to call by reading descriptions, so an item without one can only be picked by guessing from its name. This is the most basic gap on an agent-facing surface, and it is cheap to fix.

What it checks

For each item an agent can select, ax-check looks for description text:

  • MCP: the tool’s description field.
  • OpenAPI: the operation’s summary and description, joined. The rule fires only when both are missing or blank.
  • SKILL.md: a skill with no description in its frontmatter is reported once, by AXC-D022, rather than by this rule.
  • CLI help: the text next to a subcommand in the list of commands.

An empty string, or a string of only spaces, counts as missing.

Why it matters

In MCP, a client hands the model each tool’s name, description and input schema, and the model picks a tool from that list. A name such as create_invoice hints at the purpose, but it does not say what the tool needs, what it returns or when another tool is the better choice.

For skills the gap is stricter. The Agent Skills specification makes description a required, non-empty field that “Describes what the skill does and when to use it.” Anthropic’s skill authoring guidance (vendor guidance) says the description “enables Skill discovery”. A skill with no description may never be loaded at all, which is why ax-check treats it as invalid frontmatter (AXC-D022).

How to fix

Write a description that says what the item does, when to use it, and when to use a neighbour instead. Two or three short sentences are usually enough. See Write tool descriptions an agent can act on.

Example

Before

{
  "name": "create_invoice",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customer_id": { "type": "string", "description": "ID of an existing customer." },
      "amount_pence": { "type": "integer", "description": "Invoice total in pence, at least 1." }
    },
    "required": ["customer_id", "amount_pence"],
    "additionalProperties": false
  }
}

After

{
  "name": "create_invoice",
  "description": "Creates a draft invoice for an existing customer and returns its ID. Use this when the user asks to bill a customer. Do not use this to change an invoice that already exists; use update_invoice instead.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customer_id": { "type": "string", "description": "ID of an existing customer." },
      "amount_pence": { "type": "integer", "description": "Invoice total in pence, at least 1." }
    },
    "required": ["customer_id", "amount_pence"],
    "additionalProperties": false
  }
}

How ax-check detects it

The check is a plain presence test. ax-check trims the description and fires when nothing is left. For OpenAPI, an operation is named by its operationId, or by its method and path when there is no operationId.

What it deliberately leaves to other rules:

  • The root of a CLI is checked for its flags only, so a program with no tagline does not trigger this rule.
  • A skill with no description, or with frontmatter that is missing or does not parse, is reported by AXC-D022 instead, so one problem does not produce two findings. In practice this rule fires for MCP tools, OpenAPI operations and CLI subcommands.
  • Text that is present but empty of meaning, such as “TODO”, is reported by AXC-D002, not here.

Known false negatives: any non-empty text passes this rule, however weak. AXC-D002, AXC-D003 and AXC-D015 catch some weak descriptions. False positives are rare. If an item is deliberately hidden from agents and never offered to a model, silence the rule with --disable AXC-D001 (the flag can be repeated, or given a comma-separated list), but a short description is usually the better answer.

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.