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

Goes well past readOnlyHint/destructiveHint by disclosing cost ('free, no units'), that nothing is transmitted ('nothing sent'), that nothing is auto-fixed ('nothing is computed for you'), the return shape (ok plus problems carrying field, BR-… rule and message), and the stricter validation that awaits at render. These are exactly the traits an agent needs to plan a retry loop.

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 it validates, then the cost/offline guarantees, then the problem-then-render workflow, then the caveat about the render validator. Dense but every clause carries information an agent would otherwise have to infer.

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 validator with an output schema, the description covers purpose, cost, iteration loop, and the boundary against render-time validation. 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 coverage is 100%, so the param details (block contents, profile enum, en16931 default, basic restrictions) are already carried by the schema. The description adds the tie that matters: the same block is what gets passed to render as data._invoice, which clarifies identity and reuse rather than restating 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 specific verb and resource (checks the _invoice block) plus the scope: offline, mirroring the API's pre-render validation, covering EN 16931 fields, totals, VAT categories, code lists and French domestic rules. It is clearly separable from the render sibling, which it names and contrasts with the stricter full rule set plus PDF/A-3b.

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 positions the tool before render in a workflow: validate, change the values a problem names, check again, then call render with einvoice. It also names the condition that distinguishes its checks from the render-time validator, so the agent knows when this suffices and when it does not.

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: discloses unit consumption ('Every call is a new render that counts units like a PDF'), plan gating, the fact that the source is not retained, the 20 MB cap, and that the response carries status/download_url. Annotations only say readOnly=false, idempotent=false, destructive=false; the description adds the material cost and retention behavior. Minor gap: no mention of failure/error behavior or how long download_url stays valid.

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 it does, then the alternative, then the input rule, then the cost/limits. Dense and nearly every clause carries information, though the second and third sentences are long run-ons that could be split for scanning.

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, zero-required conversion tool, the description covers inputs, exclusivity rule, size limit, plan eligibility, cost model, retention, and the sibling alternative; return values are covered by the existing output schema. Nothing an agent needs to call 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%, so baseline is 3, but the description adds meaning the schema lacks: the exactly-one-source constraint (required list is empty and there is no oneOf), and clarification that render_id must be a docx/pptx render. It does not explain landscape, page_ranges, single_page_sheets or filename beyond the schema, but those are already well documented.

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 (converts) and enumerates the exact resource types accepted (Word, Excel, PowerPoint, OpenDocument, RTF, HTML) plus size limit, and explicitly contrasts with the sibling 'render' for the template+data case. An agent can distinguish this from render 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?

Names the alternative tool and the condition that selects it ('To make a document from a template and data, use render instead'), and gives an explicit rule for mutually exclusive inputs ('Pass exactly one source') with the three valid variants. It also flags a hard eligibility constraint (Free plan cannot convert).

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 readOnly/openWorld annotations: it discloses cost ('free'), the failure mode for an unknown id ('returns an error'), the 2 MB cap on image payloads, and the fact that download_url is time-limited via expires_at. That is exactly the operational context an agent needs before polling.

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?

Two dense sentences with no waste: what comes back first, then when to call it, then the cost/error caveats. Every clause (2 MB cap, expires_at, wait false) maps to a real agent decision.

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 flags the practically important pieces — the status enum and the expiring link — and adds polling guidance and error behavior. For a one-parameter read tool, an agent has everything needed to call it correctly on the first try.

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 id parameter is fully documented in the schema, including the rnd_ prefix convention, so the description adds little. The 'unknown id returns an error' clause is the only extra semantic value. Baseline 3 applies when 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 ('Returns the current state of a render') and enumerates the concrete fields returned (status values, download_url/expires_at, page_count, units, error, image preview cap). It also explicitly distinguishes itself from the siblings render and convert_to_pdf, which already return this payload for their own renders.

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 two explicit when-to-use triggers ('follow a render started with wait false' and 'get a fresh link once the old one has expired') and an explicit when-not-to-use case ('render and convert_to_pdf already return this'). Nothing about tool selection 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?

Beyond the readOnly annotations it discloses the published-vs-draft fallback, that an inferred schema from sample data is a guide rather than a contract, that the call is free, and that an unknown slug errors. These are behaviors 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?

