Aggregate transactions

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

Beyond the readOnlyHint annotation, the description discloses highly useful behavioral details: it operates server-side, returns per-group counts, distinguishes totalAmountMinor (magnitude) from netAmountMinor (signed credits minus debits), uses minor units, and defaults to the last 3 months if no period filter is provided. This significantly aids the agent in interpreting results and making assumptions.

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?

The description is compact and front-loaded, with the core purpose in the first sentence. Every sentence adds information: operation, grouping, return values, unit convention, default period, and usage examples. No filler or redundancy.

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?

Despite having no output schema, the description covers the key return fields (counts, totalAmountMinor, netAmountMinor), the default period, and gives real-world usage examples. With 20 parameters, the description cannot enumerate all filters, but the schema already does so. The description provides sufficient context for an agent to confidently use the tool without surprises.

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 high (85%), so the baseline is 3. The description adds value by clarifying the groupBy semantics (enumerating keys and the constraint 'at most one of day/month/year') and explaining the meaning of totalAmountMinor vs netAmountMinor, which helps the agent understand output-related parameters like sortBy. It does not duplicate the schema's parameter descriptions.

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's function: 'Group and total transactions server-side' with specific grouping keys (merchant, category, code, day/month/year). It distinguishes itself from sibling tools by positioning as 'the go-to tool' for spend aggregation questions like 'top categories by spend this quarter' or 'monthly spend at Tesco', which separates it from search_transactions and other stats tools.

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 provides clear context for when to use this tool (aggregation/spend analysis questions) and gives concrete example queries. However, it stops short of explicitly naming alternatives or stating when NOT to use it, so it doesn't fully meet the 5-level standard seen in the get_calls example.

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