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

Annotations already cover the safety profile (not read-only, idempotent, non-destructive), and the description adds useful constraints beyond that: the 8 MiB per-attachment ceiling, the requirement to pair with embedFonts:true for a valid PDF/A-3 claim, and that strict:true will fail rather than warn. It does not say what happens on size or strict failure in terms of error surfaces, but the added operational context is substantive.

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 paragraph, front-loaded with the identity and intended use case, then the critical caveats (size limit, embedFonts pairing), then the read-back pointer and the note that shared options behave as on other document tools. No sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 20-parameter creation tool with an output schema and full schema coverage, the description supplies exactly the non-schema-critical knowledge an agent needs: when to choose it, the font-embedding prerequisite for compliant output, the per-file size cap, and where to read attachments back. Nothing essential is left implicit.

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 the 8 MiB attachment size limit (not in the schema) and the Factur-X recipe (single XML attachment, relationship 'Source', mimeType application/xml) that tells the agent how to fill the required attachments array for the most common case. The blocks parity note with generate_basic_pdf is also useful cross-tool parameter context.

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 output type (PDF/A-3b with embedded files) and names the concrete use cases (Factur-X / ZUGFeRD e-invoices, machine-readable side-files), so the agent can distinguish it from generate_basic_pdf and the other document-producing siblings without reading the schema. The 'the tool for X' framing makes the resource and scope 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?

Gives clear selection context (use this when a PDF must carry embedded side-files, e.g. Factur-X) and names a follow-up tool explicitly ('Read them back with extract_attachments'). It stops short of an explicit when-not rule contrasting it with generate_basic_pdf for ordinary documents, which would have made it a 5.

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 (destructiveHint=false, idempotentHint=true, openWorldHint=false), and the description adds real behavioral context beyond them: the result is a single-page PDF, `data` must be raw (never pre-encoded), and ecLevel should be 'H' for print. It does not discuss outputMode/file sandbox or error escalation, which keeps it below a 5.

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 format taxonomy, then the critical `data` caveat, then a concrete call example — every clause carries information and 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?

For a 26-parameter tool with full schema coverage and an output schema, the description focuses correctly on what is distinctive (barcode creation, single page, raw payload) and delegates shared options to 'as on every document tool'. A note on outputMode defaults or the returned artifact would make it fully self-contained.

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 meaningfully enriches the two most important parameters: it explains the format enum semantics beyond the schema's terse labels and warns that `data` is the raw payload that must not be pre-encoded, plus ecLevel guidance not fully captured in 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 ('Single-page PDF with a barcode') and immediately enumerates the supported symbologies with their intended payloads, so an agent can distinguish this from generate_basic_pdf or other document builders 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?

