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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the data is pushed/synced backend telemetry, `quantity` must never be treated as currency, and external_customer_id breakdown only applies 'when the pushed rows carry one.' This is useful, though it does not cover response pagination or full return shape.

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: the first sentence states the tool's core purpose and scope, followed by a necessary money-handling warning, a breakdown note, and an API mirror reference. Every sentence contributes valuable information without 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?

Given seven optional parameters, no output schema, and many sibling tools, the description does a strong job covering purpose, raw/cost distinction, currency caveat, and optional breakdown. It still leaves a small gap around what the query response contains beyond `quantity` and any pagination behavior, but the description plus schema and annotations are sufficient for correct tool selection and basic invocation.

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 71%, so most parameters are already documented. The description supplements this by explaining the semantic framing ('raw count, no currency') and the external_customer_id breakdown condition, which helps for breakdown_by. However, it does not add meaningful guidance for filter_external_customer_id or clarify the meaning of the two undocumented parameters beyond their inferable names.

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 names a specific verb ('Query') and resource ('time-bucketed usage telemetry'), and narrows the scope to data 'this account's own backend has pushed or synced in.' It also distinguishes itself from related unit-economics tools by saying the data is 'inspected directly rather than through a pre-defined ratio' and warns that `quantity` is a raw count, not money.

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 clearly positions this tool as the raw-data counterpart to cost or ratio metrics, even pointing to list_unit_metrics/query_unit_costs as related alternatives. It does not explicitly enumerate when to prefer query_events or query_costs, but the 'raw count with no currency' warning and 'rather than through a pre-defined ratio' phrase provide usable routing context.

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