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

Annotations already cover safety (readOnlyHint false, idempotent true, destructive false), so this is a non-destructive idempotent create. The description adds real behavioral facts beyond them: the ≤8 MiB per-attachment limit, that embedFonts:true is required for a valid PDF/A-3 claim, and that strict:true will fail otherwise. It does not mention that attachments auto-enable PDF/A-3 (that lives only in the schema) or what happens on soft failures.

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 tight clauses, front-loaded with the artifact and the primary use case before secondary constraints. Dense but every sentence carries information; only the trailing 'creationDate options as on every document tool' 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 22-parameter tool with an output schema, the description correctly focuses on what the schema cannot tell the agent: the compliance envelope (embedFonts/strict interlock), the attachment size cap, and reuse of the sibling's block schema. Return values are covered by the output schema, so nothing essential 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 every parameter is already documented in schema, and the baseline is 3. The description adds modest cross-reference value — blocks shares generate_basic_pdf's schema and print/metadata/creationDate behave as on other document tools — but supplies no semantics for the attachment-specific fields (filename, relationship, dataBase64) that justify the tool.

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?

Names a specific verb and artifact: a PDF/A-3b document with embedded files, and pins the flagship use case (Factur-X / ZUGFeRD with one XML attachment, relationship 'Source', mimeType application/xml). It also distinguishes itself from siblings by delegating page content to generate_basic_pdf's block schema and pointing to extract_attachments for the inverse 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?

Gives a clear when-to-use signal: e-invoices or any PDF carrying machine-readable side-files, with a per-file size cap. It routes to extract_attachments for readback and to generate_basic_pdf for the block schema, but never states the obvious exclusion (use generate_basic_pdf if you have no attachment to embed), leaving that to the required-parameter schema.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=true), so the description does not need to repeat it. The description adds meaningful behavior: it produces a single-page PDF, can return base64 or write into the sandbox, makes encrypt exclusive with PDF/A, and notes that omitting creationDate yields different bytes each call. It does not cover auth or rate limits, but those are unlikely to matter here.

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 a single front-loaded paragraph that moves from purpose to format details to a typical call, with no wasted sentences. The final cross-reference to PDF/A, print, metadata and creationDate options is compact and useful, though slightly vague compared with the rest.

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

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

Given a 28-parameter schema with full description coverage, an output schema, and annotations covering safety, the description is complete enough for an agent to invoke the tool correctly for its main purpose. It does not elaborate on every standard document option, but the schema already documents those thoroughly.

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 goes beyond the schema by explaining which formats suit which payloads and by reiterating that data must be raw and never pre-encoded, with a concrete example. It does not explain the many secondary print/typography parameters, but the schema handles those 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?

The description opens with a concrete resource ('Single-page PDF with a barcode') and enumerates the supported symbologies, so an agent can immediately tell what the tool produces. It does not explicitly distinguish itself from siblings like generate_basic_pdf or add_chart, which keeps it 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 useful format-selection guidance (qr for URLs/vCards, code128 for ASCII SKUs, ean13 for 12–13 digits, etc.) and a typical invocation example. However, it never states when to choose this tool over alternatives such as add_chart or generate_basic_pdf, nor when not to use it, so the routing guidance is only implied.

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

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

