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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial context beyond them: values are computed on read, all money is integer cents, remaining_cents must be copied rather than recomputed, overdue depends on sales_settings.timezone with an Asia/Singapore fallback, and activity is capped at the newest 50 events. These are exactly the traits an agent cannot infer from structured fields.

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?

Dense but front-loaded: the core action, the returned cents fields, then state semantics, then activity/view/confirmation contents, then error handling. Every sentence carries information, though the computed-field enumeration is slightly list-heavy and could be tightened.

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?

There is no output schema, so the description must carry the return-shape burden, and it does: it enumerates every cents field, the full state enum, the overdue/timezone rule, days_overdue, activity truncation, viewed_count, and payer_confirmations. An agent has enough to call this and interpret the result correctly.

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 there is a single `id` parameter, so baseline would be 3. The description adds real meaning by defining the failure semantics of that id (unknown id refuses with NOT_FOUND) and directing recovery, which goes beyond the schema's bare 'The invoice id.'

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?

Opens with a specific verb+resource: 'Returns one invoice.' It immediately distinguishes itself from the list/search siblings via the closing NOT_FOUND routing sentence, so an agent can tell it apart from invoice_list and invoice_search 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?

Names the alternatives explicitly ('find it with invoice_list or invoice_search') and the exact condition that should send the agent there (unknown id / NOT_FOUND). It stops short of a general when-to-use statement versus invoice_payment_list or invoice_adjustment_list, but for a single-record fetch that gap is small.

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