List settlements (payouts of your available balance to your bank account)

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds domain context (settlement account configured in the dashboard, scheduled or on-demand payouts) but says nothing about result ordering, pagination behavior, or volume of data, so it adds modest value beyond 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?

The title and the first sentence of the body are near-identical, and the second paragraph restates the same definition before adding the filter note. The payoff content (filtering by status/subaccount) is buried at the end, so the text is redundant rather than front-loaded.

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 could reasonably say something about what a settlement record looks like or how results are ordered and paginated. With full schema coverage and read-only annotations most essentials are covered, so this is adequate but not complete for a list tool whose result shape is undefined.

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%, so the schema already documents limit, status, created, subaccount, and both cursors. The description only restates that you can filter by status or subaccount, adding no syntax or semantics beyond the schema, and it omits mention of the created range and cursor pagination that the schema defines. Baseline 3 holds.

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 gives a specific verb (list) and resource (settlements) and immediately defines the resource in business terms: payouts of your available balance (or a subaccount's) to the settlement account set in the dashboard. That lets an agent distinguish it from get_settlement (single object) and list_settlement_items (line items of a settlement). It does not explicitly name those siblings as alternatives, which keeps it just short of a 5.

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?

Usage is implied rather than stated. Saying settlements are payouts of available balance to your settlement account gives enough context to infer when this tool is relevant (checking payout history), but there is no explicit when-to-use vs when-not, and no guidance on using list_settlements vs get_settlement or get_subaccount_balance.

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