Annotations establish readOnly=false and idempotent=true for the build itself, but the description adds non-obvious behaviour the schema doesn't state: engine cross-field rules surface as CHART_ERROR with the remedy, a colours-length mismatch is a CHART_ERROR, and tagged /Figure + /Alt is auto-generated when altText is omitted. It also notes PDF/A needs embedFonts:true. Missing is any word on runtime, output size, or the practical consequence of outputMode='file'.

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 front-loaded with the core purpose, which is right, but the body degenerates into a semicolon-and-slash telegraphic wall ('Multi-series, legends, \'nice\' ticks, gridlines, negatives; per-series xValues…') that is hard to scan and mixes chart semantics with PDF/A and print boilerplate. Nearly every clause carries information, yet grouping by concern rather than by punctuation would make it substantially easier to use.

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 39-parameter tool with nested objects, an output schema, and print/PDF-A surface area, the description correctly covers chart-type semantics, colour model, error contract, and accessibility tagging rather than restating obvious fields. It leans on 'as on every document tool' for shared PDF plumbing, which is reasonable shorthand in this sibling set. Print-production interactions with the chart (e.g. that CMYK/spot colours require an intent) are the main thing 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 description coverage is 100%, so the baseline is 3. The description does add a few cross-parameter facts beyond the schema — series[].colors length must equal values.length on every chart type, axis2 is only drawn when a series sets yAxis:'right', spotColours must be declared before { spot, tint } can be used — but most of its parameter content duplicates enum listings and format examples already 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+resource+scope: 'Single-page PDF with a native vector chart (pure path operators, no raster)', then enumerates the nine supported chart types. It also distinguishes itself from the sibling that overlaps most, stating 'Inside a longer document use a \'chart\' block in generate_basic_pdf', so an agent can route between the two without opening a schema.

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

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

Gives real selection guidance inside the tool: 'Pie/donut take exactly one series', scatter requires xValues plus a positional xAxis.type, and axis.scale 'log' is not available for stacked charts. The multi-page alternative (generate_basic_pdf chart block) is named. No explicit when-not to call at all, and no sibling differentiation against add_table or embed_image, so not 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 mark this non-read-only, non-destructive, idempotent and closed-world; the description adds that it builds a new interactive AcroForm and that PDF/A, print, metadata and creationDate options behave as on other document tools. It does not spell out edge behavior such as PDF/A–encryption exclusivity or output-mode mechanics, but those are covered in the schema rather than 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?

Three compact sentences, front-loaded with the core purpose and then routing guidance. Every sentence carries weight; no repetition of schema detail.

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 23-parameter builder with a published output schema and full schema descriptions, the description covers the essential purpose, routing, and major option groups. It does not need to restate return values or every nested parameter, though it could mention required inputs and output mode 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 coverage is 100%, so the schema already documents all 23 parameters, including field-level options. The description adds only the broad field-type list and a pointer to common PDF/A, print, metadata and creationDate options, which does not add syntax or constraints 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?

States a specific verb and resource ('New PDF with an interactive AcroForm') and enumerates the form controls it can create. It explicitly distinguishes itself from fill_form/read_form_fields, so an agent can route creation versus filling 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 explicit when-not guidance: 'To fill or flatten an EXISTING form use read_form_fields + fill_form.' It also names concrete use cases (data capture, surveys, fillable templates) and identifies the common document options, leaving little 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 mark this as a non-read-only, idempotent, non-destructive build, so the description carries real weight and does: fonts are always embedded and embedFonts deliberately does not exist here, BiDi and Arabic joining are automatic, input is NFC-normalised, and newlines split paragraphs. It does not cover output defaults or common failure modes, but the key behavioral exception versus sibling document tools is disclosed.

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 capability is front-loaded, which is good, but the opening sentence is a long run-on with a 32-script parenthetical that bulks it out. The trailing 'PDF/A, print, metadata and creationDate options as on every document tool' is efficient, but overall the block is denser than it needs to 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?

For a 26-parameter, deeply nested tool with an output schema, the description correctly stays on the distinctive surface — scripts, automatic shaping, embedded fonts, lang mixing — and leaves the rest to the rich schema. Nothing essential for a correct first 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 coverage is 100%, so the schema already documents every parameter and the baseline is 3. The description adds a little meaning — lang accepts a single code, comma list or array for mixed runs, and the ha/yo/ig/sw aliases — but most of that is repeated in the lang schema description, so the marginal value is modest.

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: renders PDF text in 32 scripts, COLRv1 emoji and math symbols, with automatic BiDi and shaping. It is clear what this tool produces, but it never names how it differs from the closest sibling, generate_basic_pdf, so the agent must infer the split from the script coverage 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?

