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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds two genuinely non-obvious facts: report numbers only refresh once a day so today's documents appear tomorrow, and the tool requires a Joist Elite subscription or trial. It also documents the cursor round-trip ('Pass next_cursor back as cursor'), which the annotations do not.

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?

Purpose and scope are front-loaded in the first sentence, followed by return details, operational caveats, and the pagination note in a logical order. It is slightly verbose in re-listing the per-report contents already spelled out in the schema's enum descriptions.

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?

There is no output schema, so the description must carry the return semantics, and it does: it names the reports available, what 'total' means, and how pagination continues. Minor gap is that the per-document row fields are only sketched (e.g. 'invoices: status, total, balance and due date') without stating the response container shape.

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?

With 86% schema coverage the baseline is 3, but the description adds real meaning on top: it clarifies that 'client' is optional scoping, explains what 'total' is in the response, and instructs how to feed next_cursor into 'cursor'. Only tax_name is left to the schema alone, which is acceptable given its inline enum description.

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+resource ('A Joist report for a date range') and immediately enumerates the four report kinds it can return, which lets an agent separate it from list_invoices / list_estimates without opening the schema. The addition of 'with the period total' pins down the returned shape.

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?

Implies usage through context ('Returns one of the reports on Joist's Reports page', 'optionally for one client', 'part of Joist Elite'), which is enough to infer this is the aggregate/reporting path rather than raw listing. However, it never names an alternative such as list_invoices or export_documents, and gives no explicit when-not-to-use guidance.

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