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

Goes well past the annotations, which only say non-read-only/non-destructive/non-idempotent. It discloses two non-obvious behaviors: the version number advances rather than reverting (consistent with idempotentHint=false), and secrets are re-pinned from current values rather than restored. It also explains failure semantics ('refused rather than deploying something similar' with a reason), which is exactly the kind of context annotations cannot carry.

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?

Purpose is front-loaded, then the two caveats are clearly enumerated ('First... Second...') plus the validation-refusal clause. Slightly wordy framing ('Two things surprise people and you must not report either one wrongly'), but every sentence carries real information.

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 mutation tool with no output schema, the description covers the surprising semantics and the failure mode thoroughly. The only gap is that project_id and idempotency_key are undocumented anywhere, which an agent would need to infer.

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 0%, so the description must carry all parameter meaning. It does explain that 'to' takes a state_version from list_versions, but leaves the mapping from the parameter name 'to' implicit and says nothing about project_id or idempotency_key. Partial compensation for a 3-parameter, zero-coverage schema.

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 verb+resource ('Redeploy an earlier version of the project') and pins the identifier source to 'state_version from list_versions', which separates it cleanly from siblings like deploy, restart, and list_versions. An agent can identify the operation without opening the schema.

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 clear context for use (rolling back to a prior state identified via list_versions) and a refusal condition (stored version fails validation). It lacks an explicit 'prefer X instead when...' contrast against siblings such as deploy, but the triggering scenario is unambiguous.

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