Generate comprehensive diagnostics bundle across all LCU telemetry streams

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

'Safe and read-only' restates the annotations (readOnlyHint/destructiveHint), so that sentence earns little. However the description adds genuine behavioral value beyond annotations by disclosing the return contract ('Markdown report by default, or structured JSON when specified'), which matters because there is no output schema, and by explaining the includeLogTail fallback intent.

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 purpose sentence followed by usage routing and return-format detail, with little waste. The 'Safe and read-only' clause is redundant against the annotations and is the one sentence that does not fully earn its place.

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 composite read-only aggregator with no output schema and six optional parameters, the description covers what it produces, when to prefer it, the alternative for narrower queries, and the output format contract. Nothing an agent needs to invoke it correctly 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 description coverage is 100%, so every parameter is already documented in the schema; the description implies the format, sources, and log-tail concepts but adds no syntax or defaults beyond them. Baseline 3 applies when the schema does the heavy lifting.

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 the specific verb 'Generate' and a concrete composite resource ('all-in-one diagnostic bundle') plus the three components it combines (connectivity status, correlated telemetry timelines, disk log tails). An agent can distinguish this aggregate tool from the many single-stream siblings without opening the 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 when-to-use ('single-call comprehensive health check or bug report export when diagnosing complex client issues') and an explicit when-not with the named alternative ('For interactive querying of specific streams, use lol_forensics_correlate or subsystem-specific tools'). Routing is unambiguous.

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