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

Annotations already declare destructiveHint=true, but the description adds the concrete consequence: the old link stops working immediately for anyone holding it, and the new link grants read access to anyone who has it. It also discloses that a missing confirm yields only a preview rather than a change - rich, non-obvious behavioral context.

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?

Three tight sentences with the core action and its effects front-loaded, followed by the exclusion and the prerequisite. No filler or redundancy.

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, and the description covers the mutation effect, the irreversibility for the old link, the access implication of the new link, the voided-document exclusion, and the confirm/preview distinction. Nothing an agent needs to call this correctly is missing.

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 100%, so both parameters are already documented. The prose restates the confirm semantics rather than adding syntax or format detail beyond the schema, which is the baseline case for well-covered schemas.

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 - 'Replaces the public link of a document with a new one' - and immediately characterizes the effect on the old and new links. It does not name the obvious alternative (revoke_invoice_link) or clarify it against regenerate_client_portal_link, so sibling differentiation is left implicit.

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?

Provides an explicit exclusion ('Not for a voided document') and a hard prerequisite ('Needs confirm: true'), which tells the agent when not to call it and what is required to actually perform it. It stops short of naming the alternative tool for cases where replacement rather than revocation is wrong.

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