Usage is only implied: an agent should pick this when text is non-Latin, emoji or math. There is no explicit when-not or any named alternative, and the only routing hint is 'as on every document tool', which assumes the agent knows the sibling set.

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 annotations, it discloses network gating via PDFNATIVE_MCP_REVOCATION and PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS, the REVOCATION_NOT_CONFIGURED failure, offline zero-network behavior, incremental merging of existing /DSS, and prerequisites (at least one signed signature, unencrypted PDFs only). These details materially help an agent predict behavior and failure modes.

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?

Despite its density, the description is front-loaded with the core operation, then the ladder position, then mode/network details. Every sentence carries operational information about prerequisites, environment variables, or side effects; there is no filler.

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

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

For a complex mutation tool with ten parameters, network dependencies, and a defined workflow position, the description covers prerequisites, mode behavior, environment gating, output handling hints, and incremental merging. An output schema exists, so return-value explanation is not needed here.

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

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

Schema description coverage is 100%, so the input schema already documents all ten parameters, including mode, match, outputMode, and the DER material arrays. The description reinforces mode semantics and offline caller-supplied material but does not add much beyond the schema for parameters such as match or outputPath.

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

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

The description names a specific verb and resource — embed a PAdES B-LT Document Security Store (/DSS + /VRI) — and states exactly what material is added for future verifiers. It distinguishes itself from siblings by placing the tool in the signing ladder between sign_pdf and timestamp_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?

It gives an explicit ordered workflow: sign_pdf with profile:'pades' and timestamp:true, then add_ltv, then timestamp_pdf. It also explains when to use each mode: online for operator-provider fetching, offline for caller-supplied DER material with zero network.

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=false, destructive=false, idempotent=true and openWorld=false, so the safety profile is covered; the description adds the non-obvious constraint that a PDF/A claim requires pdfA plus embedFonts:true. It does not restate contradictions or hidden side effects, and it delegates print/metadata/watermark/creationDate semantics to the shared document-tool conventions rather than spelling them out.

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 sentences, front-loaded with purpose, then the option map, then the sibling routing rule — no filler. The middle enumeration is long but functions as a navigational index into a very large schema, so it earns its space; it could be trimmed slightly.

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 38 parameters, a rich schema and an output schema present, the description correctly focuses on purpose, the table-specific subset, and the sibling alternative while delegating the shared document options ('as on every document tool') and return values to structured fields. Nothing essential for a correct first call is missing, though outputMode/file-writing behavior is only implicitly covered by the delegation.

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 earns more by grouping the table-specific knobs (wrap, repeatHeader, zebra, caption, minRowHeight, cellPadding, cellBorders, cellVAlign, autoFitColumns, clipCells) so the agent knows which of the 38 parameters actually govern table layout. It also flags the cross-parameter pairing 'pdfA + embedFonts:true', which is semantic rather than schema restatement.

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 output (a tabular PDF report) built from named inputs (`headers` + `rows`, equal-length rows), which is a concrete verb+resource+shape. It also distinguishes itself from the sibling `generate_basic_pdf` by pointing to that tool's 'table' block for tables inside longer documents.

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

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

Gives an explicit when-not plus the alternative: 'Inside a longer document use a table block of generate_basic_pdf instead.' That is exactly the routing decision an agent needs between the two document-producing tools.

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 the safety profile (readOnly=false, destructive=false, idempotent=true), and the description reinforces it with valuable detail: incremental update with original bytes preserved, covered text stays extractable, and link rects draw no visible appearance. Minor tension: 'append' semantics mean repeat calls would stack duplicate annotations, which sits awkwardly with idempotentHint=true, though the description never claims call-level idempotence.

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 key constraint (non-destructive, original bytes preserved) is front-loaded and the type list is compact. The middle run-on sentence packing types, requirements, and encodings is dense but every clause carries information; only light reformatting would improve scanning.

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

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

An output schema exists, all four parameters are documented, and annotations cover the safety profile, so the description's job is to cover behavior — which it does: mutation semantics, byte preservation, redaction limitation, and prerequisite decryption. Nothing an agent needs before calling 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 useful cross-parameter meaning by tying fields to types ('line (needs start/end)', 'link (needs url — http:, https: or mailto:)', 'rect is the clickable area') and restating the 0-based page and [x1,y1,x2,y2] rect conventions. It stops short of explaining quadPoints geometry or colour format trade-offs 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?

