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

Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, destructiveHint=false. The description adds concrete behavioral details beyond annotations: it transforms lines into invoice/quote-ready items, prices from catalogue, refuses unknown codes by name without pricing them, and states the operation is free. These are useful runtime behaviors not encoded in annotations.

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 sentences, front-loaded with the main action, and every sentence adds value. It says what the tool transforms, what it produces, the pricing basis, unknown-code refusal, and cost.

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?

Given the rich input schema (100% parameter coverage) and the annotations (readOnly, idempotent, non-destructive), the description is complete enough: it explains the purpose, the refusal behavior, and cost. No output schema is needed because the tool feeds well-known invoice_create/quote_create flows.

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 description coverage is 100%, so the schema already documents each parameter fully. The description's added value is the overall orchestration (making lines invoice/quote-ready from catalogue pricing) rather than per-parameter semantics, so the baseline 3 is appropriate.

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?

States a specific transformation verb ('Turn a list of sku or role lines into invoice_create-ready and quote_create-ready items priced... from the catalogue as of each line's date') and clearly differentiates from siblings like sku_list, rate_get, and price_list_pdf. It also highlights a key behavioral guarantee (unknown code is refused by name and never priced).

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?

The description specifies what to use the tool for (build invoice/quote lines) and provides context like 'as of each line's date' and 'free', but doesn't explicitly name alternatives to avoid or state when not to use it. The sibling list is broad, so an explicit 'when not to use' would have been stronger.

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