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

Annotations already declare readOnly, idempotent and non-destructive, but the description adds meaningful behavior beyond them: the link is authenticated, access is re-checked at download time, and revision gates are re-evaluated. That is real context about what happens on use, though it omits link lifetime/expiry.

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 short sentences, front-loaded with the core action and followed by the two boundary clarifications. Efficient with no padding, though the review-copy sentence is slightly tangential.

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 read-only link-retrieval tool with full annotation coverage and no output schema, the description adequately covers safety, the access check, and scope limits. The main gap is explaining the jobId input, which the schema does not cover either.

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 single parameter jobId has 0% schema description coverage, so the description must carry the burden. It only implies that jobId refers to a 'generated file' and never explains the identifier's origin or how to obtain it, leaving the parameter semantics largely undocumented.

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 ('Get an authenticated link') scoped to an 'existing generated file', which an agent can distinguish from the many export/read siblings. It stops short of naming a specific alternative sibling, so it is clear but not fully differentiated.

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 draws a scope boundary ('does not approve, send or submit the file') and notes that historical dossiers/presentations are review copies, implying context of use. However it never explicitly says when to choose this over siblings like export_dossier or read_produced_document, leaving routing to inference.

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