States a specific verb ('Append markup annotations') and resource ('an existing PDF') plus the exact annotation types supported, which no sibling tool covers. An agent can tell immediately this adds markup rather than editing content, forms, or metadata.

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 encrypted-input case: 'Encrypted sources → ENCRYPTED_SOURCE (decrypt_pdf first)', naming the sibling to run first. It also warns that this is a visual overlay only, so it implicitly excludes redaction-style use, but no other exclusions or alternatives are 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?

Goes well beyond the annotations by disclosing that the page tree is rebuilt and signatures and AcroForm are DROPPED from the output copy, which is exactly the kind of lossiness an agent must know before calling. It also discloses 'Never cached,' a behavioral trait set by neither the annotations nor the schema. The dropped-content caveat does not contradict destructiveHint=false, since the source file is untouched and a new copy is emitted.

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

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

Three tight sentences: format/scope first, the destructive caveat second (flagged with CAVEAT), the alternative routing third. Every clause carries information and the most decision-relevant constraint is front-loaded.

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 four-parameter mutation tool with full schema coverage, annotations, and an output schema, the description covers everything else an agent needs: supported cipher versions, password semantics, output fidelity loss, and the correct sibling for read-only use. Nothing material 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 password (user or owner, omit for empty user password), outputMode, and outputPath in detail. The description's parenthetical about password types largely restates the schema rather than adding new semantics. Baseline 3 is appropriate where 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 ('Emit an UNENCRYPTED copy of an encrypted PDF') and even enumerates the supported encryption schemes (RC4 V1-V4, AES-128, AES-256). This cleanly distinguishes it from encrypt_pdf, inspect_pdf, and the other siblings without opening a schema.

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

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

Explicitly says when NOT to use it and names the four alternatives: 'To merely READ an encrypted PDF pass `password` to inspect_pdf / extract_text / extract_attachments / read_form_fields instead.' It also states the condition (empty user password needs none) for when a password can be omitted.

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 readOnly=false, idempotent=true, destructive=false; the description adds substantive behavior the agent could not infer: validation against zero-dependency and reproduction policy, a thrown GOVERNANCE_VIOLATION on specific violations, and the file-mode requirement for PDFNATIVE_MCP_OUTPUT_DIR. It also resolves the apparent contradiction between 'draft' and a non-destructive write by clarifying nothing is ever submitted.

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 core contract in the first clause and ends with a crisp stop instruction. It is dense—multiple policy references (AGENT_RULES.md, zero-dependency, reproduction policy, duplicateSearchPerformed) are packed into two long sentences—but nearly every clause carries decision-relevant 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?

With 11 parameters (6 required, one nested object), an output schema, and full annotation coverage, the description supplies the missing behavioral layer: no external write happens, validation can throw, and output goes inline or to a sandbox file. An agent has everything needed to call it correctly and to know what to do with the result.

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; the description earns above that by tying specific parameters to behavior—outputMode:'file' writing a .md, and duplicateSearchPerformed:false being a violation trigger. Only targetRepo's documentation-only nature and these hints are restated from the schema rather than adding wholly new 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 verb and artifact: 'Produce a LOCAL GitHub issue draft + compliance report' for a named repo, and explicitly negates the confusing action ('NEVER submit it'). The purpose is unmistakable and clearly disjoint from the PDF-manipulation siblings.

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

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

Gives clear operating context (Human-In-The-Loop contract, .github/AGENT_RULES.md, 'No GitHub write path exists') and a terminal instruction ('Present the draft AND the report to the user, then STOP'). It stops short of naming when to prefer this over alternatives or prerequisites like searching duplicates first, but with no real sibling overlap the guidance is sufficient.

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 mutation (readOnlyHint false), non-destructiveness, idempotency and closed-world behavior. Beyond that, the description discloses format-handling behavior an agent would otherwise discover only by error: PNG without alpha, JPEG 2000 passed through as /JPXDecode, and that PDF/A, print and metadata options are shared with all document tools.

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

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