Gives clear per-format selection guidance (qr for URLs/vCards, code128 for ASCII SKUs, ean13 for 12-13 digits, datamatrix for dense industrial marks, pdf417 for ID/boarding passes) with constraints like the 4296-char limit and auto-checksum. It stops short of naming an alternative tool or stating when not to use it, so it is strong but not fully routing.

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, idempotentHint=true and destructiveHint=false, but the description adds substantive behavior beyond them: alt text is auto-generated when omitted, /Figure tagging, cross-field engine rules surfacing as CHART_ERROR with the remedy, and the PDF/A requirement (pdfA + embedFonts:true, plus print/metadata/creationDate notes). That is real operational context an agent needs before calling a 37-parameter generator.

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 and chart types are front-loaded and almost every clause carries information, so there is little waste. However, the whole description is a single run-on paragraph that mixes chart-feature semantics with PDF/A, print and metadata concerns, producing a dense wall of semicolon clauses that is hard to scan before a call.

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 100%-covered schema carries the per-field detail. The description covers the headline capabilities and the composition/PDF-A constraints, which is sufficient for a tool of this complexity, though it does not mention pagination/sandbox expectations for outputMode beyond what the schema says.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description earns the extra point by explaining cross-parameter coupling that the flat schema only states locally: per-series xValues must pair with xAxis.type 'linear'|'time', the secondary axis is engaged only via axis2 + series yAxis:'right', and pie/donut accept exactly one series. Those are integration-level semantics rather than restatements.

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 ('Add native vector chart') immediately qualified by what it produces ('Single-page PDF with a native vector chart ... pure path operators, no raster') and an enumerated chart-type list that an agent can match against a request. It also routes the agent to the sibling case ('Inside a longer document use a 'chart' block in generate_basic_pdf'), so add_chart is clearly distinguishable from generate_basic_pdf.

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 alternative and the condition that selects it: standalone one-chart PDFs here, embedded charts via generate_basic_pdf's 'chart' block in longer documents. It also states form constraints (pie/donut take exactly one series). It does not spell out when the tool should not be used at all (e.g. raster image charts), so it stops short of full when/when-not coverage.

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=false, so the safety profile is covered. The description adds useful context beyond that: this produces a brand-new document rather than mutating an existing one, and it names the correct pathway for existing forms. It doesn't discuss permissions or caching, but with annotations carrying the safety load that is acceptable.

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 front-loaded sentences with the creation semantics first and the routing rule second. The parenthetical use-case list is mild padding and 'as on every document tool' is vague delegation, keeping it just under a perfect score.

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 21 parameters are fully schema-documented. For a complex creation tool the description covers the key agent decision points (what it makes, where the alternative tool lives) and delegates the shared option details appropriately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description lists the field types ('text fields, text areas, checkboxes, radio buttons, dropdowns') and characterizes them as use cases (data capture, surveys, fillable templates), but adds no syntax or format detail beyond what the schema already documents.

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 ('New PDF with an interactive AcroForm') and enumerates the field types it can build. The explicit 'New PDF' framing distinguishes it from siblings like fill_form/read_form_fields 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 routing rule: 'To fill or flatten an EXISTING form use read_form_fields + fill_form.' That names the alternative and the condition selecting it. However, it doesn't cover when-not-to-use for other scenarios (e.g., adding fields to an existing document), so it stops short of a full 5.

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 (idempotent, non-destructive), the description discloses real behavioural traits: fonts are always embedded so `embedFonts` does not exist here, input is NFC-normalised, newlines split paragraphs, and BiDi/Arabic joining/shaping are automatic. These are non-obvious engine behaviours an agent could not derive from the 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?

A single dense paragraph, front-loaded with the script inventory before mechanics. Every clause carries information (script list, aliases, emoji/math, BiDi, NFC, newline behaviour), though the parenthetical script enumeration is long 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?

For a 23-parameter tool with an output schema, the description correctly focuses on the international-text differentiators and delegates the shared document options (PDF/A, print, metadata, creationDate) to 'as on every document tool'. That delegation assumes cross-tool documentation the agent may not have, which is the only gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already carries parameter meaning, and the description mostly restates the `lang` semantics (single code, comma list, array of mixed runs) that the schema documents in full. It adds the useful note that the tool has no `embedFonts`, but little else 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 specific verb+resource and scope: rendering PDF text across 27 named scripts, colour emoji and math, with BiDi/shaping/normalisation details. It implicitly distinguishes itself from generate_basic_pdf by positioning this as the international/multilingual entry point, but never names that sibling explicitly.

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?

Usage is only implied: an agent reads the script list and infers 'use this when text is non-Latin'. There is no explicit when-to-use versus generate_basic_pdf, and no statement of what happens (or which tool to use) if the input is plain ASCII. Adequate but leaves selection 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 only flag openWorldHint and non-idempotence; the description adds the substantive behavior: incremental update with existing /DSS merged, network gated on PDFNATIVE_MCP_REVOCATION + allow-list with REVOCATION_NOT_CONFIGURED otherwise, and the fact that offline mode performs zero network I/O. These are the operational details an agent needs before invoking.

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: the PAdES B-LT action leads, then the ladder, then mode semantics, then constraints. Every sentence carries information, though the heavy parenthetical/env-var stacking makes it harder to scan than it could 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?

