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

Annotations carry only four boolean hints, so the description carries the burden — and it delivers. It discloses that recovery is partial (selected resource only, applicable instance_down/database_overload failures only), stateful across steps (parked/cooling_down/healthy progression), and permanent-failure behavior (instance_kill removes the resource irreversibly). It also discloses session-dependent behavior (fresh sessions need explicit simulationId or get NO_ACTIVE_SIMULATION) and the 30-minute anonymous TTL. No contradiction with annotations.

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?

The description is long but well-organized: scope first, then preconditions, then behavior and limits, then next-step guidance, then session handling. Every sentence except the final authentication pitch carries operational weight; the auth sentence is borderline promotional but does convey anonymous-mode limitations.

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?

Comprehensive for a stateful recovery tool: preconditions, parameter provenance, partial-effect behavior, the permanent-failure exclusion, follow-up workflow, session semantics, and the NO_ACTIVE_SIMULATION error case are all covered. With an output schema present, the recoveryProgress return details do not need to be spelled out further.

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% and each parameter already has a solid description, so baseline is 3. The description adds value by clarifying that resourceId and resourceName are alternative selectors ('provide resourceId or resourceName') and by telling the agent exactly where to source them from (create/step/metrics outputs). This exceeds the schema's per-field descriptions.

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 first sentence states a specific verb (recover), a precise scope (one reversible failed resource), and the environment (temporary anonymous demo simulation). It clearly differentiates from siblings: the opposite operation is simulation.inject_failure, and the explicit instance_kill exclusion further pins down what this tool does and does not do.

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?

Gives an explicit precondition and ordering ('Lower traffic to a serviceable level first'), tells the agent where to obtain parameter values (resourceId/resourceName from simulation.create, simulation.step, or simulation.metrics), and routes the follow-up action ('The likely next tool is simulation.step'). It also states a when-not case: instance_kill cannot be recovered.

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