document_render

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

With no annotations, the description carries the full burden and does substantially well: it discloses statelessness (nothing stored but the PDF), the default JSON return with a signed `download_url`, the binary alternative, that the call is asynchronous but blocks until the finished render is returned, and a throughput constraint (single worker, avoid parallel bursts). It omits auth requirements and the meaning of `Idempotency-Key`, so it is not exhaustive.

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 lead sentence states the core distinction and everything after it is scoped to a concrete decision: which path, what you get back, how to get bytes, and how to pace calls. Sentences are short and front-loaded with no filler, though the final operational paragraph is somewhat tangential to selecting the tool.

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 complex invoicing render tool with a deep nested schema and no output schema, the description covers the essentials an agent cannot infer: the call is stateless, the return value is a JSON payload with a signed URL (or raw PDF), and the render completes before returning. Given the large nested input tree, more guidance on the required `data`/`template` pair would have closed the remaining gap.

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 only 17%, so the description has to compensate. It adds real meaning for `output.delivery` (url vs binary bytes) and implicitly for the inline `data` body, but `template`, `document_type`, `Idempotency-Key` and the sync/async `output.mode` interaction with `pollUntilTerminal` go largely unexplained in the description text.

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 states a specific verb and resource ("Render a document supplied inline, storing nothing but the PDF") and distinguishes the stateless path from the stored-document path. It loses a point because it routes to a sibling named `create_document_render`, which does not exist under that name in the sibling list (the closest is `document_render_stored`), which could send an agent looking for the wrong tool.

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?

It gives an explicit alternative and the condition that selects it: render inline here, or use the other tool when the document already lives in the system. It also adds operational guidance (prefer one call at a time because rendering is CPU-bound on a single worker) and explains how to ask for bytes instead of a URL. It stops short of 5 because the referenced alternative name does not match the actual sibling tool.

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