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

Annotations already mark the tool as read-only, idempotent, and non-destructive, but the description adds substantial behavioral detail: the snapshot semantics of updateDateTime/updatedAt, BALANCE_FETCH_ERROR and BALANCE_CONSENT_ERROR for credit accounts, structured warnings instead of throwing, and degraded fallback behavior when upstream is unavailable or the connector isn't Open Finance. This is a model of disclosing behavior beyond structured hints.

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 sentence earns its place: it covers purpose, freshness caveat, alternative action, error modes, degradation behavior, and response shape. The most critical information (snapshot, force_sync trigger) is front-loaded, and the response shape is compactly stated at the end.

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 only one parameter and no output schema, the description compensates fully. It states the response shape, all major error scenarios, the degraded mode, and the retry/reconnect workflow. An agent has everything needed to call this tool correctly and interpret unexpected results without extra lookups.

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 0%, so the description carries the burden. It explicitly says 'Pass account_ids as an array (1–50),' adding a size constraint and clarifying the required shape. It stops short of explaining item format ambiguity (e.g., whether IDs are UUIDs or provider-specific strings), but the schema already types items as strings. This is enough for confident invocation.

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 opens with a specific verb and resource ('Returns the latest available balance per account id') and names the endpoint (GET /accounts/:id/balance). It clearly differentiates this from siblings by emphasizing the freshness/snapshot behavior and referencing openfinance_force_sync and openfinance_list_transactions as complements, not substitutes.

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 usage context: it is a snapshot tied to the last upstream sync, not a live read. It instructs when to run openfinance_force_sync ('If a movement that just happened is not reflected yet... run openfinance_force_sync to pull fresh data and then re-read') and explains how credit-specific errors should be handled (reconnecting the bank). This goes well beyond 'use this to read balances.'

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