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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so safety is covered; the description then adds substantial behavior beyond that: voided rows excluded, expected rows gated behind include_expected, payroll rows hidden for connections without payroll visibility (and those companies named), internal money movement excluded unless include_transfers is true, and currencies never summed together. This is exactly the kind of non-obvious scoping an agent needs to interpret totals.

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?

Front-loads the purpose before the behavioral clauses, and each clause carries distinct information (grouping, measures, filters, exclusions). It is dense and long, but there is little filler; the length is justified by the tool's semantics.

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 10 parameters, no required fields, and no output schema, the description does the heavy lifting on grouping, measures, and exclusion rules. The one residual gap is the exact shape of the returned groups (keys plus measure values), which the agent must infer, but the grouping/measure framing makes this largely predictable.

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 60%, and the description compensates well: it enumerates the group_by and measures options, defines week as starting Monday, clarifies that currencies are never added together, and explains what include_expected and include_transfers actually change. It adds real semantics beyond the enum values, though limit, order, and from/to handling remain mostly schema-only.

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 precise verb+resource+scope: it aggregates ('adds up') transactions matching a search, grouped by up to two dimensions. It explicitly differentiates from the sibling search_transactions by noting that a group can be opened with search_transactions to see its rows, so the agent can tell aggregation from row retrieval without opening either schema.

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?

Clearly positions the tool against search_transactions (this returns grouped totals; that returns rows) and states the filter set is identical. It does not spell out an explicit 'use this instead of X when you want Y' exclusion, but the routing context is clear enough to choose correctly.

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