document_download_render

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

With no annotations, the description carries the full disclosure burden and does real work: it states the signature is verified before the row is looked up, that this prevents using a forged token to probe for valid render ids, and that the token path skips auth work entirely. What it omits is what a failure looks like (404 vs 401/403), whether the response is streamed binary, and any rate limiting — gaps for a tool whose output is a file.

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 action is front-loaded in the first four words, and the remaining prose adds security-relevant behavior rather than filler. The second sentence is long and em-dash-laden, and the parenthetical 'by signature or by API key' slightly duplicates the token schema text, but nothing is wasted outright.

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 two-parameter, no-annotation, no-output-schema tool, the definition covers the auth model well but leaves the required render_id undefined and says nothing about the response shape (PDF bytes, content type, streaming) or error behavior. An agent could call it correctly but would be guessing about the return value and failure modes.

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%: the token parameter is well documented in the schema itself, while render_id has no description anywhere. The description reinforces the token path ('by signature or by API key') and explains the check ordering, but it never says what a render_id is or where it comes from, leaving the undocumented required parameter unexplained.

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 opening sentence gives a specific verb and resource ('Fetch the PDF') and names the two authentication paths, which is more than a restatement of the name. It does not, however, distinguish this tool from close siblings such as document_get_render or document_render_stored, so an agent cannot be certain which of these retrieves a stored render.

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 token description ('Present it and no API key is needed... Omit it and the request authenticates normally') implicitly tells the caller which credential path applies, and 'this is the one endpoint a browser hits directly' hints at the direct-link use case. There is no explicit statement of when to use this versus the sibling render-retrieval tools, and no exclusions or prerequisites beyond the auth choice.

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