With an output schema present, return values need not be described, and the description covers what remains: prerequisites, mode selection, network configuration requirements, and failure conditions. Nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description nonetheless adds value beyond the schema by framing mode 'online'/'offline' as a network-vs-no-network tradeoff with named env vars and by explaining that extraCertificates complete chains the CMS does not carry.

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 ('embed a Document Security Store (/DSS + per-signature /VRI)') and pins the exact spec level (PAdES B-LT). It also situates itself against siblings by naming the ladder (sign_pdf → add_ltv → timestamp_pdf), so an agent can place it without opening other 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?

Explicitly states when to use it (ladder step 3, after signing with profile:'pades', before timestamp_pdf) and when each mode applies: 'online' fetches via the operator revocation provider, 'offline' embeds caller-supplied DER with zero network. Prerequisites are given too: ≥1 signed signature and unencrypted PDFs only.

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?

Though annotations declare non-readOnly/non-destructive, the description adds substantial behavioral context beyond them: embedFonts adds ~0.3 MiB, creationDate omission causes byte-differences across calls while pinning it gives deterministic output, and autoFitColumns makes output non-byte-deterministic. These are non-obvious traits that meaningfully inform invocation.

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 purpose and constraint in the opening sentence, followed by the alternative routing and a compact option summary. Given 36 parameters, the length is justified, though the option-name enumeration is somewhat redundant with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation. The description covers purpose, the sibling alternative for longer documents, and PDF/A pairing; with 100% schema coverage the remaining parameter detail is delegated appropriately. Some behavioral nuance could still be richer, but it is complete enough to call 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 description coverage is 100%, so the schema already carries the parameter semantics. The description's smart-table option list (wrap, repeatHeader, zebra, caption, etc.) largely restates what the schema documents, adding only marginal value over the structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb-resource pairing ('Tabular PDF report from `headers` + `rows`') with a concrete constraint (rows the same length), and later names the sibling alternative (generate_basic_pdf's 'table' block) for longer documents. It is clear, though the core purpose arrives without an explicit action verb and is partly buried under the feature enumeration.

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

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

It gives an explicit routing condition: 'Inside a longer document use a "table" block of generate_basic_pdf instead,' which tells the agent when to prefer the sibling. It also notes 'Pair with embedFonts=true for a valid PDF/A claim.' No explicit when-not/exclusion list beyond these, but the context is clear.

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?

Discloses behavior well beyond annotations: non-destructive incremental update preserving original bytes, VISUAL OVERLAY ONLY semantics (covered text remains extractable — critical for anyone who might assume redaction), and the encrypted-source error code with remediation. Annotations declare idempotent=true and destructive=false, consistent with the description.

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: purpose, non-destructive guarantee, type list, coordinates, then the critical visual-only caveat and error handling. A bit packed but every clause carries information; 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?

Given the output schema exists, return values need not be explained. The description covers mutation semantics, coordinates, type-specific fields, error handling for encrypted sources, and the crucial non-redaction caveat — everything an agent needs to invoke 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 baseline is 3. Description adds derivative value by summarizing type-specific requirements (line needs start/end, each needs page+rect) and the page-0-based convention, though the schema itself documents these in detail.

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 (append) and resource (markup annotations), enumerates the annotation types supported, and distinguishes the tool from siblings like generate_basic_pdf or inspect_pdf by naming the ISO spec section.

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 handles the encrypted-source case by pointing to decrypt_pdf first via the ENCRYPTED_SOURCE error. The 'non-destructive' framing clarifies that this is for overlay markup, but it doesn't contrast against sibling tools like fill_form or add_table for agent routing.

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?

