Dynamic Document API

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, which covers the safety profile. The description adds real value beyond that: a signed download URL with a lifetime tied to `expires_in`, the validator verdict location `conformance.einvoice.status`, per-minute rate limits, and the test-key override of the `test` flag. Given annotations carry the write/open-world semantics, a 3 understates how much the description adds, but the bar is lower with annotations present.

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 action and the alternative, then failure behavior, then test/rate-limit caveats. It is long, but nearly every sentence carries distinct information an agent needs; the trailing rate-limit note is slightly tangental but still operationally relevant.

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, nested-payload mutation tool the description covers the failure mode, validation verdict, output artifact and its lifetime, and the test/final billing distinction. The output schema already exists, so omitting deeper return-value detail is appropriate.

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 100%, so every parameter including `invoice`, `profile`, `syntax`, `test`, `metadata`, `reference` and `expires_in` is already documented in the schema with examples and enums. The description echoes only a little of this (`expires_in` default of 1 h), so the baseline of 3 is correct — the schema, not the description, does the parameter work here.

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 artifact ('Generate a standalone, validated e-invoice XML file from invoice data') and names the concrete profiles it targets. It also distinguishes itself from `render_pdf_from_template`, so an agent can route between XML generation and PDF embedding without opening a schema.

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?

Explicitly routes the alternative case ('To embed the invoice in a PDF instead, use `render_pdf_from_template` with `einvoice`') and explains the recovery path on validation failure ('fix those fields and call again'). The test-vs-final key behavior and per-minute limits give the agent the operational context needed before calling.

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

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

