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

Annotations already establish that this is a safe, idempotent read, and the description goes well beyond them by disclosing two result-changing behaviors: datasets with a voided/deleted flag silently exclude those rows by default, and line-item datasets like requisition are NOT scoped by their parent order's status. Those are exactly the non-obvious traps that would otherwise produce quietly wrong revenue numbers, and it even points to the Scope line in describeQueryableFields.

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 first half is well front-loaded and dense with value, but the 31-item dataset list consumes roughly a third of the text and simply repeats the `entity` property description verbatim from the schema — space that earns nothing. Removing it would shorten the description substantially without losing information.

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 seven parameters all documented, full schema coverage, and read-only annotations, the description covers the pieces an agent actually needs: valid metrics, how to find field names, and the scoping caveats that affect correctness. Return-shape detail is the only soft spot, and for an aggregate result (group keys plus metric value) its absence is low-risk.

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 100%, so the baseline is 3, but the description adds meaning on top: groupBy can take one or more fields (omit for a single total), filter uses the same RSQL syntax as query, and field names must come from describeQueryableFields. The worked example with real field names (localPrice, customerOrganisationName) makes the metric/field/groupBy interaction concrete rather than abstract.

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 opening sentence names a specific verb (aggregate) plus the exact metric set (sum/avg/count/min/max), optional grouping, and optional RSQL filter, so the operation is fully pinned down. It is clearly separable from the `query` sibling by being an aggregation rather than a row-returning read.

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?

It supplies concrete use cases ('highest-value customers', 'revenue by process') plus a real invocation shape (metric=sum, field=localPrice, groupBy=[customerOrganisationName], filter="state==ORDER"), which tells the agent when this tool is the right pick. What is missing is an explicit negative case — e.g. 'use query instead when you need individual rows rather than totals' — so the boundary with `query` is only implied.

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