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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the 'Read-only' sentence largely restates structured data rather than adding value. The description does add semantic context about the Money Graph spend lenses and income/net burn, but says nothing about permissions, data freshness, or scope caveats.

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?

A single front-loaded sentence that wastes no words and packs the core semantics. Slightly dense due to the parenthetical lens list, but well structured.

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?

An output schema exists, so return-value explanation is not required, and the grouping concept is covered. However, the bucket-vs-monthly ambiguity and missing date-range behavior leave the definition under-complete for a 5-parameter tool with nested objects.

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 only 20%, so the description must compensate, and it only partially does ('date window', 'optionally per month'). It never disambiguates the overlapping bucket enum (MONTH/DAY) versus the monthly boolean, nor explains date formats or defaults, leaving a genuine ambiguity for the agent.

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 ('Total expenses ... grouped into the Money Graph spend lenses') and enumerates the lens categories, plus mentions income and net burn. An agent can distinguish it from siblings like get_income_by_category or spend_get_spend_by_payee, though it doesn't explicitly name the alternative.

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?

There is no explicit guidance on when to choose this over get_income_by_category, spend_get_spend_by_payee, or accounting_get_profit_and_loss. The phrase 'optionally per month' hints at a use case but never states prerequisites, date-window defaults, or how it relates to the similarly scoped sibling rollups.

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