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

Adds behavior beyond the annotations: multi-language header detection, skipping of previously imported lines, the resulting state of lines in books_bank_lines, and that max_lines caps both lines added and price. The per-line charge note is useful cost context; the trailing 'Free.' fragment is ambiguous and slightly muddies the pricing signal.

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?

Four compact sentences, front-loaded with the core action and formats, then the fallback, then dedupe, then outcome. The closing 'Charged per line added. Free.' is a fragment whose meaning ('free' for what?) costs a beat of clarity.

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 7-parameter, nested-object import with no output schema, the description covers formats, header detection, dedupe, downstream state and pricing — enough to call it correctly. It stops short of saying what the call returns (lines added vs. skipped counts), which would have closed the last gap given no output schema exists.

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 already 86%, so the baseline is 3; the description earns above that by explaining the columns fallback in terms of real failure modes (headers in several languages) rather than restating field docs. It does not touch decimal, date_format, currency, or max_lines semantics, leaving those entirely to the schema.

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?

States a specific verb and resource — read a bank statement from the file store onto a bank account — and enumerates the accepted formats (CSV as exported, CAMT.053/.052/.054, OFX/QFX). It also distinguishes itself from the sibling cluster by describing the handoff to books_bank_lines and books_match_bank_lines, so an agent can tell it isn't the matching or listing tool.

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 concrete when-conditions: use the columns parameter when headers aren't auto-detected, and overlapping statements are safe to import. It doesn't explicitly say what to do before (uploading to the file store) or after (calling books_match_bank_lines), but the queue reference points the agent in the right direction.

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