legivel

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

Beyond the non-destructive write annotations, the description discloses import conversion behavior (what becomes editable blocks) and what is dropped (images, scripts). However, "left lists them" is garbled and does not clearly state where the omitted items are reported, and no side effects like validation failures or revision behavior are described.

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 and reasonably front-loaded, with the key constraint in the second sentence. But "left lists them" and "A starter answers its sample data too, for preview_template" are unclear fragments that cost the reader a re-read.

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?

No output schema exists, and the description compensates by naming the returned id, revision and fields. For a tool with a nested body object fully documented by the schema, the remaining gap is only the ambiguous handling of omitted images/scripts.

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 meaning the schema lacks: the mutually-exclusive-one-of rule across the four input modes and the {{path}} placeholder convention for markdown/html. The starter/preview_template relationship is mentioned but stated awkwardly.

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 ("Save a new template"), and the word "new" implicitly distinguishes it from update_template. It does not explicitly name that sibling, so the differentiation is left partly to inference.

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 a hard selection rule for the four alternative input modes ("Send exactly one of body, markdown, html or starter"), which is real when-to-use guidance absent from the schema. It omits any guidance about when to use create_template versus preview_template or update_template.

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?

The annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuinely new behavioral context: the delete cascades to associated images, renders referencing the template fail immediately with not_found, and the action is irreversible.

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 short sentences, front-loaded with the action and its cascade scope, then the downstream consequence, then the irreversibility warning. The phrasing 'Renders that name it answer not_found at once' is terse and slightly awkward, but nothing is wasted.

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 destructive tool with full schema coverage and annotations, the description covers the key risks: cascading image deletion and irreversible outcome. It does not say what happens if the template does not exist or what a successful response looks like, though these gaps are minor given the tool's simplicity.

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 fully documented in the schema as an id or a name in the format list_templates returns. The description adds no additional detail about the parameter, which is the expected baseline when the schema does the work.

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 (delete) and resource (template) and adds a scope qualifier, 'with its images', that tells the agent this is a cascading delete rather than a metadata-only removal. This separates it cleanly from create_template, update_template, and get_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?

The description does not explicitly state when to choose this over alternatives such as update_template or preview_template; there is no direct sibling delete tool, so the choice is implicitly clear. The warning that renders naming the template immediately return not_found acts as a de facto 'when not to use' caution, but the guidance is implied rather than stated.

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=true and destructiveHint=false, so the safety profile is covered; the description goes further by disclosing the return contents (body, revision, fields) in the absence of an output schema. Crucially it surfaces the optimistic-concurrency convention — passing this revision to update_template — which is real behavioral knowledge not present in any structured field. It stops short of stating error behavior for an unknown template name/id.

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 short sentences, front-loaded with what is returned, followed by the actionable next step and the pointer to the format tool. No filler and no repetition of the schema or annotations.

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 read-only single-resource getter with one documented parameter and no output schema, the description covers return shape, the revision handoff to update_template, and where to learn about the body format. Missing only minor items such as not-found behavior for a bad name/id.

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?

There is a single parameter with 100% schema description coverage, and the schema already explains that it accepts either the id or the name as produced by list_templates. The description adds no further meaning about the parameter (no format, casing, or ambiguity resolution between id and name), 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?

The description names the resource ('one template') and enumerates the returned parts (editor document body, revision, fields it reads), which is more specific than the title 'Get template'. It separates itself from list_templates implicitly by saying 'One template' and explicitly points to get_template_format for body format. The verb is elided ('One template: ...'), costing a bit of crispness but not comprehension.

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 a concrete workflow: read this, change the body, send it to update_template with this revision, and it routes the agent to get_template_format for body semantics. It does not explicitly say when to prefer list_templates or when this tool is unnecessary, but the surrounding context is clear enough to act on.

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=true and destructiveHint=false, so safety is covered. The description adds real value by disclosing the content scope of the reference (what topics are inside), but says nothing about return format, length, or whether the output is a document to read versus structured data. With annotations shouldering the safety profile, this is adequate but not rich.

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?

It is two sentences with the imperative usage instruction placed last, which is reasonable. The long topical enumeration is informative but dense — a dozen comma-separated items in one sentence — and borders on listing for its own sake where a shorter summary would carry the same signal.

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?

