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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior beyond them: default reads a pre-aggregated rollup with minute resolution for 45 days and hourly up to 400 days, parent breakdown is computed on demand over raw spans (a real cost) and needs scoping, and truncation is surfaced via truncatedRows/truncationHint. It also documents the empty-bucket behavior for a series that stopped.

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?

Front-loads the purpose and the 'START HERE' routing before any detail, and organizes the rest into labeled sections (Parent breakdown, Params, Returns) that an agent can skim. It is on the long side for a read tool, and the Returns paragraph partly duplicates schema-described fields, but almost every clause carries usable 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?

There is no output schema, yet the description fully specifies the return shape (buckets[] with group, spanCount/okCount/errorCount/unsetCount, errorRate 0-100, throughputPerSecond, durations, quantileNanos, queryStats) plus truncation and empty-bucket semantics. Combined with resolution limits and drill-down guidance, nothing needed to call or interpret the tool is missing.

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 genuine meaning: it explains what groupBy actually does, and specifically that adding parent_operation splits an operation by its immediate caller with a concrete '8% overall vs 92% under one caller' example. The step units and defaults are largely repeated from the schema, keeping it short of a 5.

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?

Opens with a specific verb+resource+output contract: 'Aggregate spans into RED metrics: request count, error rate, throughput, and latency percentiles (p50/p90/p95/p99)'. It explicitly distinguishes itself from siblings spans/get_trace as the starting point, and from metric-style tools by naming the concrete outputs an agent will get.

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?

States explicit triggering questions ('where are errors / latency concentrated?', 'what changed between two windows?') and then names the alternative path: drill into raw spans via spans/get_trace once pointed at a specific (service, operation). It also gives a when-to-use caveat for the expensive parent breakdown ('keep it scoped: pass a tight from/to and a service/name filter').

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