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

Annotations already declare readOnlyHint/idempotent/destructive=false, so safety is covered; the description goes further by disclosing staleness (non-websocket telemetry can lag ~10 minutes), instructing to check latest_sample_time, distinguishing latest-snapshot-only from historical data, and noting it returns min/avg/max/latest summaries rather than raw series.

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-loaded with the summary statement, then a scannable bullet per target, then global caveats. Dense but every sentence carries routing or freshness information; the enumerated metric lists make it longer than strictly necessary.

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?

For a 9-parameter, no-output-schema tool, it covers target selection, per-target requirements, staleness, and return granularity. Remaining gaps are minor, e.g. it does not restate the conversation_id chaining protocol, though that is documented in the schema.

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%, giving a baseline of 3, but the description adds cross-parameter conditional logic the schema cannot express: which fields are required per target (instance needs environment + container, plus instance when several exist; server needs server; load_balancer needs environment). That materially improves correct invocation.

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 (summarize) and resource (resource telemetry from Cycle) and immediately enumerates the three target modes with the exact metrics each returns. An agent can distinguish this from query_metrics and capture_stream 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?

Explicit routing 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 names alternatives and their trigger conditions — query_metrics preset=lb_controller_traffic for history and capture_stream for real-time.

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