There is no output schema, so the description carries the burden of describing the return, and the topical enumeration does that job well. The gap is that it omits practical properties of the reference — format, size, whether it is paged — which matters for an agent deciding whether to pull the whole thing into context.

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 zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It correctly avoids inventing parameter discussion.

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 the resource precisely — the full reference of the template document — and enumerates the topics it covers (page, paragraphs, styles, formulas, bands, barcodes, grid, fonts). That makes it clearly distinguishable from siblings like get_template, list_templates, or preview_template. It never states an explicit retrieval verb, relying on the name/title, which keeps it just short of a 5.

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?

"Read it before you write or change a template body" gives a concrete trigger condition tied to the write-side siblings (create_template, update_template). It does not explicitly contrast with get_template or explain when reading this reference is unnecessary, so an exclusion clause is missing.

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=true and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing the shape of the response (period dates, counts, plan limits, per-API-key breakdown) in the absence of an output schema, which tells the agent what it will actually learn from the call. It stops short of noting data freshness or any account-level permission requirements.

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 sentence front-loaded with the resource and followed by the parameter note; every clause carries information. The phrasing 'How many of the account's documents for the period are used' is slightly convoluted and could be tightened without losing content.

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 one optional parameter, full schema coverage, safety annotations, and no output schema, the description covers what the agent needs: what is returned, and how the optional parameter changes scope. Only minor omissions remain, such as where period ids come from or whether results are per-account or per-workspace.

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%, with the schema itself explaining that period is a decimal usage-period id and that omitting it yields the current period. The description's 'Pass period to read an earlier period' merely reinforces the historical-vs-current distinction rather than adding syntax, format, or discovery guidance. 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?