Annotations already cover the read-only/idempotent safety profile, but the description adds crucial non-obvious behavior: it is not billed, it carries a 60-calls-per-minute shared rate limit, URLs are freshly signed and last expires_in until retention ends, after which the render becomes expired with no URL. This is exactly the context annotations cannot convey.

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 purpose, then usage, then expiry semantics and limits in a logical order; every sentence carries information. It is on the long side for a one-parameter tool, but no sentence is filler.

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 still covers lifecycle semantics (queued/processing/succeeded/failed/expired), URL lifetime, cost, and rate limits. An agent has everything needed to call it correctly.

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 100% and the single render_id parameter already documents its expected form (`rnd_01J9ZM…`). The description explains where the id comes from ('from a render tool's result'), which is minor added value, but the baseline of 3 applies when the schema does the heavy lifting.

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 ('Fetch one render ... by id') and enumerates what comes back (status, files with signed URLs, billed_renders, conformance report). It is unambiguous against siblings like render_pdf_from_html, which create renders rather than retrieve one.

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?

Explicit when-to-use ('when a render tool returned queued or processing', or an expired download link), when-not ('Not needed after a render tool already returned succeeded'), and even the polling cadence ('call again every few seconds until succeeded or failed'). Nothing is left to inference.

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

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

Goes well past the readOnly/idempotent annotations: discloses billing status ('Not billed'), a concrete rate limit ('60 tool calls a minute per connection, shared by all tools'), the einvoice side effect on every PDF render, and the plan-gated `einvoice_skipped_plan` warning. This is behavior an agent could not infer from annotations or schema.

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 purpose and tightly packed, with each sentence carrying distinct information (dependencies, e-invoice behavior, rate limit). The einvoice_default sentence is long and condition-heavy, which is the only mild drag on readability.

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, yet the description still frames what the returned `data` is for and how to build a valid render payload, plus prerequisites, rate limits, and plan constraints. Nothing an agent needs to invoke this correctly is missing.

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 100%, so the schema already defines `template_id` and its format. The description still adds usable sourcing guidance ('an id the user gave', implicitly from `list_templates`), which is slight but genuine added meaning beyond the schema.

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?

Opens with a specific verb+resource ('Get the `data` a template expects before rendering it') and enumerates exactly what comes back: JSON Schema, dotted-path fields with type/required, image dynamic properties, example payload, and `einvoice_default`. This clearly separates it from sibling renderers and from `list_templates`.

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?

Gives explicit when-to-use ('Call it once per template, after `list_templates` or with an id the user gave') and explicit when-not ('`render_pdf_from_html` and `render_pdf_from_markdown` take no template and need no schema'). The downstream consumers (`render_pdf_from_template`, `render_image_from_template`) and the consequence of skipping it (data rejected) are named.

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

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

Beyond the annotations (which only declare it as a safe, idempotent read), the description adds pagination behavior (50 per page, next_cursor/has_more contract), the billing status ('Not billed'), and a concrete rate limit shared across all tools. These are operational facts an agent cannot derive from the schema or 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?

Information-dense and front-loaded: purpose, usage, routing, pagination, then cost/limits. Every clause carries distinct operational information with no filler.

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 no explanation; the description covers everything else an agent needs — discovery role, sibling routing, pagination loop, and throttling — for a 4-parameter read tool with an enum filter.

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 100% and self-documenting, but the description still adds value by restating the 50-item default and explaining the cursor contract ('pass next_cursor as cursor while has_more'), which links the request parameter to the response field.

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 ('List the published templates of the connected workspace') and enumerates the returned fields (id, name, type, live version). This clearly separates it from the render_* and get_template_schema siblings.

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?

Gives explicit when-to-use ('find the template_id for a document the user describes'), explicit when-not ('skip it when you already have the id'), and routes by template type to render_pdf_from_template or render_image_from_template, plus names get_template_schema as the logical next call.

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

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

With annotations only declaring readOnly=false/destructive=false/openWorld=true, the description carries real behavioral load: sources stay unchanged, a 25 s wait ceiling before returning queued/processing, signed download URLs tied to expires_in, TEST watermark and per-minute test-render limits, and a 60 calls/min connection-wide rate limit. This is context an agent cannot get from the 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?

The purpose, ordering, and bookmark behavior are front-loaded, and each subsequent sentence adds a distinct operational fact. It is on the long side — the rate-limit and test-key details could be compressed — but no sentence is filler.

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 nested-source, high-parameter tool with an output schema, the description covers the prerequisite chain, ordering, async fallback, link lifetime, and quota constraints. Nothing an agent needs in order to invoke it correctly is missing, and return-value details are appropriately left to the output schema.

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 100%, so the baseline is 3, but the description adds semantics the schema does not: sources are consumed 'in the order given', render_id references an earlier render's stored files, bookmarks defaults to a per-source bookmark, and expires_in defaults to one hour. These tie the parameters into an actual workflow rather than restating field docs.

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 first sentence states a specific verb (merge), resource (existing PDFs), cardinality (2-200), ordering guarantee, and the bookmark default. It also explicitly distinguishes itself from the render_* siblings with 'It renders nothing itself', so an agent can tell what this tool is not.

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 names concrete use cases (combining a cover letter and an invoice from earlier renders, or public-URL PDFs) and states the prerequisite workflow: render each part first, then pass its render_id. It also routes the agent to get_render when the result is queued or processing, and to re-sign expired links.

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

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

Far exceeds the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), which only signal a non-idempotent, non-destructive, open-world write. The description adds the 25 s synchronous wait, the queued/processing fallback and how get_render resolves it, signed-URL lifetime tied to expires_in, TEST watermark behavior for test keys, and a 60 calls/min per-connection rate limit.

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-loads what the tool does, then workflow, then alternative, then timing/async/test/rate-limit behavior. Every sentence carries operational information, though the final third is dense and packs async, test-mode, and rate-limit facts into one paragraph that is harder to scan than the opening.

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 10-parameter mutation tool with an output schema, the description is complete: it covers prerequisites, data shape, format scope, async handling, URL lifetime, and quota limits. Return-value detail can correctly be delegated to the output schema, and nothing needed to invoke it successfully is missing.

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 100%, so the baseline is 3, but the description adds concrete semantic framing for data (dotted keys like title.text and hero.src with an image URL) and explains expires_in's default and re-signing behavior. The remaining parameters (image, format, version, filename, metadata, reference) are left entirely to the schema, so it stops short of a full 5.

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+resource (render an image from a saved image template) and enumerates concrete use cases (social/OG images, banners, badges). It explicitly names the sibling it is not (render_pdf_from_template for PDF), so an agent can route without opening schemas.

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?

