Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description asserts "Reads only," but the annotations declare readOnlyHint=false, i.e. the tool may modify state. That is a direct conflict about the tool's safety profile, the single most important property for an agent deciding whether to invoke it. Whatever accurate detail the description adds about returned fields is undercut by this contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with zero filler: the return payload is front-loaded, then the read-only claim, then the routing pointer. Every clause carries information and the ordering puts the most decision-relevant content first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly carries the burden of explaining return values and does so concretely (lines, VAT, totals, reason, reversed invoice details). The one gap is that it doesn't clarify how it relates to credit_note_text/credit_note_pdf for an agent choosing between them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter already documents both accepted forms ("CN-2026-0001" or an exact client name), so the schema does the heavy lifting. The description's "by id or exact client name" restates that without adding format or disambiguation detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb and resource ("Return one credit note") plus an explicit inventory of what comes back: negated lines, VAT lines, totals, reason, and the reversed invoice number and date. It also names the lookup keys (id or exact client name), so an agent can distinguish it from credit_note_list without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit routing advice: "Use credit_note_list for the ids," which tells the agent when to pick the sibling instead. What's missing is any guidance versus credit_note_text and credit_note_pdf, which are the other retrieval-style siblings and could plausibly be confused with this one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.