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

Even with readOnlyHint and idempotentHint annotations already present, the description adds substantial behavioral context: `balance` can be connector-dependent, `balance_notice` indicates outstanding amounts when balance is zero, bankData extras may lag and require a force sync, provider incidents can make values unreliable, and identity_notice requires deduplication by account number. These are exactly the kind of non-obvious behaviors an agent needs to avoid misleading users.

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?

Though long, every section earns its place: the core return summary is front-loaded, followed by critical naming guidance, account selection instructions, and a series of warning signs that materially affect how results should be interpreted. The structure uses clear paragraphs and labels such as 'Note:', 'Bulk support:', and named notice fields, making the density navigable rather than bloated.

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?

With no output schema and no parameter descriptions in the schema, the description carries the full burden of explaining output semantics, edge cases, and alternatives. It covers the bank vs legal-entity name distinction, cross-connection aggregation, credit bill nuances, stale/lagging fields, provider incidents, joint-account deduplication, and bulk execution. The tool is complex, and the description is remarkably complete for safe and correct use.

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?

The input schema has 0% description coverage, so the description must compensate. It does explain `item` (omit for all, pass for single), `item_ids` (bulk execution), and implicitly describes `type` by naming BANK and CREDIT account categories. However, the `item_id` parameter is only mentioned as a returned field tag, not explained as an input parameter, and the filtering behavior of `type` is not explicitly stated. This leaves some parameter meaning to inference.

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 clearly states that the tool returns accounts for bank connections, enumerates both account types (BANK and CREDIT), and lists the returned fields (balance, number, type, subtype, bankData, creditData). It also distinguishes itself from openfinance_list_credit_card_bills by specifying that standardized open-bill data comes from that sibling, making the purpose unambiguous even among many related tools.

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 explicitly tells the agent when to omit `item` to list accounts across all linked banks versus passing `item` to target a single bank. It also routes the agent to openfinance_list_credit_card_bills when standardized open-bill amounts or closed bills are needed, and mentions bulk support via `item_ids`. This gives clear, actionable selection guidance.

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