ax-check rule

AXC-D006: No neighbouring tool named

In a catalogue with more than one entry, the description does not name any other entry to use instead.

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, info for OpenAPI)
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 lineName the closest alternative by its exact name, for example "To find an invoice ID first, use list_invoices."

In a catalogue with more than one entry, this description does not name any other entry to use instead. Saying “use the other tool” is vague. Saying “use get_invoice when you know the ID” gives the agent an exact next move when it has picked the wrong item.

What it checks

For each item in a catalogue of two or more, ax-check checks whether the description mentions the exact name of at least one other item in the same file.

Why it matters

Overlap between tools is common across the MCP ecosystem. Tang, Chen and Xiao mapped 1,328,233 tool specifications from 124,267 MCP servers listed on 17 marketplaces; the paper’s claim (October 2026) is that 98.5% of tools have at least one functional alternative. Those alternatives are counted across the whole ecosystem, mostly on other servers. The abstract does not report how often tools inside one server overlap.

This rule applies the idea to neighbours inside your own catalogue, such as a list tool and a get tool, or a draft tool and a send tool. That step is design rationale, not something the paper establishes: such pairs are a common way to split a task, and they are the pairs an agent can confuse.

When the description names the neighbour, the agent can switch without a second search. It also forces the author to state the difference, which helps people reading the catalogue too. The tool descriptions guide asks for the nearest neighbour by name, and Agent tool catalogues explains how to keep a catalogue small and its entries distinct.

How to fix

Name the closest alternative by its exact name, and say when to switch. For example: “To find an invoice ID first, use list_invoices.” Ideally each pair of neighbours names the other.

Example

Before

[
  {
    "name": "get_invoice",
    "description": "Returns one invoice with its line items and payment history. Use this when the user refers to a specific invoice."
  },
  {
    "name": "search_invoices",
    "description": "Searches invoices by customer, status or date range and returns up to 50 matches. Use this when the user asks to find invoices."
  }
]

After

[
  {
    "name": "get_invoice",
    "description": "Returns one invoice with its line items and payment history. Use this when you know the invoice ID. If you do not know the ID, use search_invoices instead."
  },
  {
    "name": "search_invoices",
    "description": "Searches invoices by customer, status or date range and returns up to 50 matches. Use this when the user asks to find invoices. To read one invoice in full, use get_invoice instead."
  }
]

How ax-check detects it

The rule runs only when the file has more than one selectable item. The root of a CLI does not count as an item. For OpenAPI, an item’s name is its operationId, or its method and path when there is no operationId.

For each description, ax-check searches for the name of every other item, ignoring case. A name counts only as a whole identifier: it must not touch a letter, digit, underscore or hyphen on either side, so get_invoice inside get_invoice_pdf does not count. The item’s own name is ignored, and so are names shorter than three characters. The rule does not run when AXC-D002 found a placeholder.

Known false negatives: when names are ordinary words, which is common for CLI subcommands such as list, status or sync, any use of that word in prose counts as naming the neighbour. A deploy command described as “Builds the site and updates the status page” passes because it contains “status”. The rule also does not check that the named item is a sensible alternative.

Known false positives: a description that refers to a neighbour by a paraphrase (“the search tool”) is reported. Use the exact name. For a catalogue where items genuinely have no overlap, silence the rule with --disable AXC-D006.

Sources

  • Paper: Tingxuan Tang, Zilong Chen and Yue (Luna) Xiao, “Understanding the Hierarchical Structure and Functional Landscape of the Model Context Protocol Ecosystem”, arXiv 2610.05319, 4 October 2026 (preprint, not peer reviewed). https://arxiv.org/abs/2610.05319 . The paper’s claim, from 1,328,233 tool specifications across 124,267 servers on 17 marketplaces, is that 98.5% of tools have at least one functional alternative. The extension to neighbours inside one server is this rule’s design rationale.
  • Site guide: Write tool descriptions an agent can act on, agentexperience.tech. https://agentexperience.tech/insights/tool-descriptions/ . Asks every description to name the nearest neighbouring tool.
  • Site guide: Agent tool catalogues: how to keep an MCP tool catalog small, agentexperience.tech. https://agentexperience.tech/insights/agent-tool-catalogs/ . Discusses keeping a catalogue small so that its entries stay distinct.

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.