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

Annotations are minimal, so the description carries the transparency burden. It fully discloses that checks are REAL requests with side effects, that they count as invocations, that the same 10-second deadline applies, that slow routes read as failures, that rollback requires tier 4, and that repeated attempts are rate-limited. This is far beyond the structured annotations.

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 long but every sentence carries a distinct, useful fact: transaction semantics, rollback behavior, output contents, tier constraints, onFailure behavior, side-effect warnings, deadline, and rate limiting. It is front-loaded with the one-sentence summary and then expands into necessary operational detail without repetition.

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 complex publish-verify-rollback tool with no output schema, the description covers safety, failure outcomes, logging details, tier gating, side effects, timeouts, and anti-abuse limits. An agent has enough context to decide whether to call it and what to expect on both success and failure paths.

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 description coverage is only 17%, so the description must compensate. It adds strong meaning for verify with examples ('my page answers', 'my JSON route answers 200', 'the missing route really answers 404') and clarifies the expectStatus default of 200 even though the schema does not. However, html, zipBase64, and managementToken remain unexplained, leaving a partial gap.

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 concrete verb and resource: 'Publish new content AND check it works, in one transaction.' It clearly distinguishes this from siblings like dropyour_publish, dropyour_replace, and dropyour_rollback by emphasizing the verify-and-rollback transaction, and even notes that a release with nothing to verify is just dropyour_replace.

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 gives explicit when-to-use guidance: use the rollback default as 'the safe way to ship,' and use onFailure='keep' when you want to inspect the broken state or when no version history exists. It also explains when the tool refuses upfront (tier 1-3) and warns against repeated publish/fail/republish loops, so an agent knows both the right conditions and the wrong conditions.

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