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

Discloses substantial behavior beyond the readOnlyHint/idempotentHint annotations: the result is a SNAPSHOT anchored to the last upstream sync rather than a live read, updateDateTime/updatedAt is the sync instant, and it enumerates the full error taxonomy (BALANCE_FETCH_ERROR, BALANCE_CONSENT_ERROR, upstream 5xx, non-Open-Finance connector) all degrading to structured warnings instead of throwing. This is rich context annotations cannot express.

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?

Longer than typical, but every sentence earns its place: first sentence states the core purpose, then the freshness caveat, the force_sync alternative, the parameter constraint, and the error modes. It is front-loaded and dense with actionable information rather than filler, with no redundant restatement of the title.

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?

In the absence of an output schema, the description covers the critical response semantics (per-row updateDateTime/updatedAt, structured warning rows), all known error modes, and the follow-up action path. The only gap is a field-level contract for the returned balance rows (e.g., amount, currency), which an agent would otherwise need to infer.

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 must compensate — and it does: 'Pass `account_ids` as an array (1–50)' adds the cardinality constraint and plural per-account semantics that the bare schema (array of strings) does not convey. It stops short of explaining ID format or behavior for invalid/empty entries, a minor gap for a single-parameter tool.

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?

Opens with a specific verb+resource statement: 'Returns the latest available balance per account id (GET /accounts/:id/balance).' The resource is unambiguous and distinct from balance-adjacent siblings like openfinance_list_accounts or openfinance_list_transactions. Even without the title, an agent knows exactly what this tool does and what it does not do.

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?

Provides an explicit when-to-use-alternative rule: 'If a movement that just happened is not reflected yet, or the balance disagrees with the sum of openfinance_list_transactions, run openfinance_force_sync to pull fresh data and then re-read.' It also gives remediation for consent errors ('reconnecting the bank restores it'). The conditional routing is concrete and actionable, leaving nothing to inference.

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