Aggregates over fixed time windows

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description contributes the non-obvious trait that buckets are anchored to physical elapsed time rather than calendar boundaries, which materially affects interpretation. It does not discuss how gaps, partial buckets at range edges, or empty windows are handled, which is the remaining behavioral unknown for a time-bucketing tool.

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?

Two sentences, zero filler: the first defines the operation and its scope, the second handles disambiguation. The examples do real work rather than padding, and the alternative is placed after the definition where it is most useful.

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?

There is no output schema, so the description is the only place the return shape could be characterized, and it never says what a result looks like (buckets with timestamps, units, empty periods). For a four-required-parameter aggregation tool with an open-world enum, this leaves a meaningful gap for correct interpretation of results.

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 75%, with unit examples already inline for startTime/endTime and windowMinutes, so the schema carries most of the load. The description reinforces the windowMinutes meaning through the "60 minutes" example but adds nothing about the dataType enum or how it interacts with bucket size. Baseline 3 is appropriate.

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?

"Aggregated values over physical-time windows" states a specific operation (aggregation) plus the axis of aggregation (physical-time windows), and the two parenthetical examples make the concept concrete. The final sentence explicitly routes away from get_daily_rollup, so an agent can distinguish the two without opening either schema.

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 names one alternative (get_daily_rollup) and the condition that selects it (per-day vs sub-day windows), which is genuinely actionable routing. It gives no guidance for the other paths an agent might take — e.g. raw points via get_data_points versus aggregated windows — so the exclusion set is incomplete.

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