Account balance

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

Annotations already declare readOnlyHint=true, so the description doesn't need to restate that. It adds useful behavioral context: the doc suffix convention for previous years and the supported filters. No contradiction with annotations, and openWorldHint is not explained but not contradicted.

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?

Three short, information-dense sentences. The first states purpose, the second explains the previous-year suffix, the third lists supported features. No redundancy or fluff.

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?

Given the detailed schema (100% coverage) and read-only annotation, the description covers all essential usage aspects: what it returns, how to access previous years, and available filters. It doesn't describe return format, but with no output schema and openWorldHint=true, that's acceptable. Could add an example or mention limitations, but the description is sufficient.

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 100%, so baseline is 3. The description adds extra semantic value by explaining the doc suffix convention ("_p1"/"_p2" for previous years), which is not in the schema, and by summarizing the period, frequency, and filter capabilities that map to parameter usage.

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 the tool returns an accounting balance figure, specifying the scope (account, group, or balance class). It distinguishes from siblings like banana_budget or banana_vat_balance by the generic balance focus and mention of groups/classes.

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 some guidance (using _p1/_p2 suffixes for previous years, supporting period/frequency/filter) but does not explicitly name alternatives or exclusions. It provides context but not a full when-to-use vs when-not-to-use comparison with sibling tools.

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