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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds one genuinely useful behavior detail — that responses carry a next_offset pagination cursor — but says nothing about result size, default limits, or whether filters combine.

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 resource and scope. Nothing is wasted, though "Follow next_offset" is terse to the point of ambiguity about where that field appears.

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 75% of parameters undocumented, the description should explain the returned shape (fields, cursor location) and the filter semantics. It alludes to next_offset but never defines the response or the filtering model.

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 only 25%: only business_id is described in-schema, leaving limit, offset, and the status enum undocumented. The description does not compensate — it never mentions status filtering (the one enum), page-size limits, or how offset relates to next_offset.

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 concrete verb+resource (list invoices) and adds a distinguishing scope note ("with reported balances"). It doesn't explicitly contrast with invoice_get or siblings like billables_list/payments_list, but a reader can tell this is the collection endpoint rather than the single-invoice endpoint.

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?

No guidance on when to use this versus invoice_get or the other *_list tools, and no mention of how to narrow results. "Follow next_offset" implies pagination but not the conditions for calling the tool at all.

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