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

With no annotations, the description carries the full burden and does well: it discloses the 15-minute URL lifetime, that the URL is signed and time-limited, that the bytes can bypass the context window via curl_example, and the accepted formats. It omits auth/permission requirements despite an authorization parameter, and says nothing about error cases or regenerating an expired link.

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?

Front-loaded with the return value and the curl_example, and the format list comes last where it belongs. One sentence is partly redundant - 'Generates the document in the requested format and returns a time-limited signed download URL' restates the opening claim, costing a little length without adding information.

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?

An output schema exists, so return values need not be re-explained, and the description covers the critical operational facts (link lifetime, curl path, format set). It stops short of documenting the nested options object, the authorization parameter, or what happens on expiry, which leaves a small gap for a 5-param tool.

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 already ~80%, so baseline is 3. The description adds genuine value beyond the schema by calling out the legacy 'doc' format (the schema's own format description omits it) and by naming the ready-to-run curl_example that the schema does not document. It does not touch options, filename, or authorization.

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: generates the document in the requested format and returns a short-lived signed GET URL, plus a curl_example. This clearly distinguishes it from request_upload_url (the inverse direction) and export_document, and the colour on the 15-minute lifetime makes the resource concrete.

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?

Explains the two consumption modes explicitly: shell-capable agents should run the curl_example to save bytes to the working directory, while clients without shell execution use the signed URL directly. That is clear context for how to use it, but it never states when to choose this tool over the sibling export_document.

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