Dynamic Document API

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

With annotations only telling the agent this is a non-read-only, non-idempotent, non-destructive write, the description supplies the real behavioral profile: a signed download URL valid for `expires_in`, a validator verdict at `conformance.einvoice.status`, and exhaustive per-field-path error listings on rule violations. It also discloses plan gating (402), free test renders with a TEST note, and the 60-calls-per-minute connection limit — none of which annotations 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 the alternative, then outputs, failure modes, plan gating and rate limits — each sentence carries distinct information. It is dense but a touch back-loaded, with billing/test-mode and rate-limit caveats stacked at the end where a scanning agent may skim past them.

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 an 8-parameter, nested-object, mutation tool this covers what matters: how to obtain output, how success is verified, how validation failures surface, and what account/rate constraints gate the call. Even though an output schema exists, the returned status enum and URL lifetime are surfaced where an agent will act on them.

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 field-level meaning of `profile`, `syntax`, `test`, `invoice` and `expires_in` is already carried by the schema. The description echoes return-URL lifetime and default but adds no syntax/format guidance beyond it, so it meets the baseline rather than exceeding it.

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") with the concrete standards it targets (XRechnung, EN 16931, Peppol). It also names the sibling it is not — `render_pdf_from_template` with `einvoice` — so the agent can separate XML-only output from 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 agent: use this for standalone XML, use `render_pdf_from_template` with `einvoice` when the invoice must be embedded in a PDF. Adds hard preconditions (Growth plan or higher, otherwise 402 `plan_feature_unavailable`) and explains the API-key/test-mode interaction, so an agent knows both when to pick it and when the call will be rejected.

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 declare readOnly/idempotent/non-destructive, and the description adds real context on top: URLs are re-signed and last `expires_in` again, retention ends at which point the render becomes `expired` with no URL, the call is not billed, and there is a 60 calls/minute per-connection limit shared across tools. Those are non-obvious operational traits an agent cannot get from the structured fields.

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 purpose, then when-to-use, then when-not, then expiry/billing/rate-limit caveats — every sentence contributes distinct information. It is dense and semicolon-heavy, which slightly hurts scannability, but there is 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?

For a single-parameter read tool with full annotation coverage and an output schema, the description covers everything an agent needs: what comes back, when to call it, when not to, and the state-transition caveats around URL expiry and retention.

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% and the single `render_id` parameter is already documented with its format and provenance, so the description adds little beyond "by id". Baseline 3 applies since the schema carries the parameter burden.

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 the payload contents (status, freshly signed file URLs, billed_renders, conformance report). This clearly separates it from the render_* siblings, which create renders rather than retrieve them.

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 positive triggers ("when a render tool returned `queued` or `processing`", "when a download link has expired") and an explicit negative one ("Not needed after a render tool already returned `succeeded` with its files"). No inference is required to decide between this and a render_* sibling.

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 declare read-only/idempotent/non-destructive, but the description goes well beyond: it is not billed, it is capped at 60 calls per minute shared across all tools, and it warns that when `einvoice_default` is set the `data` must also carry the invoice object at `invoice_path`, with plan-based skipping (`einvoice_skipped_plan`) on Free and Starter. It also notes downstream validation behavior (render tools reject non-conforming data).

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?

Purpose is front-loaded and every sentence carries operational information (rate limit, plan gating, sibling exclusions). The opening sentence is overloaded with four comma-separated clauses, which slightly taxes readability, but there is 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?

Despite an output schema existing, the description still previews the return shape, and it adds the prerequisites (id source, plan tier behavior, einvoice coupling) an agent needs to call this correctly. Nothing material is missing for a one-parameter read 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 coverage is 100% and the single parameter is documented with an example format, so the schema does the heavy lifting (baseline 3). The description adds genuine context by naming the authoritative source of the id (`list_templates` or the user), which the schema does not say.

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 is returned: JSON Schema, dotted-path fields, image dynamic properties, example payload, einvoice_default. This clearly separates it from the sibling render_* tools, which consume the schema rather than produce it.

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 states when it is needed ('before rendering'), when it is not ('`render_pdf_from_html` and `render_pdf_from_markdown` take no template and need no schema'), the call frequency ('One call per template is enough'), and where the id comes from (`list_templates` or the user). 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?

Annotations already cover the safety profile, and the description adds context an agent could not infer: 50 results per page, the has_more/next_cursor paging loop, no billing, and a 60 calls-per-minute per-connection limit shared across all tools.

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?

A single dense paragraph, front-loaded with purpose and scope, followed by routing, pagination, and operational limits. Every sentence carries a distinct, non-redundant instruction.

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 field detail is unnecessary; the description still covers discovery purpose, sibling routing, pagination, billing, and rate limits. Nothing an agent needs to call 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?