Discloses non-obvious behavioral traits beyond the annotations: the page tree is rebuilt and signatures/AcroForm are DROPPED, plus "Never cached". Annotations only give the generic read/write/idempotency profile; the lossy-output caveat and the caching behavior are real added context. No contradiction with destructiveHint=false, since the source PDF is not modified.

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 dense sentences with the core action first, the lossy caveat second, and the alternative-route guidance last. Every clause carries information; nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation. With algorithm support, password rules, output caveats and the read-only alternative all covered, an agent has everything needed to 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% and the schema already defines password eligibility, outputMode sandboxing and outputPath requirements. The description's "given `password` (user or owner; empty user password needs none)" largely restates the schema, so the baseline 3 applies rather than extra credit.

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 ("Emit an UNENCRYPTED copy of an encrypted PDF") and scopes it precisely with the supported cipher list (RC4 V1–V4, AES-128, AES-256). It is immediately distinguishable from encrypt_pdf and from the read-only siblings named later.

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: "To merely READ an encrypted PDF pass `password` to inspect_pdf / extract_text / extract_attachments / read_form_fields instead." It also states when the password may be omitted (empty user password), so both use and non-use conditions are covered.

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 description goes beyond the annotation set and provides crucial behavioral context: the draft is never submitted, a human files it, no GitHub write path exists, policy violations raise GOVERNANCE_VIOLATION, and the agent must present output and then STOP. This is exactly the kind of non-obvious behavior an autonomous agent needs.

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 compact yet information-dense. Critically, it front-loads the key constraints (LOCAL, NEVER submit, HITL) and includes the procedural end state ('present the draft AND the report to the user, then STOP') with no wasted words.

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 11 parameters, nested reproduction object, output schema, and annotations, this description still closes all important gaps: the governance policy, violation behavior, output modes, human review step, and stop condition. An agent has enough to invoke the tool and interpret its guidance 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?

Even though the input schema describes every parameter thoroughly, the description adds meaningful behavioral requirements: duplicateSearchPerformed:false triggers a GOVERNANCE_VIOLATION, and outputMode 'file' writes a .md file. These enrich the interpretation of the parameters beyond their simple schema definitions.

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 clearly states the action ('Produce a LOCAL GitHub issue draft + compliance report'), the resource ('for pdfnative / pdfnative-mcp'), and the critical boundary ('NEVER submit it'). It is fully differentiated from the PDF-manipulation siblings by the explicit issue-drafting scope.

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 clearly establishes when to use the tool: when an issue draft is needed under the Human-In-The-Loop contract and must not be submitted. It also tells the agent it does not provide a GitHub write path, implying it should not be used for actual issue submission, though no explicit alternative tool is 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?

Annotations already carry the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds real substance: PNG without an alpha channel, base64 input, and that PDF/A, print, metadata and creationDate options behave as on every other document tool — a useful cross-tool parity signal. It does not restate the deterministic/byte-identical behavior that creationDate pinning implies.

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 compact sentences, front-loaded with the artifact and its constraints before the routing rule. Every clause earns its place; the only slightly loose element is the trailing cross-reference to 'every document tool', which is terse but a bit hand-wavy about where those options are documented.

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 27-parameter tool with full schema coverage, an output schema and annotations, the description only needs to frame the artifact and route the agent, which it does. The complex regimes it inherits (PDF/A, PDF/X, print production, encryption, typography) are covered by the schema and sibling docs, so nothing essential for a correct call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 27 properties in depth. The description's mentions of base64, PNG-without-alpha, caption and render width/height merely echo what the schema states, adding no syntax or format detail beyond it. Baseline 3 is correct when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('PDF with one embedded JPEG or PNG') plus the optional caption and render width/height, so the output artifact is unambiguous. It also names the sibling to use instead ('image' block of generate_basic_pdf) for longer documents, letting an agent distinguish embed_image from generate_basic_pdf 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?

