Restore a prior deployment

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

It discloses key behaviors beyond the annotations: it mints a NEW deployment rather than mutating the old one, URL/settings are unchanged, restoring the current deployment is a no-op, and below Pro it returns a 403 with upgrade_url. The return value (updated parent drop with bumped revision) is also specified, providing a complete behavioral picture.

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 well-organized and front-loaded: it opens with the core action, then explains the mechanism, key caveats, usage preference, requirements, and return value. Despite a moderate length, every sentence contributes meaningful information without repetition or fluff.

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?

Given the tool's complexity (version-history rollback, Pro gating, no-op behavior, and reliance on other tools for input resolution), the description covers everything needed for correct invocation: purpose, exact behavior, prerequisites, error handling, and return information. The presence of an output schema further reduces the need to describe return values in detail.

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?

The input schema already provides detailed descriptions for both parameters (100% coverage), so the baseline is 3. The description adds extra value by tying deployment_id to dropthis_list_deployments, stressing that drop_id must be id-only and referencing dropthis_resolve for URL/slug resolution, which enriches the semantic understanding beyond the 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?

The description clearly states the tool's function: rolling a drop back to a prior deployment's content. It distinguishes itself from siblings by explicitly naming the alternative (reading an old version with dropthis_get_content and re-publishing) and positioning itself as the first-class rollback path, making its unique purpose unambiguous.

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?

The description provides explicit usage guidance: use this for version-history rollback, prefer it over the manual alternative, and note the prerequisites (Pro plan, drop_id must be id-only, deployment_id from dropthis_list_deployments). It also mentions the error below Pro, which signals when the tool cannot be used.

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