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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description aligns with and enriches this: it warns that database data is NOT rolled back, describes the concurrent-job refusal behavior (naming the running job), and the RationalBloks update refusal. All of this goes beyond the annotations and matches them — no contradiction.

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 earns its place: the core action and warning are front-loaded, followed by workflow, use case, and concurrency details. It is somewhat long, but the length is justified by the destructive nature and the multiple behavioral constraints that need disclosure.

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?

With no output schema, the description carries the burden of explaining behavior, and it does so thoroughly: what is reverted, what is not, the redeployment follow-up, and concurrency refusals. It doesn't explicitly describe the return value, but for a mutation tool that hands off to get_job_status, this is a minor gap.

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 all three parameters are documented in the schema. The description adds marginal value by confirming 'version' is a commit SHA and reinforcing the get_version_history lookup, but does not introduce meaning the schema lacks. 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?

States a specific verb (rollback), resource (project), and target (previous version) in the opening sentence. The warning clarifies the exact scope — reverts schema AND code — which distinguishes this from pure code or pure data rollbacks and from its sibling rollback_graph_project (graph vs. non-graph projects).

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?

Explicitly names the preparatory tool (get_version_history to find the commit SHA) and the follow-up tool (get_job_status to monitor redeployment). States the use case ('when a schema change breaks deployment') and documents refusal conditions with actionable recovery ('call it again in a few minutes').

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