The description names the resource (the account's document usage for a period) and enumerates exactly what it reports: period dates, included vs. used counts, plan limits, and per-API-key split. The verb is implicit — it reads as a statement of return contents rather than 'retrieves usage' — but no sibling tool covers usage, so differentiation is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only guidance is 'Pass period to read an earlier period,' which tells the agent when to supply the parameter, not when to call this tool versus alternatives. With no competing usage-related sibling this is largely harmless, but there are no explicit exclusions or preconditions.

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 establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value by disclosing the shape of each returned entry and the plan-level template cap, but omits ordering, pagination, and whether the cap truncates results — meaningful for a listing with no output schema to fall back on.

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?

One dense sentence with no filler, and the resource scope is front-loaded before the field enumeration. The trailing clause about 'how many templates the plan keeps' reads slightly awkwardly and could have been separated, but nothing is 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?

With no parameters, no nested objects, and no output schema, the description is the sole source of return-shape information and it delivers that. Gaps are limited to result ordering and any cap-induced truncation, which are secondary for a simple enumeration 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?

The tool takes zero parameters, so there is nothing for the description to clarify beyond the schema. It correctly implies the call is account-scoped and unfiltered, which is the only semantic worth conveying 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?

The description names the resource ('the account's saved templates') and enumerates exactly what each entry carries (id, name, revision, fields it reads), which separates it from get_template and the render/create siblings. It stops short of an explicit verb like 'list', so the enumeration is doing the work of signalling the operation.

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?

There is no statement of when to call this versus get_template, get_template_format, or get_usage. The absence of parameters weakly implies an unfiltered enumeration of the whole account, but the agent is left to infer that from the description's phrasing rather than being told.

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/non-destructive annotations: it discloses that nothing is stored, that previews consume a shared hourly plan budget (a real rate limit), the exact return shape (JPEG pictures of up to 4 pages plus a text block with page count and defects), and how problems are surfaced with path and page. The rendering conventions for a missing field (‹path›) and a non-drawing graphic (empty frame) are details an agent could not get elsewhere.

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 the purpose, then behavior, then the workflow, and each sentence carries information. The sentences are densely packed with clauses (budget sharing, defect list, placeholder conventions) but none is filler, so the density is justified rather than wasteful.

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?

There is no output schema and the tool has six parameters including nested objects, so the description must carry the return-value burden itself; it does so by naming the image format, page cap, and the accompanying diagnostics block. Combined with the cost warning and the suggested iterate-with-update_template loop, an agent can invoke and use the result correctly without further context.

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 documents csv, data, dpi, template, first_page, and page_count thoroughly. The description adds only the practical hint to request later pages with first_page, restating page-count limits that the schema already enforces, so it does not meaningfully extend parameter meaning.

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 action and resource: it produces pictures of a saved template's pages filled with data, purely for checking appearance before render_template. It explicitly distinguishes itself from the sibling render_template, which is the key confusion risk in this tool family.

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 a concrete workflow (preview, look at the pictures, change the body with update_template, preview again) and places itself before render_template. It stops short of stating when a preview can be skipped, e.g. for pure data validation where no visual check is needed, so it is clear but not exhaustive.

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?

The annotations already declare this is not read-only and not destructive. The description adds meaningful billing and idempotency behavior: each successful render counts as one document, and resending the same document with the same key returns the same PDF without counting again.

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 three concise sentences with the core operation front-loaded, followed by the counting and idempotency rules. There is no unnecessary wording.

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 18-parameter render tool, the description establishes the input, output, billing count, and idempotency guarantee. The very rich schema carries parameter details, though the description could mention output modes or sibling-tool routing more explicitly.

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 18 parameters are already documented in the schema. The description only refers to the Markdown input and idempotency key at a high level, adding no new parameter semantics 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?

The description states a clear verb and resource: turn a Markdown document into a PDF and return the PDF. It does not distinguish this from the sibling render_template tool, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains idempotency and document counting, but gives no explicit guidance on when to use render_pdf versus render_template or preview_template. It also does not state when not to use it.

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 readOnlyHint=false and destructiveHint=false, i.e. a non-destructive write. The description adds substantive behaviour the annotations cannot convey: each successful render is metered as one document, replaying the same data with the same idempotency key returns the same PDF without a second charge, and layout problems surface as warnings while the PDF is still produced. This is real operational context (billing, idempotency, non-fatal failure mode). It stops short of covering authorisation/scoping, size limits or what happens when the template id is unknown.

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?

Four short sentences, purpose front-loaded, then metering/idempotency, then the warning behaviour — a sensible order with no filler. The final sentence packs three distinct warning conditions into one clause, which is dense but still parseable. Slightly more structure (or an explicit clause on return shape) would improve scanability.

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?

There is no output schema, so the description carries the burden of describing the return value; it says 'return the PDF' and mentions warnings, but never indicates how the PDF is delivered or how warnings are surfaced in the response. Combined with no differentiation from render_pdf, an agent lacks the information to choose confidently between the two render paths. Metering and idempotency, the hardest behaviours to guess, are well covered.

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 75%, so the schema already documents template, data and csv reasonably well, which sets a baseline of 3. The description earns an extra point by explaining the *effect* of idempotency_key (same key + same data yields the same PDF and is not re-counted), which the bare maxLength=256 constraint does not convey. It does not add further syntax detail for data paths or CSV source keys.

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 opens with a specific verb+resource+result: fill a saved template with data and return the PDF. That is unambiguous about what the tool does. It does not, however, name or contrast itself with the close sibling render_pdf (or preview_template), so an agent must infer the division of labour from sibling names alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when this tool is appropriate (you have a saved template with data/CSV and want the final PDF) and it clarifies retry semantics via the idempotency key. But it never states when to prefer it over preview_template or render_pdf, which are the obvious alternatives in the sibling list. Usage guidance is present but inferential rather than explicit.

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=false and destructiveHint=true, and the description meaningfully supplements them: it discloses optimistic concurrency control, the exact conflict signal, and the partial-update contract. It never says that supplying body/html/markdown replaces the entire document irreversibly — that is implied by "replace the document" but not spelled out as a warning.

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 short sentences, front-loaded with the operation and immediately followed by the required concurrency input and the conflict outcome. No restatement of the tool name or schema details, and every clause carries distinct 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 6-parameter mutation with a nested body object and no output schema, the description covers the required inputs, the failure mode, and the update semantics adequately. Gaps are the destructive nature of document replacement and what to do after a conflict (re-read with get_template); otherwise an agent can call this 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%, so the schema baseline is 3; the description earns above that by adding conflict semantics to base_revision ("the revision you read; a newer revision answers template_version_conflict") and the omit-to-keep rule that governs name, body, markdown, and html. It adds no guidance on choosing between the three document-input parameters (body vs markdown vs html), which the schema only hints at.

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?

"Change a template" states a specific verb and resource, and the follow-up sentences sharpen it into a partial-update operation on a document plus name. It does not name any sibling (create_template, delete_template, preview_template) to draw the boundary, so it falls short of a 5.

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 preconditions for calling: you must send base_revision, the revision you actually read, or the call answers template_version_conflict. The omission rule ("what you leave out stays as it was") tells the agent not to resend untouched fields. There is no explicit routing to alternatives such as preview_template before saving or get_template to re-read after a conflict.

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