Three compact sentences, front-loaded with the core output and its image-format constraints. The parenthetical format details and the reference to shared options are dense but earn their place; nothing is redundant with the 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?

For a 29-parameter document builder, the description covers the distinctive parts (image input constraints, placement, the longer-document alternative) and deliberately delegates shared PDF/A, print and metadata options to the documented convention. With an output schema present, return-value explanation is unnecessary.

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 29 parameters are individually documented, so the schema carries nearly all parameter meaning. The description adds only a top-level summary (caption, render width/height, shared PDF/A and print options), which is baseline-level value over 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 first sentence states a specific output (a PDF with one embedded JPEG, PNG or JPEG 2000 image) and names the accepted encodings. It also distinguishes itself from the closest sibling by telling the agent to use generate_basic_pdf's image block for longer documents.

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 routing sentence gives a clear when-to-use-else rule: single image now, embedded image block when the image belongs in a longer document. It doesn't add an explicit exclusion list, but the primary alternative 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?

Goes well beyond the annotations by disclosing the lossy side effect — the page tree is rebuilt, signatures and AcroForm are dropped, only URI links survive — plus that the result is never cached and RC4 is never emitted. This is exactly the pre-call warning an agent needs, since destructiveHint=false alone would not prepare it for losing signatures and form fields.

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

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

Dense but front-loaded: the operation and algorithm come first, then required/optional credentials, then the destructive caveat in a clearly labeled CAVEAT clause. Nearly every clause carries information; only the permissions enumeration lightly duplicates 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?

For an 8-parameter tool with a nested permissions object and an output schema, the description covers the operation, credential model, security caveat, and ordering constraint against signing. Output routing (base64 vs sandboxed file) is left entirely to the schema, which is acceptable given outputMode/outputPath are fully described there.

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, including the password-rotation meaning and the AES variants. The description mostly restates that structure (ownerPassword required, userPassword optional, permission flag list) rather than adding syntax or edge-case meaning, so the baseline applies.

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

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

States a specific verb and resource ("Encrypt an existing PDF") plus the exact handler family (Standard Security Handler) and the algorithm set it can and cannot emit. Its scope is also delineated against the closest siblings: password rotation covers the encrypted-source case that otherwise belongs to decrypt_pdf, and "encrypt BEFORE signing" positions it relative to sign_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 when-to-use conditions: pass `password` to rotate an already-encrypted source, omit it for a plain source, and encrypt before signing. It does not explicitly name decrypt_pdf as the alternative for removing protection, so the exclusion 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 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 say readOnly=false, destructive=false, idempotent=true; the description goes well beyond them by disclosing that signatures/AcroForm/XMP are dropped, boxes are kept, URI link annotations survive unless dropAnnotations, and the output is unencrypted by default. These are exactly the lossy side effects an agent needs before committing a mutation.

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

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

Three tight sentences, front-loaded with the core operation, then caveats, then alternative routing. No filler, and the parenthetical detail is dense rather than padded.

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 encrypt object and an output schema, the description covers the important behavior (lossy conversion, encryption defaults, sandbox-free base64 default). The one weakness is the 'Same page-tree caveats as merge_pdfs' cross-reference, which forces reliance on another tool's description even though the caveats are partially enumerated inline.

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 pages, password, encrypt, dropAnnotations, outputMode and maxOutputSizeBytes in detail. The description's mentions of `pages`, `password`, and `encrypt` largely restate that, adding no syntax or constraint beyond the schema's existing notes. Baseline 3 is appropriate.

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

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

The first sentence states a specific verb-plus-resource with scope: keep an arbitrary `pages[]` subset (0-based, in the given order) in ONE fresh PDF. That immediately distinguishes it from merge_pdfs (combining documents) and split_pdf (producing several files), so an agent can pick it without opening a schema.

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

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

