ax-check rule

AXC-D008: Parameter has no description

An input parameter, property or flag has no description, so an agent must guess its meaning and format.

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

Severitywarn
KindConformance. A finding is a fact about the input.
Modeax-check lint
Applies toMCP tool lists, OpenAPI, SKILL.md, CLI help
Pattern tagsdescription, schema-enum
Fix in one lineDescribe each parameter: what it means, its format, its default and any limits.

An input parameter, property or flag has no description. The agent sees a name and perhaps a type, and must guess the meaning, the format, the unit and the default. A wrong guess often produces a call that is accepted but does the wrong thing.

What it checks

ax-check reports every parameter whose description is missing or blank. Each one is reported separately, with a pointer to where it is defined.

Why it matters

Parameters are where most wrong calls start. A field called since could be a date, a timestamp or an ID. A field called amount could be in pounds or in pence. A field called limit may have a maximum the server enforces quietly. The name rarely says which.

Li, Ye, Guo and Dang found that constraints often live in prose rather than in the schema: the paper’s claim (SilentProbe, August 2026, 2,501 OpenAPI documents) is that 40.1% of documents state a constraint in prose that the schema does not encode. A parameter with no description has neither: no machine-checkable constraint and no prose either. The tool descriptions guide asks for parameters to be written as carefully as the tool description.

How to fix

Describe each parameter: what it means, its format, its unit, its default and any limits. Put anything a machine can check into the schema as well (enum, format, pattern, minimum, maximum), and use the description for meaning.

Example

Before

paths:
  /invoices:
    get:
      operationId: listInvoices
      summary: List invoices for the current account.
      parameters:
        - name: since
          in: query
          schema:
            type: string
            format: date
        - name: limit
          in: query
          schema:
            type: integer

After

paths:
  /invoices:
    get:
      operationId: listInvoices
      summary: List invoices for the current account.
      parameters:
        - name: since
          in: query
          description: Only return invoices issued on or after this date (UTC). Omit it to start from the oldest invoice.
          schema:
            type: string
            format: date
        - name: limit
          in: query
          description: Maximum number of invoices to return. Default 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20

How ax-check detects it

A parameter fires the rule when its description, after trimming, is empty. What counts as a parameter depends on the surface:

  • MCP: each top-level property of the tool’s inputSchema.
  • OpenAPI: each path, query, header and cookie parameter (operation-level parameters override path-level ones with the same name and location), and each top-level property of the JSON request body. A description written next to a $ref, which OpenAPI 3.1 allows, counts.
  • CLI help: each flag in the root help and in each subcommand’s help. --help, -h, --version and -V are skipped everywhere. -v is checked like any other flag, because many tools use it for verbose output.
  • SKILL.md: skills have no parameters, so the rule does not fire there in practice.

When a parameter has no description, AXC-D007 is not checked for it, because there is no prose to read.

Known false negatives: nested properties inside an object parameter are not checked. A placeholder such as “TODO” counts as a description here; AXC-D002 checks placeholders only for items, not parameters.

Known false positives: a parameter whose meaning is truly obvious from its name and schema, such as a boolean --quiet flag, may still be reported. A few words are cheap, but you can silence the rule with --disable AXC-D008.

Sources

  • Paper: Li, Ye, Guo and Dang, “SilentProbe: Measuring Silent Failure in Production APIs Used as Agent Tools”, arXiv 2609.00035, submitted 29 August 2026 (preprint, not peer reviewed). https://arxiv.org/abs/2609.00035 . The paper’s claim, across 721,320 parameters in 2,501 OpenAPI documents, is that 15.2% of parameters declare any machine-checkable constraint and 40.1% of documents state a constraint only in prose.
  • Site guide: Write tool descriptions an agent can act on, agentexperience.tech. https://agentexperience.tech/insights/tool-descriptions/ . Asks for parameters to say what they mean and to put closed sets in the schema.

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.