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

Annotations already flag destructiveHint=true, but the description adds critical behavioral context: it changes production renders, there is no undo beyond rolling forward, restoreDraft auto-snapshots the existing draft to preserve unsaved work, and missing API key leads to dashboard setup instructions. It also discloses the 409 VERSION_CONFLICT rejection, going beyond the annotations without contradicting them.

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 a single dense paragraph but every sentence adds pragmatic value—purpose, usage alternatives, destructive warnings, auth requirements, and concurrency behavior. It is not needlessly verbose, but it does pack many clauses into one block; could be slightly better structured with bullets, yet it remains efficient and front-loaded.

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 4 parameters, no output schema, and rich annotations, the description covers all essential dimensions: what it does, when to use it, safety/destructive impact, parameter nuances, and required permissions. Nothing important is missing, and the lack of an output schema is compensated by the detailed behavioral and param guidance.

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 the schema is already detailed. The description adds extra value by explaining that templateId accepts UUID or slug and that expectedPublishedVersion is an 'optimistic fence' for concurrency control, plus the nuance that restoreDraft only snapshots when not byte-identical. This goes beyond the schema descriptions without repeating them, though the schema already does much of the heavy lifting.

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: 'Revert a template after a bad release: repoints published_version at the version you name, so every subsequent render immediately serves that snapshot again.' This clearly distinguishes it from the sibling publish_template by explaining the unique reversion mechanics and the expectedPublishedVersion parameter, making the purpose unmistakable.

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 guidance to prefer this tool over publish_template's version argument when reverting, and explains why: only this tool offers expectedPublishedVersion as an optimistic fence and can restore the working draft. It also clarifies when restoreDraft should be used (true/false behavior) and notes the auth requirement, covering when-to-use and exclusions.

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