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

With no annotations and no output schema, the description carries the full burden and does meaningful work: it names the returned aggregates, explains that sales use locked rates and that received_market_value is the value at arrival time, states period_start inclusive / period_end exclusive, and discloses the test-key filtering behavior. Gaps remain around authentication scope, aggregation limits, and the shape/units of the returned numbers, but the substantive behavior is disclosed.

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 content is dense but mis-ordered: a long comma-separated field list leads, while the actual operation and its period semantics trail behind it. Some material duplicates the schema (inclusive/exclusive boundaries are already stated on period_start and period_end), weakening the value per sentence.

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 6-parameter read tool with no annotations and no output schema, the field enumeration usefully substitutes for missing return documentation and the test-mode note covers a real edge case. However, nothing addresses authorization/permission scope, size limits on returned groups, currency defaulting, or error behavior — gaps an agent would likely hit.

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 67%, with timezone, period boundaries, and include_simulated already documented in the schema. The description adds value beyond it by explaining that occurred_at is bucketed in the given timezone and currency, and by naming the output container `groups` for group_by — semantics the schema's bare enum does not convey. It still says nothing about currency's default or conversion behavior, leaving one parameter thin.

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 opens with a dense enumeration of returned fields rather than a verb+resource statement, so the purpose (aggregate totals over occurred_at for a period) must be inferred from the clause 'with payment counts, over occurred_at in the given timezone and currency' plus the title. It never distinguishes itself from the sibling list_records, which is exactly the ambiguity an agent facing both tools needs resolved.

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?

Usage is only implied: the boundary semantics of the period and 'group_by returns the same totals per month, asset, chain, type or address' hint at when the tool applies, and 'With a test key, simulated rows count only with include_simulated=true' is a genuine usage rule. But there is no explicit when-to-use / when-not-to-use guidance and no named alternative (e.g., list_records for row-level data).

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