Three tight sentences: what is returned, when to call it, and the edge-case caveat. The return value is front-loaded and 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 shapes need not be spelled out, and the description covers the remaining ambiguities: version resolution, inference fallback quality, and error behavior. Nothing needed to call 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 sole `template` parameter already documents slug-or-tpl_ id format. The description adds no parameter-level detail beyond naming the slug context implicitly, 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: returns the JSON Schema of a template's `data` object plus its sample data. It also pins the resolution rule (published version, else latest draft), which no sibling tool does.

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 sequencing ('after list_templates and before render or validate_template') and a clear exclusion ('ad-hoc html has no stored schema to read'). The failure case for an unknown slug is also 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 readOnlyHint, destructiveHint, and openWorldHint annotations, it discloses important behavior: the full set of returned components, checksum usage for subsequent saves, version resolution semantics, and the Word/PowerPoint limitation. It also notes that the operation is read-only and free.

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 description is dense but well-structured and front-loaded with what is returned. Every sentence contributes operational information: return contents, save workflow, version semantics, and the document-format caveat.

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 the presence of an output schema, full schema description coverage, and clear read-only annotations, the description is complete enough for an agent to invoke the tool correctly. It covers return scope, version behavior, downstream save workflow, and an important edge case for Word and PowerPoint templates.

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?

The schema fully documents both parameters, so the baseline is 3, but the description adds meaningful semantics for the version parameter: what latest means, what published means, and how draft/build versions are selected. It does not further explain the template slug or tpl_ id beyond the schema, but the added version behavior is valuable.

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 resource and verb: it returns the source composition of a template version, enumerating body markup, css, head, settings, data, translations, partials, and checksum. This is specific enough to distinguish it from siblings like get_template_schema and 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?

It gives clear workflow guidance: call before save_template when editing a user-named template and pass the returned checksum as base_checksum. It also explains version selection behavior for latest, published, version numbers, and channels, though it does not explicitly name alternative read tools such as 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?

Annotations already declare readOnlyHint and destructiveHint=false, so 'Read-only and free' is partly redundant, but 'free' is new. The genuinely additive content is the scoping model: a signed-in agent sees the workspace chosen at connect time (changeable under Account → Connected agents) while an API key is pinned to the workspace it was created for. That explains why the answer might differ from user expectation, which annotations never 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?

The payload is front-loaded in the first sentence (what is returned), then triggers, then the scoping caveat. Four sentences with little waste, though 'Read-only and free' partly restates the annotations and could be trimmed.

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 elaboration, yet the description still summarizes the fields an agent would reason about. With zero parameters and full annotation coverage, nothing an agent needs in order 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?

The tool takes no parameters, so the baseline of 4 applies. The description correctly offers no parameter guidance and instead spends its words on what the fixed result contains.

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 names a concrete resource and enumerates exactly what comes back: workspace, organisation, plan, environment, and unit totals (included, used, prepaid balance). That is specific enough that an agent can distinguish it from every sibling in the list, none of which report account or workspace state.

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 concrete triggers ('where a document will land', 'how many renders are left') and a diagnostic case tied to a named sibling: when list_templates returns unexpected results. It stops short of stating when not to call it or naming alternatives for the diagnostic case, so it is clear context without exclusions.

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 readOnlyHint/destructiveHint, but the description adds real behavioral facts: results are most-recently-changed first, archived templates are excluded, all matches come back in one answer (no pagination), an empty list signals no match, and a null published_version means render cannot use it. It also notes the call is free, which matters for an agent deciding whether to probe.

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 scope, and every clause carries information an agent would otherwise have to guess. The single dense block runs long and chains several ideas, but there is no filler sentence to cut.

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 the description needn't enumerate return values, yet it still calls out ordering, archived exclusion, and the published_version null edge case that gates render. Combined with 100% schema coverage and clear annotations, an agent has everything needed to call this correctly or decide not to.

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 q, tag, kind and engine are already fully documented, including case-insensitivity, exact-match tag format, and the kind/engine enums. The description's brief gloss of kind values repeats the enum rather than adding filtering 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?