Explicit routing rule with condition: 'Inside a longer document use an "image" block of generate_basic_pdf instead.' This names the alternative and when to prefer it. It offers no other usage context (e.g. when PDF/A or print options matter for this tool), so it stops short of a full when/when-not map.

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 by disclosing the destructive side-effects: signatures and AcroForm are DROPPED, only URI links kept, and results are never cached. These are exactly the consequences an agent must know before invoking, and they are not derivable from the readOnly/destructive/idempotent hints.

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 front-loaded with the key outcome and CAVEAT clearly flagged. Semicolon-heavy phrasing packs a lot into two sentences; everything earns its place, though the first sentence is slightly run-on.

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 algorithm choice, password roles, permissions, output modes, rotation, and the signature/AcroForm drop caveat. With an output schema present, return values need not be described, so nothing an agent needs 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 beyond the schema by explaining the interplay: ownerPassword is required, userPassword is the open password, permissions map to the four flags (default allowed), and `password` enables rotation of an already-encrypted source.

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 (Encrypt) applied to a specific resource (an existing PDF) with the exact handler and algorithm set (AES-128/AES-256, RC4 never emitted). An agent can distinguish this from decrypt_pdf and sign_pdf 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?

Gives clear situational guidance: rotate a password by passing the current `password`, and 'encrypt BEFORE signing' due to the page-tree rebuild. It does not explicitly name the alternative (decrypt_pdf) or state when not to use it, so it stops short of full when/when-not routing.

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 idempotentHint, and the description reinforces this with 'Read-only extraction'. It adds valuable behavioral details beyond annotations: default payload inclusion, metadata-only probing, password handling, and token-frugal summary mode. These add meaningful context without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three tightly-worded sentences with no fluff. The core action is front-loaded (read-only extraction), key formats are named in the first sentence, and the remaining sentences efficiently cover optional behaviors and parameter interactions.

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 tool has a high-quality output schema, rich parameter descriptions, and complete annotations, the description covers the necessary behavioral context: file selection, payload vs metadata probing, encrypted sources, and response verbosity. Nothing appears missing for an agent to correctly invoke this 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 schema already provides 100% parameter coverage with detailed descriptions, so the baseline is 3. The description adds concise semantic layer by explaining the practical intent of includeData:false as metadata-only probing and verbosity:'summary' as token-frugal. It also hints at the relationship between filename and single-file selection, complementing 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 clearly identifies a specific verb-object pair ('Read-only extraction') targeting embedded files in PDFs, including recognizable formats like PDF/A-3 and ZUGFeRD. This distinguishes it from sibling tools such as add_attachment and extract_text without ambiguity.

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 provides clear usage context: extracting embedded files from a PDF, including how to select a single file, probe metadata only, handle encrypted sources, and save tokens. It stops short of explicitly naming alternative tools or stating when not to use this tool, but the context is strong enough for an agent to route correctly.

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 read/write/idempotency hints, but the description adds concrete lossy behavior: signatures, AcroForm, and XMP are dropped; boxes are kept; URI links are preserved unless dropAnnotations. It also discloses that output is unencrypted unless `encrypt` and that encrypted sources need `password`.

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 compact clauses front-load the core behavior and bury constraints in parentheticals with minimal waste. It is dense but each sentence carries real information; slightly terse cross-references keep it from a full 5.

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 not be explained, and the description covers the mutation profile, source-encryption handling, output-encryption default, annotation retention, and the sibling alternative. Nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter, and this is the baseline case. The description reiterates `pages`, `password`, `encrypt`, and `dropAnnotations` but adds little syntax or constraint detail beyond what the schema provides.

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+resource: keep a `pages[]` subset in ONE fresh PDF, with 0-based ordering semantics. It also discriminates from the sibling split_pdf by naming the multi-document case as its opposite, so the agent can distinguish it 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?

It explicitly routes the agent: 'Need several documents? Use split_pdf.' It also constrains input handling ('arbitrary pages[] subset') and references merge_pdfs for shared caveats, giving clear when-to-use context.

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, idempotent, non-destructive), and the description goes well beyond them: `extractable` is false only on ENTIRE U+FFFD decoding with extractableReason, ActualText/tagged-content returns SOURCE text in logical order, untagged RTL/Indic returns glyph-draw order, encrypted sources yield PASSWORD_REQUIRED/PASSWORD_INVALID, and maxTextLength overflow fails with OUTPUT_TOO_LARGE. This is unusually rich behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and core extraction semantics are front-loaded and no sentence is pure filler, but the paragraph is dense and heavily backticked, mixing contract-level guarantees (ActualText ordering, error codes) with implementation detail. Slightly over-stuffed for a single description, though 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?

