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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, yet the description still adds substantive behaviour: a fixed 30-day window on the movement list, the meaning of off_by (holding account surplus over Stripe's balance, net of holds and unbooked amounts), and the fact that gaps are only flagged when nothing pending explains them. It also correctly restates the read-only boundary with the redirect to the Payouts page for action, which is consistent with the annotations.

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?

Nothing is wasted semantically, but the payload is packed into one ~90-word sentence with a nested parenthetical defining off_by mid-list, so it is not front-loaded and is hard to parse. Reformatting the six return elements as a short list would materially improve it without adding length.

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 has to describe the return surface and does so item by item, including the id/record-type fields an agent needs to chain into get tools. The only gap is that it never says how the result changes when several connected companies or Stripe accounts exist, which the schema only partly covers.

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% and both parameters (company, stripe_account) are already documented as optional when only one connection exists, so the schema carries the load. The description adds nothing about how the tool behaves when several companies or Stripe accounts are connected, so the baseline 3 is appropriate.

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 names a specific verb and resource and enumerates what the answer contains: synchronisation of the QuickBooks holding account with Stripe's balance, off_by, records Caribooks did not write, items needing the user, the last payout, and 30 days of booked movements. The domain vocabulary ('Caribooks', 'holding account', 'off_by') is dense and never defined, but the scope is unmistakably a payout reconciliation status read rather than a setup or save operation.

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?

It implies the sequencing: returned movement record types and ids are meant to be fetched with the get tools, and it states that answers and booking happen on the Caribooks Payouts page, which tells the agent this tool cannot resolve anything. There is no explicit routing to or away from get_payout_setup / save_payout_setup, so the choice among the payout siblings is left to inference.

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