Specific verb (Lists) plus resource (templates) plus scope (the workspace this server works in, chosen at sign-in or the API key's), ordering rule, and the returned field set. It also names the siblings that consume the slug (get_template_schema, validate_template, render), so an agent can place it precisely in the workflow.

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: "Call it first to find the slug that get_template_schema, validate_template and render take." Explicit when-not: "skip it when the user already named the template." Both the trigger and the exclusion are 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?

Annotations already cover the safety profile (readOnly=false, destructive=false), and the description adds real behavioral context: every call is a new render consuming units, test keys are free but watermarked, templates render their published version and fail with template_not_found when null. Failures return status failed with a code/message, and links expire at expires_at. Good additions, but the einvoice and return-shape details are partly duplicated by the output schema, so it sits at a solid 3.

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, then progressively less common concerns (units, einvoice, expiry). It is long, and the einvoice sentence packs several ideas together, but nearly every sentence carries operational information and could not be cut without loss.

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 9-parameter, nested-object, mutation tool with an output schema, the description covers source choice, output defaults, failure mode, cost, expiry and the einvoice branch. Nothing an agent needs to call 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 already documents each parameter with enums and nested einvoice fields. The description adds a few non-obvious constraints — data shaped per get_template_schema, data._invoice for einvoice, published-version template selection — but most of its parameter talk restates the schema. 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?

Opens with a concrete verb+resource+output matrix: filling a stored template or ad-hoc html with data, yielding PDF/image/DOCX/PPTX. It explicitly names the sibling it is not (convert_to_pdf) in the same breath, so an agent can route without opening either 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?

States the positive case ("Use it to make a document from data") and the exclusion with an alternative ("to turn an existing office file into a PDF, use convert_to_pdf"). It also points to validate_template and check_invoice as preflight steps, giving concrete ordering guidance rather than vague hints.

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, it discloses the key behavioral trait that the save is draft-only and does not affect renders until a person publishes. It also covers authorization requirements, the return contents including review_url, the validation loop with sample data, base_checksum conflict behavior, and plan-limit implications.

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 description is dense but appropriately sized for a 13-parameter mutation tool with nested objects. The most important fact, that this saves a draft and never publishes, is front-loaded, and each subsequent sentence adds operational guidance rather than repeating schema details.

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?

It covers the essential context an agent needs: draft semantics, the two invocation modes, prerequisite read via get_template_source, authorization, unsupported template types, validation expectations, and the review workflow. Although an output schema exists, the description's mention of review_url and validation errors is still useful for agent behavior.

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 100%, so the schema carries most parameter documentation. The description still adds meaningful semantics beyond the schema for the central parameters: partial updates keep unchanged parts from the read version, base_checksum detects newer versions, and change_note is read by the person before publishing.

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 ('Saves a template as a draft') and immediately distinguishes it from publishing or rendering by noting that renders keep using the published version. It also clearly separates the two save modes: updating an existing template versus creating a new 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?

It gives explicit workflow guidance: read with get_template_source first, change only what the user asked for, and pass template plus base_checksum for an existing template, or new_template plus html for a new one. It also names a limitation (Word and PowerPoint templates cannot be saved here), which helps the agent avoid misuse.

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?

Adds substantial context beyond the readOnly/non-destructive annotations: the call is free, consumes no units, stores nothing, and produces no document. It also discloses result semantics — `ok` plus `diagnostics` with severity, code, message, path/line/column, or part/paragraph for Word and PowerPoint — and clarifies that warnings leave `ok` true but should be settled before rendering.

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?

Dense but front-loaded: cost and side-effect guarantees come first, then when to call, then per-mode behavior, then return semantics. A few clauses restate schema-documented defaults (version fallback, data omission), but the length is justified by the tool's two-mode complexity.

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?

Covers everything an agent needs for a 5-parameter, mode-switching validation tool: cost, side effects, mode selection, what each mode checks, and how to interpret warnings versus errors. An output schema exists, yet the description still summarizes the return contract helpfully rather than leaving a 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter behavior the schema does not convey: the `template` path validates against the published version falling back to latest or a named version, whereas `html` + `engine` compiles offline and reports unknown filters and variables missing from `data`. It also explains what the data is checked against (the stored JSON Schema, with wrong types or missing required fields as errors).

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 ("Checks a template and its data without rendering") and immediately distinguishes itself from `render` by declaring no units are consumed and no document is produced. It further splits the tool's two operating modes (stored template vs. ad-hoc html) so an agent can tell exactly which capability it is invoking.

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 triggering conditions: call it "before render when you assembled the data yourself, or after writing ad-hoc html," which effectively routes the agent away from `render` when validation is the goal. It does not state any when-not conditions (e.g., cases where validation is redundant), so it falls just short of a 5.

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