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

Annotations already declare read-only/idempotent/open-world, so the safety profile is covered; the description goes well beyond that by disclosing return shape ('min/avg/max/latest summaries rather than raw series'), a freshness limitation ('non-websocket telemetry can lag by up to ~10 minutes'), and the mitigating check ('latest_sample_time'). It also pre-empts the misleading conclusion an agent might otherwise draw from stale samples.

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 opening clause is front-loaded and the per-target bullets are parallel and skimmable, with every bullet carrying a return-content list plus a use case. It is on the long side and the per-target metric enumerations are dense, but no sentence is pure filler.

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, and the description compensates by spelling out what each target returns, the aggregation form (min/avg/max/latest), and the caveat that results may lag. An agent has everything needed to pick a target, satisfy its prerequisites, and interpret the result.

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 the required-parameter combinations per target ('target=instance (needs environment + container, plus instance when there are several)'; 'target=server (needs server)'; 'target=load_balancer (needs environment)') that the flat schema does not encode. This is real added meaning, though it does not explain range_start/range_end semantics beyond what the schema states.

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?

States a specific verb and resource ('Summarized resource telemetry from Cycle, with anomaly flags') and then decomposes the tool's scope by target value, so an agent knows exactly which slice of telemetry each mode returns. It names the sibling tools it is not (query_metrics for history, capture_stream for live data), making it clearly distinguishable from them.

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?

Gives explicit when-to-use guidance per target: 'Use for one hot or crashing container', 'Use for server out of resources / disk suspicions', 'Use for 502s and unreachable-URL problems'. It also states when to prefer alternatives ('Latest snapshot only; for history use query_metrics preset=lb_controller_traffic' and 'use capture_stream for what is happening right now'), which is exactly the routing information an agent needs.

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