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

Adds substantial context beyond the annotations: the dry-run-until-commit=true gate, side-effect on card terms (limit, statement day, due date, minimum due), the match-or-add behavior for lines, the auto-generated 'Balance adjustment' row that "never counts as spending," and replacement-on-reread. The re-send replacement nuance is consistent with idempotentHint=false (the tool is still not globally idempotent).

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?

A single dense ~90-word paragraph with the core purpose front-loaded and every sentence carrying information. It is appropriately sized for a 13-parameter tool, though the mid-sentence "whatever still separates the ledger from the closing balance" phrasing is somewhat convoluted and could be tighter.

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 complex, write-behind tool, the description covers the main workflow end to end: anchoring, terms-setting, line handling, adjustment creation, ordering, re-send, and dry-run. The output schema and 100%-covered input schema carry the remaining burden; the description could have acknowledged the accounting-only params (fees, interest, apr_percent, previous_balance) but their schema descriptions already say they are used only when lines are absent.

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 the baseline is 3, but the description adds real relational meaning: it identifies statement_date + closing_balance as the pair that anchors the ledger, explains that lines are matched or added against the closing balance, and positions commit as the write gate. This goes beyond the schema's literal per-field descriptions.

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 opening phrase — "One credit-card statement, as the bank printed it" — names a specific resource, and the body makes the action concrete: give statement date + closing balance and the ledger is anchored to the bank. It clearly distinguishes itself from siblings like import_statement or reconcile_statement by scoping to card statements and by describing the anchoring behavior.

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?

Gives explicit procedural guidance: "Send statements oldest first, one call each" and explains re-send semantics ("re-sending the same statement date replaces its adjustment instead of stacking"), plus the dry-run default. It does not, however, name alternatives or state when to prefer this over siblings such as import_statement or set_credit_card, so exclusions are implicit rather than explicit.

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