Compute Account Balances by Dimension

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context the annotations cannot: the return grain (one row per dimension plus a total), the inclusion of API INITIAL opening balances, and a cross-tool reconciliation guarantee against compute_account_balance.

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?

Two sentences, no filler, with the core purpose and the example front-loaded and the return/reconciliation guarantee second. Every clause carries information an agent cannot get from the schema.

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, the description correctly carries the return shape (one row per dimension plus total) and a consistency guarantee, which is what an agent most needs. It leaves open how the default date range behaves when date_from/date_to are omitted, a minor gap for a read-only reporting tool.

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 100%, so account_id, date_from, date_to and fresh are already documented in the schema. The description adds only indirect meaning (the mention of API initial balances hints at the cached API data that 'fresh' refreshes) but gives no date-range semantics of its own. Baseline 3 applies.

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?

States a specific verb and resource ('break an account's balance down per dimension') and grounds it with a concrete example (1020 Arvelduskontod: LHV, Wise, Lightyear). It also distinguishes itself from the closely related compute_account_balance by declaring that its total matches that tool's output.

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 per-dimension breakdown framing makes the selection context clear versus compute_account_balance, which the description names and reconciles against. It stops short of an explicit 'use X when you need only the total, use this when you need the breakdown' rule, and says nothing about list_account_dimensions.

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