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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description rightly spends its budget elsewhere: it discloses the two distinct return shapes (single worst run vs one entry per agent) and the payload contents (canonical accepted claim plus exact occurrence evidence). It does not mention result caps or pagination for the fleet-wide mode, which is the remaining gap.

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?

Three tight sentences with zero filler; the core purpose and routing cue are front-loaded and the two parameter-dependent behaviors are contrasted compactly in the middle.

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?

With no output schema, the description carries the burden of describing returns and does so (canonical accepted claim, occurrence evidence, per-agent entries). The defaults and limits for windowDays and any cap on fleet-wide results are left to the schema, which is acceptable, but the per-agent result cardinality could be more explicit.

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%, and the agentId semantics the description restates ('returns the single worst run for that agent' / 'worst-per-agent across the fleet') are already present in the schema text. The description adds no syntax, format, or defaults beyond what the schema documents, so the baseline 3 applies.

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 ('Return the worst recent run(s)') and immediately frames the scope of ambiguity with the agentId branch. It is easily distinguished from siblings like get_run, list_runs, and fix_worst_run because it names the aggregate concept ('worst') rather than a plain retrieval or a mutation.

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?

Positions itself as 'the landing call for what's broken right now', which is a clear use cue, and the with/without agentId branches tell the agent which mode to pick. It does not explicitly name alternatives or when-not-to-use cases (e.g., reach for fix_worst_run once you have the result), so it stops short of a 5.

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