AXC-D004: Does not say when to use it

The description says what the item does, but never says when it is the right choice. An agent matches a user’s request against descriptions, so a trigger such as “Use this when the user asks why an invoice is unpaid” makes the match far easier than a bare statement of function.

What it checks

ax-check looks for a “when to use” phrase anywhere in the description of each tool, operation, skill and subcommand. If it finds none, it reports the item.

Why it matters

A description of function answers “what does this do?”. An agent is asking a different question: “is this the thing for the request in front of me?”. A sentence that names the task, the question or the situation answers that question directly.

For skills this matters most, because the description is often the only text loaded before the skill is chosen. The Agent Skills specification says the description “Describes what the skill does and when to use it.” Anthropic’s skill authoring guidance (vendor guidance) says it “should include both what the Skill does and when to use it”, and adds: “Always write in third person. The description is injected into the system prompt.”

CLI help and OpenAPI operations are often read by people as well as agents, and their conventions rarely include trigger sentences, so the finding is info there rather than a warning.

How to fix

Add a sentence that starts “Use this when …” and names the task or question it answers. Write it in the third person and describe the user’s situation, not the implementation.

Example

Before

---
name: invoice-reconciliation
description: Matches bank payments to open invoices and marks matched invoices as paid.
---

After

---
name: invoice-reconciliation
description: Matches bank payments to open invoices and marks matched invoices as paid. Use this when the user asks why an invoice still shows as unpaid, or asks to reconcile a bank statement. Do not use it to issue refunds.
---

How ax-check detects it

The rule passes when the description contains any of these phrase families, matched case-insensitively:

• “use this”, “use it”, or “use” followed by when, whenever, if, for, to, after, before or only, unless the word just before is “not”, “never” or “avoid” (or a contracted negative), so “Do not use this for refunds” does not count;
• call, invoke, choose, pick, select, run, trigger, load, apply or activate, then “this” or “it”, then when, if, to, for, after or before;
• “when” followed by you, the user, a user, users, an agent, the agent, asked, needed, working, someone, it is, there is or the task;
• useful, helpful, appropriate, ideal, intended, designed or meant, followed by for, when, if or to;
• “triggers on”, “triggers when”, “activates on”, “activates when”;
• “for questions about”, “for tasks that”, “for requests involving” and similar;
• “if you need”, “if the user asks”, “if an agent wants” and similar;
• “start here” or “begin with this”.

The rule does not run when AXC-D002 found a placeholder.

Known false negatives: the match is a phrase, not a meaning. A sentence such as “Designed for internal use” matches “designed for” without naming a task. Check by eye that a real trigger is present.

Known false positives: a trigger written in other words, such as “Answers billing questions from finance staff”, is not recognised. Rephrase it with one of the forms above, or silence the rule with --disable AXC-D004.

Sources

• Specification: Agent Skills specification, agentskills.io, retrieved 2026-10-08. https://agentskills.io/specification . Says the description “Describes what the skill does and when to use it.”
• Vendor guidance: Skill authoring best practices, Anthropic, retrieved 2026-10-08. https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices . Says the description “should include both what the Skill does and when to use it” and should be written in the third person because it is injected into the system prompt.
• Site guide: Write tool descriptions an agent can act on, agentexperience.tech. https://agentexperience.tech/insights/tool-descriptions/ . Asks every description to say when the tool is the right 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-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-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-0017: Injected skills lowered pass rates and raised token cost on average (Preprint). WebDev-Skills-Bench (preprint) found that injecting matched public skills reduced mean Pass@2 by 1.3% to 4.2% across four models and raised token cost by 72% to 394%, with gains in only 17% to 36% of skill-project pairs.

Related guides

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