An output schema exists, so return shapes need not be re-explained, yet the description still clarifies the semantic meaning of `extractable`/`extractableReason`. With encryption handling, memory-bound behavior, and token-frugal options all covered, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the PASSWORD_REQUIRED/PASSWORD_INVALID error outcomes for `password`, the extractableReason semantics tied to extraction, and the interplay of verbosity:'summary' with the returned fields. It adds real inter-parameter behavior rather than restating field docs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Plain-text extraction' returning pages[] + fullText) and implicitly distinguishes itself from siblings like extract_pages, extract_attachments and inspect_pdf by naming text extraction and its decoding mechanism (ToUnicode CMap, /Differences). An agent can identify what it does 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?

Gives clear conditional guidance: pass `password` for encrypted sources, use includeRuns:true for positioned runs, verbosity:'summary' for token frugality, and prefer generating with pdfA when faithful extraction of complex scripts matters. It does not explicitly contrast with the closest sibling (extract_pages) or state when *not* to use it, so it stops short of full routing.

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

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

Goes well past the annotations by disclosing that writes are incremental so prior signatures stay valid for their revision, that flatten.drops the interactive layer, that unknown field names raise FORM_FIELD_NOT_FOUND unless onUnknownField:'ignore', that signature fields cannot be filled (FORM_UNSUPPORTED), and that encrypted sources need a password. These are exactly the behavioral traits an agent needs and none are derivable from readOnlyHint/idempotentHint.

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?

