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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the description only needs to add nuance. It adds meaningful context: 'refresh' does not extend expiry, does not grant approval, and requires the original guest/integration or verified owner. 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?

Three sentences front-load the action and then pack in the key exclusions and preconditions. No filler or repetition of schema details.

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 small read-only, idempotent tool with annotations present, the description covers the operational intent, preconditions, and negative boundaries. It doesn't need to restate return values since none are promised beyond 'both saved images,' and no output schema exists. Minor gap: no explicit mention of what the returned images/links contain, but the essentials are present.

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 schema describes guestToken fully but leaves designToken undocumented (50% coverage). The tool description does not compensate for designToken's missing semantics; it only references 'the same immutable design' in passing. With half the parameters carrying no description in either schema or description, this is a clear gap.

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 specific verb+resource: 'refresh expired front/back proof links and return both saved images.' It explicitly distinguishes itself from approve_design_proof and revise_business_card_design by stating what it never does ('never rerenders, extends design expiry, or grants approval'). Clear scope, no tautology.

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 states the precondition ('Requires the original guest/integration or verified owner') and gives a clear exclusion ('Missing or expired design state requires a new design and review'). It also spells out the boundaries of the operation, so an agent knows not to use it for rerendering or approval. It does not explicitly name sibling tools, but the behavioral exclusions effectively guide selection.

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