get_exercise_plan

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

With no annotations provided, the description carries the full burden and does meaningful work: it flags that routes marked mutating change data, that these hit production and count as ordinary traffic, and that the target defaults to the current git HEAD. It stops short of stating whether the call itself is read-only or what the plan's shape/size is.

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?

Every sentence carries information, but the phrasing is dense and indirect — the lead clause delays the actual subject, and the mutating/reporting caveats are stacked mid-paragraph. It reads as stream-of-consciousness rather than front-loaded structure.

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?

No output schema and no annotations, yet the description covers return content categories, the `needed` vs optional distinction, side-effect risk, and default resolution — enough for an agent to call it correctly. Only the precedence among the four selectors and the response format remain unstated.

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 3 is the baseline; the description adds value beyond the schema by disclosing the default behavior ('Defaults to the current git HEAD'), which explains what happens when none of the four optional selectors is supplied. It does not clarify how commit/latest/version/deployment_id interact or take precedence.

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?

The description names the resource concretely — an exercise plan enumerating active routes short of their runs, routes changed by this release that haven't run, and critical flows — plus the `needed` flag. The opening clause ('What stands between a release and clearance') is indirect, but the enumeration makes the output identifiable and differentiates it from verification-status siblings like get_verification.

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?

It implies the workflow (run routes, then 'report what you ran with report_with') and gives a safety rule for mutating routes, but never says explicitly when to call this versus get_verification or wait_for_verification, nor any prerequisites. It also references a tool (report_with) that is not among the listed siblings, leaving the chaining ambiguous.

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