Effectively four dense sentences with no filler; the operation and its alternative are front-loaded and error behavior is packed into terse semicolon clauses. The telegraphic compression (backticked terms, arrow notation) costs a little readability, 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 an 8-parameter mutation tool with a nested values object and an output schema, the description covers scope, alternatives, mutation semantics, error codes, security (encryption) and the incremental-update guarantee. Return values need not be explained 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 already 100%, so baseline is 3, but the description adds real meaning: the values map semantics (fully-qualified name → string/array/boolean/export state), the pure-flatten shorthand, and the signature-field exclusion. It omits explaining outputMode/outputPath sandbox behavior, which lives only in 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 (fill and/or flatten) on a specific resource (the AcroForm of an EXISTING PDF) and explicitly contrasts with the sibling that creates one (add_form). An agent can distinguish this from add_form and read_form_fields 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 add_form as the alternative for creating forms and states the selection condition ('EXISTING PDF'), plus clarifies that flatten with no values is a pure flatten. It does not explicitly route to read_form_fields for discovery in the description itself (though the schema does), so it stops just short of full when/when-not coverage.

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, destructiveHint=false, idempotentHint=true and openWorldHint=false, so the safety profile is largely covered. The description adds compliance-state consequences (what a valid PDF/A claim requires) and structural notes (block bodies mirror the dedicated tools), but says nothing about output mode behaviour (inline base64 vs sandboxed file write), the pdfA/encryption exclusivity, or the random-vs-deterministic output caveat — all material for a 27-parameter generator.

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 block inventory, then the routing rule, then the option map — the three things an agent needs in priority order. Given the scope of the tool, every clause carries information; there is no filler or restated title.

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 and the input schema is exhaustively documented, so return-value detail is unnecessary. The description covers routing and the major option families, and the block inventory matches the schema's oneOf variants; it stops short only on output delivery (outputMode/outputPath) and the pdfA/encrypt exclusivity, which matter 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 description coverage is 100%, so the per-parameter text is already complete and the baseline is 3. The description earns above baseline by grouping the 27 parameters into functional clusters (compliance, navigation/presentation, print, metadata, determinism) and asserting cross-parameter pairings, which is orientation an agent does not get from reading 27 independent schema entries.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb+resource (multi-page PDF) and enumerates exactly what can be composed from ordered blocks, naming every block kind. It explicitly positions itself against siblings: 'DEFAULT for any document; use the dedicated tools only for a standalone artefact', making it unmistakable that this is the general-purpose document builder rather than add_table/add_chart/embed_image.

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 guidance: default for any document, dedicated tools only for standalone artefacts, add_attachment for embedded files, add_international_text for non-Latin scripts. It also gives conditional guidance for compliance flags ('pdfA + embedFonts:true for a valid PDF/A-1b/2b/2u/3b claim') and for navigation/presentation options, which is when-to-use at the parameter level.

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 read-only/idempotent/non-destructive, so the description's 'Read-only, deterministic' is partly redundant. However it adds genuine behavioral value: the dry run shares the builder's pagination planner and includes toc blocks, guaranteeing page-count parity with generate_basic_pdf — non-obvious behavior beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose ('Pagination preview WITHOUT generating a PDF'), followed by output shape, parity guarantee, and a token-efficiency tip. Dense but every clause earns its place, though the em-dash-heavy run-on phrasing slightly hurts readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present the description needn't explain return values, and the annotations cover the safety profile. Given the 13-param complexity, it still tells the agent what the tool is, when to reach for it, how its inputs mirror generate_basic_pdf, and how to keep calls cheap — nothing an agent needs is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it enumerates which inputs move a block (title, footerText, pdfA, normalize, embedFonts, pageSize, margins, header/footerTemplate) and directs the agent to reuse generate_basic_pdf's arguments, plus a token-frugal recipe (verbosity:'summary', fields:['totalPages']).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource (pagination preview / inspect layout) and explicitly frames it as a dry run that does NOT generate a PDF, immediately distinguishing it from generate_basic_pdf. It also names the return shape (page count, block page/x/top/width/height in points), so an agent knows exactly what it produces.

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 clear usage context: pass the same inputs you would give generate_basic_pdf and the page count will match, because both share the pagination planner. The alternative (generate_basic_pdf) is implied rather than explicitly named as the non-preview path, and there are no explicit when-not-to-use exclusions, so it falls 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.

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: encrypted sources require a `password`, `check` returns only requested keys plus a `checksPassed` aggregate, and the tool is deliberately token-frugal via verbosity/fields. Nothing about failure modes or limits beyond that, hence not a 5.

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: the core output shape comes first, optional flags next, encryption and token notes last. Backtick-heavy jargon makes it terse rather than skim-friendly, but every clause carries 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 an 8-parameter inspection tool with an output schema, the description covers everything an agent needs: scope, field/claim distinction, CI-mode behavior, password handling and compactness controls. Return values are also briefly mapped even though the output schema carries 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% and the description largely restates what the schema already documents (check semantics, signatures/pages flags, verbosity contents). It adds little parameter meaning beyond the schema, though the 'composes after verbosity' projection ordering and token-frugal framing have some value.

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 precise verb+resource ('Read-only facts about a PDF') and enumerates exactly which facts are returned, then explicitly separates what it does NOT judge ('the claim, not its validity — use veraPDF for that'). This lets an agent distinguish it from validate_pdf and verify_pdf 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?

Clear about context: it routes validity questions to veraPDF/verify_pdf and frames the `check` option as a CI assertion workflow. It does not, however, give an explicit when-to-use-this-instead-of-verify_pdf/Sibling routing sentence for the common 'is this signed and valid?' question, which the schema partially covers.

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

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

