Retry a failed run

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

Beyond annotations, the description discloses important side effects: a new package build is triggered, AWS Batch may be started, a new run becomes the scenario's latest run, and the old errored run is preserved as history. It also flags a non-obvious response quirk: the response describes the old run while the new run ID must be read from get_scenario's run_id. This is exactly the kind of context annotations cannot provide.

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 front-loaded with the core action, then immediately covers authorization, side effects, response semantics, and state validation. Each sentence carries useful information, and the surprising response behavior is called out clearly without excess.

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?

Even though an output schema exists, the description adds necessary operational context: auth requirements, valid state, side effects on scenario history, and how to obtain the new run ID. Nothing an agent needs in order to invoke this tool correctly appears to be 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?

There is only one parameter, and schema coverage is 100%, so the schema already explains run_id as 'The run ID to retry.' The description reinforces that only errored runs are valid targets, but it adds little parameter-level syntax or format beyond what the schema provides. Baseline 3 is appropriate.

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 opens with a specific verb and resource: 'Retry a failed simulation run.' It goes further to distinguish the operation from a plain re-run by stating it starts a fresh package build as a NEW run while preserving the errored run as history. This clearly separates it from siblings like start_simulation and get_run.

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 states explicit preconditions: a launch-level agent key is required, and a read or draft key returns 403 AGENT_LEVEL_INSUFFICIENT. It also says the tool is only valid when status is 'error' and returns 409 otherwise, which is exactly the when-to-use guidance an agent needs.

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