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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds rich behavioral context beyond them: balance_notice means a reported 0.00 balance may still have outstanding debt, bankData derived fields can lag after connection creation, provider_incident can make balances unreliable, and identity_notice requires dedup by account number before summing balances. These are exactly the non-obvious behaviors an agent needs to avoid giving misleading answers.

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 description is long, but it is front-loaded with the core return contract and organized into clear caveat paragraphs. Every sentence earned its place given the complexity and missing output schema, though some parenthetical explanations and repeated references to `bank`/`connector_id` could be slightly tightened without losing meaning.

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?

Given that there is no output schema and very sparse parameter documentation, this description is exceptionally complete. It explains the result shape, field-level semantics, single-bank vs cross-bank behavior, batching, stale data, connector incidents, identity deduplication, and when to delegate to sibling tools. An agent has enough context to select, invoke, and interpret this tool correctly in most realistic scenarios.

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 0%, so the description carries the burden, and it does a strong job on `item` and `item_ids` by explaining their behavioral difference. However, the `type` parameter and singular `item_id` are only inferable from the enum and the bulk-support sentence rather than being explicitly tied to their filtering or batching semantics.

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 first sentence states a specific verb ('Returns') and resource ('accounts for a bank connection'), then enumerates account categories (BANK, CREDIT) and returned fields (balance, number, type, subtype, bankData, creditData). It clearly distinguishes the bulk-all-banks behavior from single-bank behavior and differentiates this tool from siblings like openfinance_list_credit_card_bills.

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?

The description gives explicit when-to-use guidance: OMIT `item` to list accounts across ALL linked banks when the user asks for 'my accounts/cards' without naming a bank, and pass `item` to target a single bank. It also explicitly routes the agent to openfinance_list_credit_card_bills for standardized open-bill amounts and to openfinance_force_sync for reconciling stale derived fields.

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