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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context beyond that — it mutates the owning agent by attaching a regression scenario, and it will refuse certain failure categories outright. It stops short of covering idempotency (what if the scenario already exists) or whether the optimization launch needs approval.

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: the action first, the workflow routing second, the guardrail third. No filler, and the most decision-relevant information is front-loaded.

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 mutating tool with no output schema, the description covers the side effect (scenario added to the owning agent), the optional chained action, and the refusal path. It could say more about what the caller receives back or how to follow up on the launched optimization, but nothing critical 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 the baseline is 3. The description adds genuine meaning by tying 'optionally launch an optimization targeting that failure' to the autoLaunch parameter, clarifying its downstream effect rather than just restating it.

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 compound action: convert a failed run into a regression scenario on its owning agent, with an optional optimization launch. It is clearly distinguishable from add_regression_scenarios (manual scenario creation) and trigger_optimization (standalone optimization), since it scopes the action to a diagnosed failure.

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?

Explicitly names the entry-point sibling (get_worst_run) and the workflow (pipe get_worst_run → fix_worst_run), plus an explicit exclusion: runs whose failure is not prompt-fixable (tool_config, model_limitation). Both when-to-use and when-not-to-use are stated.

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