With 100% schema coverage the baseline is 3, but the description adds the paging contract that the schema alone does not state: the default page size and the instruction to pass `next_cursor` as `cursor` while `has_more` is true. It also ties template `type` values to the correct downstream render tool, which is meaning beyond the enum itself.

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 fields returned (id, name, type, live version), which lets an agent distinguish it immediately from get_template_schema and the render_* 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 ('to find the `template_id` for a document the user describes'), an explicit when-not ('skip it when you already have the id'), and routes by template type: pdf_code/pdf_markdown to render_pdf_from_template, image_canvas to render_image_from_template, and schema lookup to get_template_schema.

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: sources remain unchanged, synchronous wait is capped at 25 s, slow renders return `queued`/`processing`, download URLs are signed and expire per `expires_in`, expired links can be re-signed by get_render, and there are per-minute limits plus TEST-watermark behavior for test keys. The rate limits and watermark disclosure are exactly the kind of context annotations don't carry.

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 what the tool does and its hard limits, then use cases, then async/return behavior, then operational constraints. Dense but every clause is informative; there is no filler or restatement of the tool name.

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?

With an output schema present, annotations covering read-only/destructive/idempotency, and 100% schema coverage, the remaining risks an agent faces (sync vs async, link expiry, test vs billed renders, rate limits) are all addressed in the description. Nothing material is missing for correct invocation.

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 still adds value by explaining ordering of `sources`, the `bookmarks` default semantics, and that `expires_in` governs the returned signed URL lifetime and is reusable by get_render. It leaves `metadata`, `reference`, and `filename` elaborations mostly to the schema, which already documents them well.

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 with hard scope ("Merge 2-200 existing PDFs into one PDF, in the order given") plus the bookmark behavior, and explicitly separates itself from the render_* siblings by noting "It renders nothing itself." An agent can distinguish it from render_pdf_from_html/template 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 concrete use cases ("combine documents, e.g. a cover letter and an invoice from earlier renders") and names get_render as the tool to use when the result returns `queued`/`processing`. It stops short of an explicit rule about when to choose merge_pdfs versus the render_* family for new content, but the boundary is strongly implied by "it renders nothing itself."

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 only declare non-readonly, open-world, non-idempotent, non-destructive; the description adds real behavior beyond that: a 25 s wait with signed URLs valid for `expires_in`, the queued/processing async states, watermark and free-test semantics, and a 60 calls/min connection rate limit. None of that is derivable 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 the core action and formats, then routing, then behavior; each sentence carries distinct information. It is dense for a single paragraph — the test-key and rate-limit sentences could be split out — but nothing is truly redundant.

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 tool with nested objects, an output schema, and annotations, the description covers the entry path, data shape, alternatives, async follow-up, and limits. Return-value detail is correctly omitted since an output schema exists.

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 every parameter is already documented, including dotted keys for `data`, `expires_in` defaults, and `version` options. The description largely restates those facts; its only marginal addition is the workflow hint that `data` keys come from `get_template_schema` and that `hero.src` is an image URL. Baseline 3 is appropriate.

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?

Specific verb + resource (render an image from a saved image_canvas template plus data), names output formats and concrete use cases (social/OG images, banners, badges), and explicitly separates itself from the PDF sibling. An agent can identify the tool without opening the 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 routing: image templates come from `list_templates` with `type: image_canvas`, dynamic properties from `get_template_schema` go into `data`, and PDFs go to `render_pdf_from_template`. It also gives the fallback path for slow renders (`get_render` collects queued/processing and re-signs links), which is exactly the when-to-use decision an agent needs.

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 only declare non-readonly, open-world, non-idempotent, non-destructive; the description adds substantial operational context beyond that: a 25 s synchronous wait then signed download URLs with an expiry, queued/processing states that require get_render and re-signing, the requirement that remote images/fonts be public URLs, the TEST watermark and per-minute limits on a test key, and a 60 calls/min connection-wide rate limit. These are exactly the traits an agent needs to plan a call sequence.

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 templating, then lifecycle, then billing/limits — a sensible ordering with no filler sentences. Slightly long, and the test-key billing behavior is partly restated from the `test` parameter description, but each sentence still carries operational 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?

For a 10-parameter mutation tool with nested pdf options, this is complete: it covers input constraints (public URLs for assets, Jinja via `data`), timing and async fallback, auth/billing behavior of the API key, and rate limits. An output schema exists, yet the description still provides the return-lifecycle facts an agent needs to know before calling.

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, and the description earns above that by explaining the Jinja semantics of `data` with concrete syntax ('{{ name }}', '{% for row in rows %}'), that `head` is the place for web-font <link> tags, and that `expires_in` defaults to one hour with get_render re-signing. It does not add anything about the pdf options block, but the schema already documents those well.

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 a PDF from HTML/CSS in headless Chromium) and immediately triangulates against the two sibling render tools by name. An agent can distinguish it from render_pdf_from_template and render_pdf_from_markdown 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 explicit positive conditions ('when no saved template fits and the layout matters: letters, styled tables, one-off documents') and explicit alternatives with the selecting condition for each ('for a saved template use render_pdf_from_template'; 'for a text report without layout work render_pdf_from_markdown is shorter'). Also names get_render as the follow-up path for slow renders.

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 only declare the safety profile (not read-only, open-world, non-idempotent, non-destructive); the description adds the substantive behavior: a 25 s wait then signed URLs, the queued/processing async path with get_render and re-signing, the TEST watermark on test renders, and a 60 calls/minute per-connection limit. It also discloses a hard capability boundary — raw HTML is not rendered.

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 alternatives, then async/expiry behavior, then billing and rate limits — a sensible information hierarchy. It is dense and long-ish for one paragraph, but nearly every clause carries operational weight; only the expires_in restatement is mild duplication.

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?

