Summarise sales

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: cancelled receipts are excluded, the 31-day data availability limit, and the safety cap on receipts read (max_receipts). It also clarifies that 'top' is ignored when grouping by day, which is a behavioral nuance not obvious from the schema. No contradiction with annotations.

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 three sentences with zero waste. It front-loads the core purpose, then lists the metrics and breakdown dimensions, then adds the two critical constraints (cancelled receipts excluded, 31-day limit). Every sentence earns its place and the structure is easy to scan.

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?

For a read-only aggregation tool with 100% schema coverage and no output schema, the description covers the essential context: what it aggregates, what metrics it returns, what grouping options exist, and the data availability limitation. The only minor gap is that it doesn't describe the exact output shape, but since there's no output schema and the description lists the metrics, this is acceptable. The 31-day limitation is a valuable completeness addition.

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 the schema already documents all 6 parameters. The description adds some context around the 'top' parameter behavior (ignored when grouping by day) and the max_receipts safety cap, but it doesn't add significant meaning beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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 aggregates receipts over a date range into totals and a breakdown, with a specific verb ('Aggregate') and resource ('receipts'). It distinguishes itself from raw receipt listing by explicitly saying 'without the model having to page through raw receipts', and lists the exact metrics and grouping dimensions. This differentiates it from siblings like loyverse_list_receipts and loyverse_get_receipt.

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 implies when to use this tool: when the model needs sales totals/breakdowns rather than raw receipts, explicitly contrasting with paging through raw receipts. It also provides a critical usage constraint: without the Unlimited Sales History add-on, only the last 31 days are available. However, it doesn't explicitly name alternative tools or state when not to use it, so it falls just short of a 5.

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