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

Even though annotations already mark the tool read-only and non-destructive, the description discloses many non-obvious behaviors: `name` is the legal entity rather than the brand, credit `balance` is connector-dependent, `balance_notice` means a zero value should not be presented as no debt, `bankData` fields can lag, and `provider_incident`/`identity_notice` can invalidate normal interpretation. This goes far beyond the annotations and prevents serious misreporting by an agent.

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 every section earns its place by introducing a caveat that materially changes how the agent should interpret results. It front-loads the main purpose and then organizes edge cases into focused blocks. It is slightly more verbose than strictly necessary, but the density of useful information is high.

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?

There is no output schema, so the description carries complete responsibility for explaining return values and edge cases. It covers the core fields, bank attribution, credit-bill semantics, provider incidents, identity notices, and bulk execution, giving an agent everything needed to call the tool and interpret its response correctly.

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?

With 0% schema description coverage, the description takes on the parameter-semantics burden and largely succeeds: it explains the key `item` contrast, mentions `item_ids` for batch calls, and the BANK/CREDIT enum is already self-describing in the schema. However, `item_id`'s precise relationship to `item` is left implied rather than explicitly described, preventing a perfect score.

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 states a precise verb-resource pair ('Returns accounts for a bank connection') and explicitly lists the two account types and the payload fields. It also clarifies the all-banks vs single-bank behavior, making the tool's purpose and scope unambiguous even among many similar sibling 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` (user asks for 'my accounts/cards' without naming a bank) and when to pass it. It also names `openfinance_list_credit_card_bills` as the correct alternative when standardized bill amounts are needed, and calls out `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.