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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=true; the description reinforces this with 'create or recover' (idempotency) and adds non-obvious context that anyone with the URL can view the draft and that availability is checked at open time. It stops short of describing return payload or link persistence, but the annotation coverage lowers the bar.

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?

Four sentences, front-loaded with the core operation followed by identifier sourcing, locale default, and safety caveats. Dense but each sentence carries a distinct instruction; slightly long for the operation but not wasteful.

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?

No output schema exists, so the description would ideally hint at what a caller receives (a URL). It comes close via 'create or recover a public live preview link' and notes the availability-check behavior, but does not state the returned link shape. Otherwise complete for a 4-param tool with an open-world annotation.

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 only 50% – route and locale are documented in the schema, but siteId and projectId have no schema descriptions. The description compensates by naming where each ID comes from (list_projects, list_sites) and giving route/locale usage rules, adding genuine meaning beyond the structured fields.

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 and resource: 'Create or recover a public live preview link to a site page without publishing.' The 'without publishing' clause cleanly distinguishes it from publish_site and its inverse revoke_shared_preview in the sibling set.

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 source tools for identifiers (list_projects, list_sites), tells when to omit locale, and adds a clear behavioral rule: 'Share only when requested; if the preview workspace is missing, report that state without editing or publishing the site.' This covers when-to-use and the fallback case.

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