ax-check rule

AXC-D021: Many visible parameters

The tool exposes more than 15 parameters, and every visible parameter is one more an agent may fill wrongly.

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

Severityinfo
KindHeuristic. A pattern match: a prompt to look, not a verdict.
Modeax-check lint
Applies toMCP tool lists, OpenAPI, CLI help
Pattern tagsselection, context-budget
Fix in one lineHide rarely used parameters, give them defaults, or split the tool by task.

The tool exposes more than 15 parameters. Every visible parameter is one more thing an agent must read, decide about and possibly fill wrongly, and it adds to the context cost of the tool. This is information, not a failure: some tools need many inputs, but most calls use only a few of them.

What it checks

ax-check counts the inputs of each tool, operation or subcommand and reports any that has more than 15.

Why it matters

An agent sees every parameter in the schema and has to decide, for each one, whether to set it and to what. Rarely used options sit beside the essential ones with the same weight. If a parameter’s allowed values live only in prose, a wrong value may not even produce an error.

Most parameters carry no machine-checkable limits. In the SilentProbe paper (Li, Ye, Guo and Dang, arXiv 2609.00035, 29 August 2026), across 721,320 parameters in 2,501 OpenAPI documents, 7.5% declared an enumeration and 15.2% any machine-checkable constraint (the paper’s claim). The more parameters a tool shows, the more places such a gap can hide.

Splitting is a trade-off, not a free win: more, smaller tools mean more entries to choose between. In MCP-GRANITE (Paschalides et al., arXiv 2609.24161, 21 September 2026), a 4-tool interface gave the best trade-off in the authors’ setting (the paper’s claim, with small local models).

How to fix

  • Give rarely used parameters sensible defaults and say so in their descriptions.
  • Hide expert options behind a single options object, or move them to a separate tool for the rare task that needs them.
  • Split the tool by task when different callers use different halves of the parameter list.
  • Put allowed values in the schema (enum, minimum, format) so the parameters that remain can be checked.

Example

Before

{
  "name": "create_invoice",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customer_id": {}, "amount": {}, "currency": {}, "due_date": {},
      "po_number": {}, "memo": {}, "footer": {}, "locale": {},
      "tax_rate": {}, "tax_id": {}, "discount_code": {}, "template_id": {},
      "logo_url": {}, "send_copy_to": {}, "late_fee_percent": {}, "reminder_days": {},
      "rounding_mode": {}, "custom_fields": {}
    }
  }
}

After

{
  "name": "create_invoice",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customer_id": {}, "amount": {}, "currency": {}, "due_date": {},
      "memo": {}, "options": { "type": "object", "description": "Rarely needed settings: tax, template, reminders. Defaults suit most invoices." }
    },
    "required": ["customer_id", "amount", "currency"],
    "additionalProperties": false
  }
}

The property schemas are left empty here to keep the example short; real ones need types and descriptions.

How ax-check detects it

ax-check counts the inputs of each entry and reports the entry when the count is more than 15. What counts as an input:

  • MCP: the top-level properties of inputSchema. Properties of nested objects are not counted.
  • OpenAPI: the path, query, header and cookie parameters (path-level and operation-level, with the operation’s version winning when both define the same one), plus the top-level properties of the JSON request body.
  • CLI help: the flags shown in a subcommand’s own --help, leaving out --help, -h, --version and -V. A -v flag counts, because -v can mean --verbose. The root command is not counted, and a subcommand whose help was not captured counts as zero.

The threshold of 15 is the default of the maxParams option of lintSurface in the ax-check library. There is no command-line flag for it. The finding gives the count.

Known false positives: tools that mirror a large, well-known interface (for example a full search API) may need every parameter. Known false negatives: a tool with 10 parameters, each a large nested object, passes.

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

Sources

  • Paper: Li, Ye, Guo and Dang, “SilentProbe: Measuring Silent Failure in Production APIs Used as Agent Tools”, arXiv 2609.00035, 29 August 2026. https://arxiv.org/abs/2609.00035. The paper’s claim: across 721,320 parameters in 2,501 OpenAPI documents, 7.5% declare an enumeration and 15.2% any machine-checkable constraint. Endpoints were reached through one aggregation layer with which the authors declare an affiliation.
  • Paper: Paschalides et al., “MCP-GRANITE”, arXiv 2609.24161, 21 September 2026. https://arxiv.org/abs/2609.24161. The paper’s claim, with small local models: a 4-tool interface gave the best trade-off in their setting.
  • Guide: Write tool descriptions an agent can act on, agentexperience.tech, retrieved 2026-10-08. https://agentexperience.tech/insights/tool-descriptions/. Write the parameters as carefully as the description and 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.