Roll back deploy

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

Beyond the destructiveHint annotation, the description adds critical behavioral context: 'Triggering a rollback with this endpoint does not disable autodeploys' and 'an autodeploy might restore changes you had intentionally rolled back.' It also discloses the required deployId condition, which is not apparent from annotations alone.

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 concise (four sentences), front-loaded with the core purpose, and includes only high-value details: endpoint path, autodeploy caveat, and candidate selection guidance. No redundant or irrelevant content.

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 destructive rollback tool with no output schema, the description provides complete operational context: what it does, how to use it correctly, what it doesn't do (disable autodeploys), and how to manage the side effect. It sufficiently covers parameters, behavior, and alternatives.

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% with basic descriptions, but the description enriches the semantics significantly: deployId must be a previously successful deploy of the same service and can be listed via render_list_deploys with status 'live'. This goes well beyond the schema's simple 'The ID of the deploy to roll back to'.

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 clearly states the tool's purpose: 'Roll back deploy' and 'Trigger a rollback to a previous deploy of the specified service.' It distinguishes this from sibling tools like render_create_deploy and render_cancel_deploy by specifying the rollback action and the target resource.

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?

Provides explicit usage guidance: 'deployId must be a previously successful deploy of this same service' and directs the user to render_list_deploys to find candidates with status 'live'. It also warns about autodeploys and names an alternative (Update service endpoint or Dashboard) for toggling autodeploys.

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