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

Goes well beyond the annotations by disclosing the blast radius ('page content is preserved' — only the link is destroyed) and the authorization model. It also confirms the idempotent behavior announced in annotations ('Repeating the request succeeds'), so an agent knows retries are safe and that the destructiveHint is scoped to the link only.

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 short sentences, front-loaded with the action, then permissions, then idempotency/scope, then a safety guardrail. No filler and no repetition of schema or annotation content.

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?

Covers purpose, auth, idempotency and side effects for a one-parameter tool, which is nearly everything an agent needs. With no output schema present, the description never states what a successful response returns, which is the only remaining 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 description coverage is 0%, so the description carries the burden, and it does identify the provenance of sharedPreviewId ('the id returned by create_shared_preview'). It does not restate the UUID format or validate the value, but the critical question — where to get the id — is answered.

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 ('Disable') and resource ('a public shared preview link'), and ties the tool to its sibling create_shared_preview as the source of the id. An agent can immediately distinguish this from creation/listing siblings without opening the schema.

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 who may call it (creator with current project access, or a workspace admin) and adds a scoping instruction: 'Revoke only the link the user requested.' It does not enumerate when *not* to use it or name an alternative, but the usage context is clear and actionable.

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