ax-check rule

AXC-D002: Placeholder description

The description is a placeholder such as "TODO", "N/A", "description" or a repeated word like "ai ai".

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

Severityerror
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 lineReplace the placeholder with a sentence that says what the item does and when an agent should pick it.

The description is a placeholder, such as “TODO”, “N/A”, “description” or one word repeated, like “ai ai”. It fills the field, so a schema validator is satisfied, but it tells an agent nothing. In practice it is the same as having no description at all.

What it checks

ax-check reads the description of every tool, operation, skill and subcommand and asks whether it is filler text left over from a template or a generator.

Why it matters

An agent picks a tool by reading its description. A placeholder gives it no purpose, no inputs and no boundary, so the agent falls back on the name, or skips the tool entirely. Placeholders also hide from reviewers: the field is present, so a quick scan looks fine.

The Agent Skills specification requires a description that is non-empty and “Describes what the skill does and when to use it.” A placeholder passes the first test and fails the second. The tool descriptions guide sets out what a description should say instead.

How to fix

Replace the placeholder with a sentence that says what the item does and when an agent should pick it. If the item is not ready to be used, remove it from the surface until it is.

Example

Before

paths:
  /invoices/{invoice_id}/void:
    post:
      operationId: voidInvoice
      summary: TODO

After

paths:
  /invoices/{invoice_id}/void:
    post:
      operationId: voidInvoice
      summary: Void an unpaid invoice.
      description: >-
        Marks an unpaid invoice as void so it can no longer be paid. Use this
        when an invoice was sent in error. Do not use this for a paid invoice;
        use refundInvoice instead.

How ax-check detects it

The description is trimmed and lower-cased, and trailing full stops, exclamation marks, colons and semicolons are removed. It is a placeholder when any of these is true:

  • It is exactly one of a fixed list: todo, tbd, tba, fixme, xxx, n/a, na, none, null, undefined, nil, description, desc, placeholder, no description, no description provided, no description available, description goes here, add description, add a description, insert description here, enter description, lorem ipsum, test, temp, foo, bar, -, --, ..., the ellipsis character, or ?.
  • It starts with TODO, TBD, FIXME or XXX, in any case, followed by a colon, full stop, exclamation mark, hyphen or the end of the text. “TODO: write this” is reported; “Todo list: adds an item” is not.
  • It starts with “lorem ipsum”.
  • It is a single template slot in angle brackets, such as <description>.
  • It has no letters or digits at all.
  • It has two or more words and they are all the same word, such as “ai ai”.

When this rule fires, ax-check skips the other description rules for that item (AXC-D003 to AXC-D006, AXC-D015 and AXC-D020) and leaves it out of the similarity and length comparisons, because there is nothing to compare.

Known false positives: a description that is exactly one of the listed words but means something, such as “None” for a tool that does nothing on purpose, is reported. Write a real sentence instead, or silence the rule with --disable AXC-D002.

Known false negatives: placeholders outside the list, such as “Coming soon” or “Tool description”, pass this rule, and so does “TODO write this” with no punctuation after the marker. AXC-D003 and AXC-D015 catch some of them.

Sources

  • Specification: Agent Skills specification, agentskills.io, retrieved 2026-10-08. https://agentskills.io/specification . Requires a non-empty description that “Describes what the skill does and when to use it.”
  • Site guide: Write tool descriptions an agent can act on, agentexperience.tech. https://agentexperience.tech/insights/tool-descriptions/ . Says what a description should contain: purpose, when it is the right and the wrong choice, and the nearest neighbour.

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.