It gives clear routing context: encrypted sources require `password`, output stays unencrypted unless `encrypt` is supplied, and 'Need several documents? Use split_pdf' names an alternative with its selecting condition. It does not explicitly state when NOT to use it relative to merge_pdfs or inspect_pdf, but the positive guidance is strong.

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 is unusually rich about semantics the annotations do not cover: `extractable` is false only when a page decoded ENTIRELY to U+FFFD, extractableReason explains it, /ActualText source-text handling, logical-order behavior for RTL/shaped scripts with the one Thai above-vowel caveat, and per-mode onStreamError outcomes with error codes. That is genuine behavioral context beyond the readOnly/idempotent hints, though the CMap/encoding internals are more implementation trivia than agent-relevant behavior.

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 most sentences carry real information, but it is a single dense paragraph thick with backticks, parentheticals, and low-value internals (Tj/TJ operands, /Encoding /Differences, pdfnative 1.9 version trivia). Splitting the font-decoding internals from the parameter/behavior notes would improve scannability.

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 extraction tool with an output schema, the description covers the failure modes (PDF_PARSE_FAILED, OUTPUT_TOO_LARGE, PASSWORD_REQUIRED/PASSWORD_INVALID), the partial-success case (extractable=false), encoding/ordering edge cases, and the token-frugal path. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already defines every parameter including the onStreamError enum and verbosity modes; the description largely restates these. The only marginal additions are the framing of runs as "positioned runs" for includeRuns and the note that `pages` is 0-based, both of which the schema also carries.

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

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

Opens with a specific verb+resource ("Plain-text extraction") and immediately names the mechanism (decoding Tj/TJ operands via /ToUnicode CMap) plus the outputs (pages[] + fullText). It is clearly distinguishable from mutating siblings like sign_pdf or add_table, though it never explicitly names the closest logical sibling, inspect_layout, even while mentioning positioned runs.

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 implied rather than stated: "includeRuns:true ... Useful for layout-aware extraction" hints at a layout use case, and "Encrypted sources: pass `password`" is a precondition. There is no explicit when-to-use-this-vs-alternatives routing (e.g. vs inspect_layout or inspect_pdf), so the agent must infer.

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 and idempotentHint=true, and the description adds real context beyond them: incremental update semantics that preserve prior signatures for their revision, the error codes FORM_FIELD_NOT_FOUND and FORM_UNSUPPORTED, the signature-field restriction, and password handling for encrypted sources. However, flatten:true 'drops the interactive layer', which is an irreversible effect not reflected in destructiveHint=false; the description discloses it, so the agent is not misled, but the tension between the stated effect and the annotation is left unaddressed.

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?

Single front-loaded paragraph that leads with the verb, the resource and the sibling contrast before dropping into parameter notes. The terse `key`: meaning notation is dense but scannable, and no sentence is filler; only the stacking of many short clauses makes it slightly harder to parse than it needs to 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?

For an 8-parameter mutation tool with an output schema, the description covers the non-obvious risks an agent needs: signature preservation, flatten irreversibility, unknown-field policy, signature-field rejection and encryption. Return values need no explanation given the output schema, though outputMode/outputPath sandbox behavior is left entirely to the schema.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description's parameter notes (string/array/boolean value typing, pure-flatten with empty values, password for encrypted sources) largely restate what the schema already documents. It adds a little by tying onUnknownField and the FORM_FIELD_NOT_FOUND code together, but nonWinAnsi, outputMode and outputPath are not mentioned at all in the description.

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 pair (fill/flatten) against a specific resource (the AcroForm of an EXISTING PDF) and explicitly contrasts with the sibling add_form, which creates one. 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?

The parenthetical '(add_form creates one)' makes the use case explicit: existing forms with fields already present. It also notes 'with no values = pure flatten' as a distinct invocation mode. It stops short of naming read_form_fields as the required discovery step (that hint lives only in the pdfBase64 schema description), so it is clear but not fully routed.

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=false, destructive=false and openWorld=false; the description adds substantive context on compliance behavior — the PDF/A + embedFonts pairing, PDF/X prerequisites, and the exclusivity of encryption with pdfA. It also discloses that bytes vary across calls unless creationDate is pinned, and that encryption produces randomised, never-cached output, which goes beyond the safety hints. Minor gap: outputMode sandboxing and diagnostics behavior live only in 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?

