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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond them: the pagination contract (pass next_cursor back as cursor) and an authentication requirement (Cotlet API key with access to this app). It stops short of describing result ordering or limits.

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?

It is reasonably front-loaded, leading with what the tool returns, but there is redundancy: the settled-invoices content is stated twice (once in the opening list, again as 'Each item names the invoices it settled with the amount applied'), and the type in/out meaning is repeated from the schema.

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?

For a read-only list tool with annotations covering safety and no output schema, the description supplies the missing pieces: the item shape, the pagination mechanism, and the auth requirement. Filtering parameters are left to the thoroughly documented schema, which is acceptable here.

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 100%, so every parameter is already documented, giving a baseline of 3. The description largely restates the type enum (which the schema already explains) but does add the pagination semantics for cursor, so it is at or slightly above baseline rather than below.

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 uses a specific verb (lists) and resource (payments received/made), and enumerates the content of each entry: date, method, bank account, and settled invoices. It also clarifies the directionality with the in/out type, distinguishing it from the write sibling alegra_record_payment.

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 explains what 'in' and 'out' mean and how to paginate with next_cursor, which implies when the tool is relevant. However, it never states explicitly when to use this versus alegra_list_invoices or alegra_record_payment, and gives no exclusions or prerequisites.

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