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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description earns credit for adding what they don't: default and max page size, sort order, the returned field set, the per-currency aggregation of totals/paid/owed, and an ownership/permission boundary. It stops short of stating pagination termination behavior or whether totals reflect the full filtered set or just the current page.

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 dense sentences, front-loaded with what the tool returns before the access caveat, with no filler. It is longer than strictly necessary because the return-field enumeration is packed in, but each clause carries information.

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 and 9 optional parameters, the description compensates by describing the return payload (fields, sort, page size) and the aggregate totals per currency, plus the permission boundary. An agent has enough to call this correctly and interpret the result.

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 89%, so the schema already documents q, to, from, kind, page, status, boardId, clientId and pageSize. The description adds only the cents unit on monetary values and restates status names (even omitting 'open', which the schema supplies). Baseline 3 is correct when the schema carries the parameter burden.

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 verb and resource ('Lists the user's invoices and estimates') and pins down scope: newest first, 25 per page up to 100, with the exact fields returned. This clearly separates it from single-document siblings like get_invoice and from export_invoices_csv.

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?

Usage is implied by the enumeration scope rather than stated. The one real routing signal is the access constraint ('Only the account's owner has invoices; other project members do not read them'), which tells an agent when this call is authorized. No alternatives such as get_invoice, export_invoices_csv or list_unbilled_work are named or contrasted.

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