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

Annotations already mark this as destructiveHint=true and readOnlyHint=false, so the mutation is disclosed. The description adds useful behavioral context: the capability stops resolving immediately and the returned URL is a bearer capability that should only be revealed or opened on user request. No contradiction with 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 short and front-loaded with the main behavioral outcome, followed by the HTTP method and auth instructions. The final two sentences about creating and opening links are somewhat tangential to the revoke operation, but they add useful bearer-capability safety context without becoming bloated.

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 simple destructive DELETE operation with no output schema, the description provides the key elements: the effect, the endpoint, the multi-space auth prerequisite, and a security caution. It does not describe response behavior or error cases, but those are less critical given the simplicity of the operation.

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 50%: targetSpaceId has a description, but id does not. The description clarifies id through the DELETE path and reinforces targetSpaceId usage, but it does not explain where id comes from or its expected format. This is adequate but incomplete.

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, specific effect: 'The capability stops resolving immediately.' Combined with the title 'Revoke an embed link' and the DELETE endpoint, it clearly identifies the action and resource. It is easily distinguishable from the sibling tools embed_links_create and embed_links_list.

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 gives clear context for multi-space accounts: call auth_verify, ask the user which space to use, and pass targetSpaceId. It also adds an explicit caution about creating and revealing embed links only when the user asks. However, it does not explicitly state when to prefer this tool over an alternative or when not to revoke.

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