List invoices

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds no behavioral context beyond that — nothing about result volume, pagination behavior, or what the default limits mean in practice. It does not contradict the annotations, but it contributes essentially nothing behavioral.

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, front-loaded with the core action before the use cases, with no filler or repetition of the title. It is appropriately sized for a simple list tool, though the second sentence is a loosely packed list of scenarios rather than precise guidance.

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?

For a read-only, non-destructive list operation with fully documented parameters and clear annotations, the description is minimally sufficient. With no output schema, the agent still learns nothing about the shape of returned invoice records or whether results are paginated, which is a real but modest gap for a listing tool.

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%: each of the six parameters has its own description, including the DATE REFERENCE warning on dateFrom and the default/max on limit. The description adds no syntax, format, or filtering semantics beyond the schema, 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?

States a specific verb and resource ('Fetch invoice records') that clearly identifies a read of invoice data. However, it never distinguishes itself from adjacent read tools in the sibling set such as get_payments, get_estimates, or get_line_items, so an agent must infer the boundary. Clear but undifferentiated.

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 offers intended scenarios ('billing questions, unpaid balances, invoice status tracking'), which is implied usage guidance rather than explicit routing. It names no alternative tool and gives no when-not condition, so an agent choosing between this and get_payments or get_estimates gets no help.

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