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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the description's job is to add context — and it does: it discloses the field projection limits, that results are paged one page per call, and that output is scoped by token permissions. It stops short of stating page size, rate limits, or ordering, which would complete the picture.

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 compact sentences with zero filler, and the return-field inventory is front-loaded. The lead is a noun phrase of returned fields rather than a verb+resource statement, which is slightly less scannable than it could be, but nothing is wasted.

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, the description usefully documents the returned shape and exclusions, and it covers the paging and permission caveats. However, for a 4-parameter filtered list tool it says nothing about the date-range and site filters, and it omits the list-vs-get distinction against famly_get_invoices, leaving real gaps.

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 only 25% — only nextToken is documented, while siteIds and the two date-range objects (createdDateRange, invoiceDateRange with nested from/to) carry no format or semantics in either schema or description. The description never mentions filtering by site or date range, so it fails to compensate for the coverage gap on 3 of 4 parameters.

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?

The description enumerates exactly what the call returns (invoice IDs, numbers, totals, dates) and what is excluded (line descriptions, child records, PDF links), which makes the resource and projection unambiguous. It does not differentiate itself from the sibling famly_get_invoices, so the agent cannot tell from the description alone which of the two to pick.

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?

'One page per call' implies a pagination loop and 'results depend on token permissions' flags an auth caveat, but there is no explicit when-to-use guidance and no statement of when to prefer famly_get_invoices over this list tool. The agent is left to infer selection and pagination behavior.

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