Gives an explicit prerequisite chain: find the template via list_templates (type: image_canvas), learn its settable properties via get_template_schema, then pass them in data. It also gives explicit alternatives for adjacent needs (render_pdf_from_template for PDF, get_render for slow renders) and states when the async path applies.

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

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false): it discloses the 25s wait-then-return flow, the queued/processing async path and that get_render collects and re-signs expired links, that remote assets must be public URLs, that the test key yields watermarked test renders, and the shared 60 calls/min limit.

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 purpose, then routing, then mechanics — a sensible order with no filler sentences. It is dense and long, but each sentence carries distinct operational information rather than restating the name or schema.

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 10-parameter, nested-schema tool with an output schema present, the description supplies everything the schema cannot: async handling, asset restrictions, auth/test-key semantics, and rate limits. Return-value details are correctly left to the output schema.

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 100%, so the baseline is 3, but the description adds Jinja syntax examples (`{{ name }}`, `{% for row in rows %}`) that meaningfully help an agent construct the `data`/`html` inputs, and it restates the expires_in default and test-mode interplay. The many pdf sub-options (scale, margin, page_ranges) are left to the schema.

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 precise verb+resource ('Render a PDF from HTML') and immediately scopes it as 'HTML and CSS you write, in headless Chromium.' It explicitly differentiates from siblings render_pdf_from_template and render_pdf_from_markdown, so an agent can route without opening any schema.

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?

Gives an explicit when-to-use condition ('when no saved template fits and the layout matters: letters, styled tables, one-off documents') plus two named alternatives with the condition selecting each. When-not guidance is unambiguous.

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

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

Goes well beyond annotations (readOnlyHint=false, openWorldHint=true) by disclosing the 25 s blocking window, the signed-URL return with expiry, the queued/processing async fallback and its collector tool, the TEST watermark and per-plan limiting when a test key is used, and the 60 calls/minute connection-wide rate limit. It also states a real content constraint (raw HTML not rendered), which is behavior an agent must know before calling.

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 purpose and then ordered by escalating need: capabilities, sibling routing, timing/return, async fallback, test-mode and rate limits. Dense but every sentence is operational. Slightly overstuffed in the test-key sentence, which repeats ground the `test` parameter description already covers.

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 10-parameter, open-world, potentially asynchronous renderer with an output schema, it covers the pieces an agent actually needs: which sibling to pick, how long it blocks, what comes back, what to do when it does not finish, and the quota/test constraints. Return-value detail is correctly left to the output schema.

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 100%, so the baseline is 3; the description earns a step above by adding meaning the schema does not, notably that the Markdown source accepts tables/task lists/footnotes but excludes raw HTML, and that the theme is the built-in default path. It does not re-explain individual PDF options, which is appropriate given the schema already documents them.

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 ('Render a PDF from Markdown') plus its built-in theming, and immediately names the two sibling renderers it is not (render_pdf_from_html, render_pdf_from_template). An agent can select this tool without opening any schema.

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?

Gives the concrete use case (report, summary, notes with no layout work) and explicit routing rules: designed layout -> render_pdf_from_html, saved template -> render_pdf_from_template. It also names get_render as the follow-up path for queued/processing renders, covering the alternative for the async case.

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

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

Annotations declare a non-read-only, open-world, non-idempotent operation, and the description layers on concrete behavior beyond them: a 25 s wait then queued/processing with get_render as the collector, signed URL lifetimes, TEST watermark semantics under a test key, plan-gated e-invoice skipping with a named warning, and a 60 calls/min connection limit.

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-loads purpose and routing, then escalates into behavior, e-invoice rules, and limits. Almost every sentence carries operational content, but the e-invoice passage is dense enough that the section on the default-vs-override interplay could be tightened.

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?

Given 10 parameters, nested objects, and an output schema, the description covers routing, prerequisites, async collection, billing/watermark behavior, and the full e-invoice decision tree. Nothing an agent needs to invoke it correctly is missing.

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 100% and the schema itself is rich, so the baseline is 3; the description still adds cross-parameter meaning the schema cannot express — einvoice replaces the template's einvoice_default, einvoice:null turns it off, and a test API key overrides the test parameter. It does not, however, add format detail for the pdf option object or margins.

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 ('Render a PDF from a saved template of the workspace plus JSON data') and immediately distinguishes itself from render_pdf_from_html, render_pdf_from_markdown, and render_image_from_template by naming when each applies. An agent can route without opening any schema.

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?

Explicit when-to-use ('when a template exists for the document') and when-not, with named alternatives for each case, plus the prerequisite tools list_templates and get_template_schema for the required inputs. No inference left to the agent.

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