Far exceeds the annotation bar: it discloses what is destroyed (signatures, AcroForm, XMP/PDF-A claim), what survives (page boxes, /UserUnit, URI links), error codes (PASSWORD_REQUIRED, PASSWORD_INVALID, OUTPUT_TOO_LARGE, SECURITY_VIOLATION) and two distinct size guards. Annotations only say it is not read-only and is idempotent, so the description carries the real behavioral load.

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 sentences, front-loaded with the core operation before the caveats. Dense but every clause (what survives, error codes, guards) earns its place; the inline error-code tokens make it slightly less scannable than an ideal definition.

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 encryption, annotation handling, sandboxed file output, and size limits — everything an agent needs to invoke this 7-parameter nested-object tool 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 baseline is 3, but the description adds genuine meaning: `password` applies to every encrypted source, output is unencrypted unless `encrypt` is set, and it explains the layering of `maxOutputSizeBytes` (256 MiB assembly) against the separate 50 MiB output cap. Still, per-parameter syntax largely lives in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource plus scope: 'Concatenate 2–50 PDFs into one fresh, self-contained document.' That cleanly separates it from siblings like split_pdf, extract_pages, or validate_pdf.

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 clear operating conditions (encrypted sources need a password, output is unencrypted unless `encrypt`, page-tree rebuild side effects) and even routes PDF/A re-declaration to the generating tools. It stops short of naming a specific alternative sibling or stating explicit when-not-to-use cases.

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 readOnly=false, idempotent=true, destructive=false, so the description carries real weight: it discloses that signerName/reason/location/contactInfo/signingTime are frozen into /Sig at placeholder time and sign_pdf cannot rewrite them later, and that the unsigned output is not yet conformant PDF/A because /Contents is empty. These are non-obvious behavioral consequences not derivable from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical framing (what it is, that it is optional, that sign_pdf auto-injects) comes first, and the rest is a tight enumeration of reasons to use it. Sentences are dense and information-packed for a 29-parameter tool, though the parenthetical lists make it slightly harder to scan than an ideal definition.

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 need not document return values, and with annotations covering the safety profile it mainly needs to convey the placeholder-specific semantics — freezing, nonconformance, and sizing. It does all of that, plus points to shared options, so an agent has everything needed to decide whether and how to call it.

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 baseline is 3, but the description adds genuine selection guidance beyond the schema: which situations justify placeholderBytes (large RSA keys, long chains), what reserveTimestamp is for, how pageIndex pins the widget, and the PAdES role of subFilter. It also forward-references cross-cutting options (PDF/A, print, metadata, creationDate) as shared document-tool conventions. It does not attempt to restate all 29 parameters, which 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?

States a specific verb and artifact: creates a new PDF carrying an unsigned /Sig placeholder explicitly intended for a LATER sign_pdf call. This clearly separates it from sign_pdf and from generate_basic_pdf, so the agent knows this is a preparatory step, not the signing step.

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 declares itself OPTIONAL and names the alternative that makes it unnecessary ('sign_pdf auto-injects one'). It then enumerates the concrete reasons to use it anyway: sizing placeholderBytes for >4096-bit keys, reserveTimestamp for an RFC 3161 token, pinning pageIndex, choosing the PAdES subFilter, or shipping the placeholder separately. Both when-to-use and when-not-to-use are covered.

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 mark it as read-only and idempotent, and the description adds useful behavior details: password handling for encrypted PDFs and a token-frugal 'summary' response mode that returns only fieldCount. It does not disclose every edge case, but the core behavioral traits are well covered by the annotations and description together.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded, and every sentence earns a place. The long first sentence packs critical output attributes efficiently, followed by short, actionable notes about fill_form, password, and verbosity. There is no excess filler or repetition.

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 annotations, the rich parameter schema, and the presence of an output schema, the description covers the remaining necessary context. It tells the agent when to call it, how to handle encrypted files, and how to customise response size, which is complete for a read-only 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?

All four parameters already have thorough schema descriptions, so the baseline is met regardless. The description briefly mentions password and verbosity behavior, but those details are largely restating what is already in the schema. It adds little beyond what the input schema conveys.

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 clearly states a read-only list of AcroForm fields and enumerates what is returned: name, type, value, flags, options, and widget placements. It also ties the operation to the sibling fill_form tool, so its role in the workflow is unmistakable.

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 explicitly says 'Call it BEFORE fill_form to learn the names,' giving the agent a concrete, actionable use case and emphasizing that this tool is a prerequisite for fill_form. It does not mention when not to use it or provide other alternative tools, so it lacks full exclusionary guidance.

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