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

The description carries substantial behavioral detail beyond the annotations: the arithmetic validation (opening + rows = closing), the refusal that names the gap (P-3), duplicate statements refused a second time (P-4), rows already on record skipped and listed back, and an explicit effects list (source recorded, transactions recorded with provenance). With readOnlyHint=false and destructiveHint=false already declared, this adds real operational context rather than repeating it.

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 core instruction is front-loaded and most sentences do work, but the prose is stylistically ornate ('Hand over one statement', 'retyping rows is where digits slip') and the bare codes P-3 and P-4 are introduced without explanation. Slightly tightened wording would carry the same payload in less space.

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 17-parameter mutation with no output schema, the description covers validation rules, failure modes, duplicate handling, and resulting side effects, which is what an agent needs to call it safely. What is missing is any statement of what comes back on success (a batch or source id) to bridge into review, and the opaque P-3/P-4 references are left for the agent to guess at.

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 a baseline of 3 would be defensible, but the description adds genuine meaning: `text` is the preferred input, `rows` is the paper-only fallback, `hash` is passed only with rows because it is computed from text, and `row_count` should be omitted when the statement does not print one. It also supplies the strong warning never to adjust a line to make it balance.

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 sentence names the resource (one statement: printed balances plus its lines) and the outcome (accepted whole or refused with the gap named), which is specific enough to distinguish it from neighbouring purchase tools. It stops short of naming sibling tools, though 'Nothing is categorised here; review follows' points at the review step without naming purch_review_batch.

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 gives strong, explicit guidance on which input mode to use: `text` is 'the normal way, and the only way when you have the text', and `rows` 'exists for one case only'. That said, the guidance is entirely about choosing between its own parameters and says nothing about when to reach for this tool versus purch_add_receipt, purch_add_bill, or purch_review_batch.

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