With an output schema present, return values need no explanation, and the description still covers what an agent must know before calling: timeout, async fallback, link expiry, watermark/billing semantics and rate limits. Nothing material is left to inference for a 10-parameter, nested-object render 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 100%, so the input schema already documents all 10 parameters including expires_in's 3600 default and the test-mode semantics. The description restates the expires_in default and the API-key override of test mode, adding reinforcement but no genuinely new parameter semantics, so the baseline 3 applies.

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 the mechanism (built-in theme) and the value proposition. It explicitly distinguishes itself from the two nearest siblings, render_pdf_from_html and render_pdf_from_template.

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?

Names both alternatives and the condition that selects each ("For a designed layout use render_pdf_from_html, for a saved template use render_pdf_from_template"), and positions this as the quick option for reports, summaries or notes. It also routes the agent to get_render when a render comes back queued or processing.

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 only say it is a non-read-only, open-world, non-idempotent call; the description adds the behavior that matters: a 25 s wait then signed URLs with an expires_in lifetime, queued/processing outcomes recovered via get_render, test-key semantics with watermarking, plan gating for e-invoicing with an einvoice_skipped_plan warning, and a 60 calls/min connection rate limit. None of that is inferable from the 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 routing, then builds outward to timing, statuses, test mode, e-invoicing and rate limits; most sentences carry distinct information. It is dense and the e-invoice plan limitation is spread across two sentences, but nothing is padding for a tool with this much behavior.

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, and the description still covers everything an agent needs before calling: prerequisites, failure modes (schema errors, 400 on invoice_path), asynchronous completion path, link expiry and re-signing, billing/test implications, and plan constraints. No material gap remains.

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 cross-tool provenance the schema lacks: template_id comes from list_templates, data shape from get_template_schema, and schema violations fail per wrong field path. It also clarifies the tri-state e-invoice semantics (object replaces default, null disables, omitted keeps default) and that a missing invoice_path yields a 400 validation_error.

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 three siblings by naming the cases each one handles. An agent can pick this tool over render_pdf_from_html, render_pdf_from_markdown or render_image_from_template 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 'use it when a template exists' rule, names the fallback siblings and the condition that selects each (no template -> html/markdown, images -> render_image_from_template), and routes to list_templates and get_template_schema for prerequisites. When-not-to-use is stated, not implied.

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?

Well beyond the supplied readOnly/idempotent annotations, it discloses the validation engines (KoSIT for schema/business rules, veraPDF for PDF/A-3b), what is explicitly not checked (tax correctness, signatures, PDF-page-to-XML match), and the latency contract: 25 s wait, then `queued`/`processing` collected via get_render. It also states plan availability, the 25/day test-render cap, and the shared 60 calls/minute 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 the action and accepted inputs, followed by routing, behavior, and limits in a logical order with no filler sentences. It is a dense block that packs several distinct concerns (engines, exclusions, latency, quotas) into one paragraph, which is efficient but slightly harder to scan than a structured list would be.

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 a nested source object, an output schema, and a mutation-free but quota-governed operation, the description covers inputs, engines, failure modes (valid:false with reason), async behavior, and rate limits. Nothing an agent needs in order to call it correctly and interpret the result 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 all four parameters (source variants, test, metadata, reference) are already fully documented in the schema, and the baseline of 3 applies. The description only lightly reinforces parameter meaning by tying `render_id` to create_einvoice output and mentioning the 25 s/queued behavior relevant to `test`; it adds no format, precedence, or size guidance beyond what the schema states.

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 concrete verb ('Check an e-invoice') plus the exact accepted resources: Factur-X/ZUGFeRD PDF, PDF carrying xrechnung.xml, CII or UBL XML. It also explicitly separates itself from the creation siblings ('It creates no file'), so an agent can distinguish it from create_einvoice and render_pdf_from_template without inspecting 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 explicit when-to-use conditions ('incoming invoices before they go to accounting', or an XML from create_einvoice via render_id) and explicit routing to alternatives ('to make an e-invoice, use create_einvoice or render_pdf_from_template with einvoice'). It additionally names the cases it does NOT cover (ZUGFeRD 1.0/2.0, XRechnung before 3.0, Peppol BIS 3.0), which prevents mis-selection.

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