AXC-D013: Near-duplicate descriptions

Two entries in the same file have descriptions so similar that an agent has no text to tell them apart. It will pick one of them by position, by name or by chance. This usually happens when one description was copied from another and never rewritten.

What it checks

ax-check compares the description of every entry with the description of every other entry in the same file, and reports pairs that are identical or nearly so.

Why it matters

Overlapping tools are common across MCP marketplaces. Tang, Chen and Xiao mapped 1,328,233 tool specifications from 124,267 MCP servers; the paper’s claim (October 2026) is that 98.5% of tools have at least one functional alternative somewhere in the ecosystem. Overlap is fine when each description says what makes its tool different. It is a problem when the text is the same.

Anand and Chattaraj tested how models handle tools built to look right while being wrong, including “semantic decoys” and “capability mirages”. The paper’s claim (8 models, 120 tasks, August 2026) is that such decoys mislead tool selection, with susceptibility varying about 36 times across models. Two near-identical descriptions in your own catalogue may act as accidental decoys for each other. That is design rationale: the paper planted deliberate decoys and did not test accidental duplicates.

How to fix

Rewrite both descriptions so each one states the difference: what it does that the other does not, and when to choose it. Name each as the other’s neighbour (see AXC-D006). If the two entries really do the same thing, remove one.

Example

Before

[
  {
    "name": "archive_invoice",
    "description": "Archives an invoice so it no longer appears in customer invoice lists."
  },
  {
    "name": "void_invoice",
    "description": "Archives the invoice so it no longer appears in the invoice lists for a customer."
  }
]

After

[
  {
    "name": "archive_invoice",
    "description": "Archives an invoice so it no longer appears in invoice lists. It can be restored later with restore_invoice. Use void_invoice instead when the invoice was issued in error and must never be paid."
  },
  {
    "name": "void_invoice",
    "description": "Voids an invoice that was issued in error, so it can never be paid and cannot be restored. Use archive_invoice instead to tidy up a paid invoice that may be needed again."
  }
]

How ax-check detects it

The rule compares every pair of entries that have a real description. Entries with no description, or a placeholder (AXC-D002), are left out. Entries that share a name are skipped, because AXC-D014 reports them.

1. Two descriptions are identical when they match after lower-casing and dropping everything except letters and digits. Differences in punctuation or spacing do not count.
2. Otherwise, each description is reduced to a set of content words: stop words and bare numbers are removed, and a light stemmer maps “archives” to “archive” and “lists” to “list”.
3. If both sets have at least four words, the similarity is the Jaccard index: the number of shared words divided by the number of distinct words across both.
4. The rule fires when the similarity is 0.8 or more. The default can be changed only through the duplicateThreshold option of the lintSurface library function; there is no command-line flag for it.

Each pair is reported once, on the later entry, with the other entry’s name and the similarity.

Known false negatives: the threshold is strict on purpose. “Lists open invoices for a customer account” and “Lists paid invoices for a customer account” score about 0.67 and are not reported, although an agent may still confuse them. Very short descriptions, with fewer than four content words, are compared only for an exact match. Names are not compared.

Known false positives: entries that genuinely differ only in a detail the words do not show, such as two API versions of one operation, may be reported. State the difference in the text, or silence the rule with --disable AXC-D013.

Sources

• Paper: Anand and Chattaraj, “Diagnosing Tool-Selection Reasoning in LLM Agents with Canary Tools”, arXiv 2608.04719, 5 August 2026 (preprint, not peer reviewed). https://arxiv.org/abs/2608.04719 . The paper’s claim, across 8 models and 120 tasks, is that decoys such as semantic decoys and capability mirages mislead tool selection, with susceptibility varying about 36 times across models.
• 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 is that 98.5% of 1,328,233 MCP tools have at least one functional alternative.
• 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 and say when it is the wrong choice.

Related evidence

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.

• EV-0020: Praise and list order move tool selection (Preprint). A preregistered preprint with two small OpenAI models found that stacked praise in a tool description raised its pick rate by about 43 percentage points, and that with identical listings the first-listed tool was picked about 72 points more often.
• EV-0001: An enum in the schema ends silent failures from example-only vocabularies (Preprint). SilentProbe (preprint) reports that a vocabulary a parameter description only exemplified ("e.g.") was missed on 88 of 88 attempts across twelve models, and that promoting it into the schema cut the failure to 0 of 89.
• EV-0003: Error text that names the next tool lifts recovery (Preprint). A preprint testing five OpenAI models reports that an expired-credential error naming a terminal command left 45% of tasks recovered, naming the server's login tool instead raised recovery to 84%, and on rate limits naming the call to repeat raised recovery from 6% to 88%.
• EV-0018: Skill rules that name a command or path change what agents do (Preprint). A study of 3,159 skills (preprint) found that adding a checkable rule raised the rate at which four coding agents took the required action by +0.23 on average, with the gain coming mainly from rules naming a command or path the old skill did not mention.
• EV-0019: Skill selection precision collapses as the skill pool grows (Preprint). A preprint reports that as the pool of available skills grew from 5 to 100, the precision with which agents actually used the right skill fell from 29.6% to 3.3%.
• EV-0021: Agents leave available tools unused: the adoption gap (Preprint). On OSWorld-MCP (preprint), a reasoning model given MCP tools called one on only 55 of 309 tasks, 23.9% of the tasks a tool could reach, and the same tools made a non-reasoning model 5.9 points worse.

Related guides

• Write tool descriptions an agent can act on
• Agent tool catalogues need a pruning strategy