Front-loaded with what the tool does and its routing guidance before the compliance clauses. It is dense and semicolon-heavy — a bulleted block-kind list would scan faster — but with a 30-parameter tool the length is largely earned.

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 tool this large, the description covers the decision-critical parts: default routing, block coverage, and compliance pairings. Remaining detail (outputMode, print boxes, typography, encryption internals) is fully documented in the schema, and an output schema exists, so no return-value explanation is needed.

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% across all 30 parameters, so the schema carries the parameter semantics and the baseline of 3 applies. The description does add real value by noting that the chart block takes the same body as add_chart and that each block kind mirrors a dedicated tool, which helps the agent reuse known shapes.

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 — a multi-page PDF composed from ordered blocks — and enumerates the supported block kinds, so an agent knows exactly what it can build. It also explicitly positions itself against siblings: 'DEFAULT for any document; use the dedicated tools only for a standalone artefact', naming add_table, embed_image, add_barcode, add_form and add_chart.

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

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

Gives explicit routing rules: use this for any full document, use dedicated tools only for standalone artefacts, add_attachment for embedded files and add_international_text for non-Latin scripts. It also states when to reach for pdfA + embedFonts, outline/pageLabels/viewerPreferences/watermark, and points to the shared document-level parameters.

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 description's marginal value is the fidelity guarantee: the dry run shares the builder's pagination planner, including toc blocks, and is deterministic. It could have gone further on limits (image byte caps, chart measurement behavior) but the behavioral profile is well beyond what annotations alone convey.

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

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

Front-loaded with the differentiator, then the contract, then the token-saving tip. Dense but essentially waste-free. Slightly telegraphic phrasing ("Read-only, deterministic." as a fragment) costs a little readability but conveys real 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 16-parameter, nested-schema tool with an output schema, this covers what matters: purpose, fidelity contract, and a cheap output mode. Return-shape detail is correctly delegated to the output schema. Minor gap: no mention of cost/latency or upper bound on blocks when previewing very large documents.

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. The description earns a step above by explaining the semantic invariant tying the parameters together: any input that moves a block (title, footerText, pdfA, normalize, embedFonts, pageSize, margins, header/footer templates) must be mirrored from generate_basic_pdf or the preview diverges. It also names the projection knobs (verbosity:'summary', fields:['totalPages']), which is an efficient-usage cue rather than a restatement.

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?

"Pagination preview WITHOUT generating a PDF" names a specific verb (preview/inspect) and resource (pagination/layout), and immediately disambiguates from the sibling generate_basic_pdf by stating no PDF is produced. The concrete output promise (page count plus page/x/top/width/height per block) lets an agent know exactly what it gets.

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 clear operating rule: pass the same arguments you will give generate_basic_pdf so the page count matches. That tells the agent when this tool is appropriate (pre-flight check before building). It stops short of an explicit "do not call this to produce a file, call generate_basic_pdf for that" exclusion statement.

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?

Goes far beyond the annotations by disclosing page-tree rebuild consequences (signatures and AcroForm dropped, XMP/PDF-A claim lost, page boxes and /UserUnit preserved, URI links retained), the PASSWORD_REQUIRED/PASSWORD_INVALID codes, and two separate size guards (256 MiB assembly, 50 MiB OUTPUT_TOO_LARGE). This is exactly the lossy-side-effect context an agent needs before committing.

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

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

Front-loaded with the core action and dense with useful facts; nearly every clause carries information. The telegraphic, parenthetical style (fragment sentences, inline error codes) is compact but slightly harder to parse than plain prose.

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 7-parameter, nested-schema merge tool with an output schema already available, the description covers the critical unknowns: lossiness of the page-tree rebuild, encryption/password behavior, output destination safety, and both size limits with error names. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds value by tying `password` to all encrypted sources, clarifying that output stays unencrypted unless `encrypt` is set, and explaining dropAnnotations' selective URI-link retention and the assembly-vs-output cap distinction. Remaining nested permission flags are left entirely to the schema.

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