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

Annotations already cover safety (idempotent=true, destructive=false, readOnly=false), so the bar is lower. The description adds genuinely useful behavioral detail beyond the annotations: PDF/A-3 auto-enable via attachment, the strict:true cold fail if embedFonts is not paired, the ≤8 MiB per-file cap, and a read-back pointer to extract_attachments. No contradiction with annotations; this is meaningful supplementary behavior disclosure, though it stops short of explaining exact failure or concurrency 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?

Five sentences, mostly one clause each, front-loaded with the tool's core identity. Every sentence earns its place: the Factur-X use case, the size constraint, the blocks reference, the embedFonts/strict pairing, the read-back pointer, and the note that print/metadata options mirror other document tools. No filler and no restatement of schema details.

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

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

Given the tool's complexity — 19 parameters, nested objects, an output schema, 2 enums — the description plus the fully-described schema leave no critical gap for an agent to call this correctly. The description covers the core semantic decisions (when to use it, how to compose the body, how to get a valid PDF/A claim, where to find the result). Everything else is accurately land cheaply documented in the rich 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?

With 100% schema description coverage, the baseline is 3, but the description adds inter-parameter meaning that the schema prose lacks: it explains the coupling between embedFonts and strict (strict:true fails otherwise), delegating blocks to generate_basic_pdf's schema (saving the agent from guessing the block shape), and it restates the Factur-X attachment convention in the narrative. This is more than the schema alone 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 leads with a specific verb and resource: producing a PDF/A-3 document with embedded file attachments, and pins the canonical use case (Factur-X/ZUGFeRD e-invoices) plus the general case (any machine-readable side-files). It names exact characteristics (one XML attachment, relationship 'Source', mimeType application/xml) that clearly differentiate this tool from the 26 siblings, especially from generate_basic_pdf and extract_attachments. This goes well beyond a restatement of the name or title.

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 gives concrete when-to-use context: 'the tool for Factur-X / ZUGFeRD e-invoices' or any PDF with side-files, and routes the agent to read results back with extract_attachments. It also signals where to find the body schema (generate_basic_pdf). The only gap is the absence of an explicit when-NOT-to-use statement with an alternative (e.g., use generate_basic_pdf when no attachments are needed), which keeps this just shy 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?

Adds useful behavioral context beyond annotations: the result is a single-page PDF, data must be raw ('never pre-encode'), and ecLevel should be 'H' for print. It also flags 'PDF/A, print, metadata and creationDate general options'. It does not contradict the annotations, and annotations already covers failed/crucy/safety characteristics.

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

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

Two dense sentences plus an example: no filler, useful constraints are front-loaded, and the common typic invocation is given before wiring into extra options. Every sentence carries decision-relevant behavior.

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

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

For a 24-parameter tool, the description gives a strong entry point and relies on the very rich input schema for the long tail (encryption, outputMode, PDF/A, footers, etc.). That is acceptable given the schema coverage, but the description could be a bit more explicit about output modes and the full PDF/A family of common options.

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. The description still adds value by mapping formats to practical uses, highlighting 'raw payload, never pre-encode', and reading EAN-13 checksum auto-computation. This eases whether to the Correct parameter choices without repeating every schema field.

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 what the tool does: it creates a single-page PDF containing a barcode, and it maps each supported symbology to a realistic content type. It is specific about the resource and output shape, though it does not explicitly compare against sibling add_* tools like add_image or add_table.

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?

Includes per-format guidance, e.g. QR for URLs/vCards, code128 for ASCII SKUs, pdf417 for ID cards, plus a concrete 'typically' example. It says when to use each barcode format but does not mention when not to use the tool or reroute to a sibling tool.

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 idempotentHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond that: output is a single-page PDF with pure vector paths, pie/donut require exactly one series, errors surface as CHART_ERROR, and PDF/A compliance requires embedFonts. This is strong but not exhaustive; e.g., it doesn't mention default random output unless creationDate is pinned, though the schema does.

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 compact paragraph that packs a lot of feature detail without fluff. It front-loads the core value proposition (native vector chart) and then lists constraints and notable behaviors. It earns 4, not 5, because the dense wall of text could be structured more clearly for an agent scanning for supported chart types or key restrictions.

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 with 35 parameters, the description is nearly complete: it covers chart types, vector guarantee, multi-series, axes, pie/donut constraint, error code, routing to generate_basic_pdf, and PDF/A pairing. The output schema exists, so describing return values isn't necessary. It slightly lacks a quick statement about expected output format (base64 vs file) or the default one-page document, but the schema covers the outputMode parameter, so this is a minor 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 baseline is 3. The description does add some high-level semantics like 'per-series xValues with xAxis.type linear|time' and 'Pie/donut take exactly one series', but these are also repeated in the schema. No significant meaning is added beyond what the schema already documents, so 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 description states a specific verb ('Add') and resource ('native vector chart') and enumerates the supported chart types and features. It is clearly distinct from siblings like add_table or embed_image, but it does not explicitly name a sibling tool it is not, so it stops short of a 5.

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

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

The description gives a clear routing rule: 'Inside a longer document use a "chart" block in generate_basic_pdf.' This tells the agent when not to use add_chart. However, it doesn't explicitly state when to prefer this tool over other chart-capable paths or give a fuller when-to-use/when-not-to-use comparison, so it doesn't reach 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 the safety profile (readOnly=false for a document-creation mutation, idempotent=true, destructive=false), and the description adds modest context beyond that — noting this tool creates a new PDF rather than touching existing content and that common options mirror the other document tools. It does not dive into side effects, output format, or state changes for file-mode output, but with the schema carrying those details, a mid-score is fair.

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, each earning its place: the first states what the tool does and lists the field types; the second gives the exclusion rroute; the third signals family-wide option consistency. It is front-loaded and contains no filler—just a minor tightening opportunity in the redundant 'as on every document tool' phrase.

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-parametee complex nested tool, the combination of a 100%-covered schema, an output schema, and safety annotations gives the complete picture — required and output modes (base64/file), return to return, exclusive modes, defaults all live in the structure. The only region left to the agent to discover is the return-up artifact structure, which the output schema holds, so nothing critical 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 each of the 20 parameters is already documented (units, defaults, exclusivities, groupings). The description merely hints at the field vocabulary without repeating parameter-level detail; no compensation needed, but also no added value above 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?

Starts with a specific verb+resource — 'New PDF with an interactive AcroForm' — and enumerates the concrete control types (text fields, text areas, checkboxes, radio buttons, dropdowns). It further sharpens the scope by naming the sibling path it is NOT ('To fill or flatten an EXISTING form...'), so an agent can distinguish create-from-fill at a glance.

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 away from this tool for existing forms: 'To fill or flatten an EXISTING form use read_form_fields + fill_form.' The use cases (data capture, surveys, fillable templates) imply when to call it. It does not, however, contrast with other creation tools like generate_basic_pdf, so the boundary for 'when a plain PDF suffices' is left implicit.

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, the description discloses important behavioral facts: BiDi, Arabic joining, complex-script shaping, NFC normalization, newlines become paragraphs, and fonts are always embedded so embedFonts does not exist. This is exactly the kind of behavior an agent cannot infer from the schema alone, and it contradicts no annotation.

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-to-five dense sentences deliver a lot of ground without filler. The heavy script list is pruned with ellipsis, behavioral facts are front-loaded, and shared document options are collapsed into one phrase. It could trim a little, but it commits 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?

For a complex tool with 21 parameters, an output schema, and nested objects, this description covers the critical behavioral and parameter concerns. It could still be improved by naming the typical alternative for plain-Latin text, but it is nearly complete as it stands for selecting and calling the tool.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the description adds real semantics: lang can be either a single code or an array for mixed runs, newlines split paragraphs, and Unicode normalization behavior is explicitly described. This is genuinely useful beyond the schema, though not exhaustive.

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 the tool as rendering PDF text in 24 scripts plus emoji and math, which distinguishes it from siblings like add_table, add_barcode, and add_chart. It does not explicitly state that it creates a new PDF document or position itself against generate_basic_pdf, so it stops just short of a 5.

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

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

The description gives a strong capability profile: international scripts, automatic shaping, always-embedded fonts, and no embedFonts option. However, it never explicitly says when to use this tool instead of a sibling such as generate_basic_pdf or add_table, so the when-to-use guidance is implied rather than stated.

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

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

The description discloses important behavioral traits beyond annotations: network behaviour via the OPERATOR revocation provider, zero network in offline mode, incremental merging of existing /DSS, and constraints on signed/unencrypted input. There is no contradiction with the annotations, which treat it as a mutating and world-open operation.

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

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

The description is dense but efficient: it front-loads the core purpose and PAdES context, then uses compact parentheticals for mode/error details. It avoids fluff while still packing workflow, security, and environmental constraints into a text that earns its length.

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, 9-parameter tool with external network side effects, this description is complete. It explains the PAdES level, the call sequence, the mode differences, the security configuration, the offline/online material sources, and the key input constraints. Combined with the full schema and present output schema, an agent has enough to invoke 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 coverage is 100%, and each parameter already has detailed inline descriptions. The description adds some contextual value about modes and prerequisites, but it largely restates information present in the input schema rather than contributing new parameter-level semantics.

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 pair: 'embed a Document Security Store (/DSS + per-signature /VRI)' with validation material. It also situates the tool in a clear sequence (sign_pdf → add_ltv → timestamp_pdf), which disambiguates it from sign_pdf and timestamp_pdf without needing to inspect 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?

Usage context is explicit: it is ladder step 3, requires at least one signed signature, requires an unencrypted PDF, and differentiates online vs offline modes. It even names the error condition (REVOCATION_NOT_CONFIGURED) and the environment prerequisites, leaving no ambiguity about when this tool is appropriate.

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 declare destructiveHint=false, readOnlyHint=false, idempotentHint=true. The description adds meaningful behavior: PDF/A interaction with embedFonts, strict failure mode (PDF_A_COMPLIANCE_VIOLATION), tagged caption implications, and encryption/caching notes. These details exceed what annotations cover, though with a 34-param schema, the focus stays on the table-specific aspects.

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

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

The description is dense and well-structured, front-loads the core concept (tabular PDF report from headers+rows), and packs the smart-table options into one efficient list. Every sentence adds value, with the routing to generate_basic_pdf placed last as a natural afterthought.

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?

The tool has a huge schema (34 params) and output schema, so the description does not need to explain every return value. It covers the key behavioral notes (PDF/A compliance, embedFonts), and the self-contained table nature is clear. It does not explicitly mention outputMode/outputPath, but the schema covers that, so the balance is appropriate.

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 not need to restate every parameter. It adds a top-level framing ('Smart-table options: wrap, repeatHeader ...') that summarizes the parameter groups without duplicating schema detail. It directly compensates where the schema is otherwise terse, e.g., grouping the table-format options.

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 'Tabular PDF report from `headers` + `rows` (every row the same length)', which names the specific verb (add/generate), the resource (table report), and the core inputs. It distinguishes this tool from generate_basic_pdf explicitly by mentioning the alternative for embedding a table inside a longer document.

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 'Inside a longer document use a \'table\' block of generate_basic_pdf instead,' providing an exclusion condition and the named alternative. It also notes the shared options ('as on every document tool'), which sets expectations for typical usage.

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 declare readOnlyHint: false, destructiveHint: false, and idempotentHint: true, but the description significantly adds behavior beyond these: the PDF is modified non-destructively as an incremental update, original bytes are preserved, and content is never removed or redacted. It also warns about encrypted sources and sandbox file output. This is much stronger than the annotations alone.

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, structured as a sentence listing current valid types, then a sentence covering required parameters, then a warning. Major constraints and warnings are uppercase and front-loaded within each sentence. No filler or repetition of the schema is present.

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 rich input schema that already documents every parameter and an existing output schema, the prose description still covers all operational facts an agent needs: non-destructive behavior, required coordinate parameters, encrypted-source handling, and sandbox file writing. There are no missing behavioral warnings or usage caveats that an agent would need to know before making a safe call.

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 input schema already documents every parameter with useful descriptions, so the schema itself carries most semantics. The description enriches understanding by explaining the coordinate system (PDF user-space points), showing which parameters go with which annotation types (e.g. start/end for line, icon/open for text, quadPoints for markup types), and by stating that type-specific fields are optional. The one weak area is that outputMode/outputPath semantics are mostly schema-covered, but the description does reinforce the sandbox requirement.

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 the resource (existing PDF) and the precise action (append markup annotations as a non-destructive incremental update), listing supported annotation types and the standard it follows. It distinguishes itself from sibling tools like sign_pdf, encrypt_pdf, and merge_pdfs without needing detailed inspection.

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 states what it is not for: 'VISUAL OVERLAY ONLY — nothing is removed or redacted (covered text stays extractable).' It explicitly advises that encrypted sources require decrypt_pdf first. This provides clear when-to-use and when-not-to-use guidance relative to sibling 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?

The description discloses important non-obvious behaviors: the page tree is rebuilt, signatures and AcroForm are dropped, and results are never cached. This adds substantial value beyond the annotations, and no contradiction exists with idempotentHint/readOnlyHint.

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-load the core purpose, then the critical caveat, then the alternative routes. Each sentence earns its place, and the formatting makes the warning noticeable.

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?

The description, together with the fully documented schema, is sufficient for an agent to invoke the tool correctly: it covers supported algorithms, password requirements, the destructive caveat, alternate tools, and output modes are already in the schema. No critical operational context 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 parameters and constraints. The description reiterates the password semantics and caveat, matching the schema but adding no substantial new parameter-level 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 uses a specific verb ('Emit an UNENCRYPTED copy') and clearly identifies the resource (encrypted PDF) and supported encryption types. It also explicitly distinguishes itself from read-only PDF tools, so an agent can tell it apart from siblings like inspect_pdf and extract_text.

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 states exactly when to use this tool versus alternatives: to decrypt by emitting a new copy, and when merely reading an encrypted PDF to pass the password to sibling read tools instead. This gives explicit routing guidance with named alternatives.

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 provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'PNG without alpha channel' input constraint (already present in the schemas) and the cross-tool option pattern, but reveals no new behavioral traits beyond what annotations and schema already state. No contradiction exists.

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 with each carrying a distinct role: scope definition, sibling alternative, and cross-tool option pattern. The final sentence is slightly abstract but avoids redundancy, and the description is front-loaded with the clarifying scope before routing guidance.

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 25-parameter tool with an output schema and rich parameter descriptions, the description covers the essential invocation decision and defers the rest to the schema. The main omission is any high-level note about output behavior, but the output schema and idempotency annotation fill that gap adequately.

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 25 parameters. The description briefly names caption, render width/height, and the doc-wide options group, but provides no new semantic detail beyond what the parameter schemas already give.

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 the scope precisely: one PDF with a single embedded base64 JPEG/PNG, optional caption, and render width/height. It explicitly names generate_basic_pdf's 'image' block for longer documents, which differentiates it from the most similar sibling tool without opening any schemas.

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

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

Gives an explicit when-not-to-use rule with the alternative tool: 'Inside a longer document use an image block of generate_basic_pdf instead.' This directly routes the agent to the correct sibling, with the positive use case for this tool implied by contrast.

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 annotation declares `destructiveHint`: false, but the description honestly states that the page tree is rebuilt and signatures/AcroForm are DROPPED. This is an annotation contradiction; per rubric a direct contradiction requires a score of 1.

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 and every one earns its place: algorithm/handler, password/permissions/rotation, then the destructive caveat. The security-relevant warnings are front-loaded and there is no fluff.

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 with 8 parameters, 100% schema coverage, and an output schema available, the description covers every decision axis: algorithm version, rotation, permissions, timing, outputMode implications, and the destructive caveat. Nothing an agent needs to select or invoke it safely 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 every parameter is already meaningfully described in the input schema. The description restates ownerPassword required, optional userPassword, permission flags, and rotation; this convenience is useful but adds little 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?

Says exactly what it does: 'Encrypt an existing PDF' with a named handler, algorithms, password modes, permissions, and rotation use-case. This cleanly separates `enrypt_pdf` from sibling tools like `decrypt_pdf` and `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 context: use it on unencrypted or already-encrypted via `password` for rotation, and explicitly says to run encryption BEFORE signing. It does not spell out a when-not-to-use alternative such as 'use decryption for removing security', but the workflow cy 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?

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?

The description discloses material side effects: signatures/AcroForm/XMP are dropped, boxes are kept, URI annotations persist unless dropAnnotations, and output is unencrypted unless encrypt is supplied. These go well beyond the annotations and give the agent the real behavior of the tool. There is no contradiction with the idempotentHint/destructiveHint 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 compact, front-loaded, and avoids duplicating the 8-parameter schema. It leverages the sibling merge_pdfs to inherit known caveats instead of repeating them, and every sentence contributes either a constraint, a behavior, or an alternative.

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 rich input schema with 100% coverage and a declared output schema, the description fills the remaining practical gaps: output freshness, encryption behavior, page-tree side effects, and the route to split_pdf. An agent has enough information to select and invoke this 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, and the description adds useful semantics on top: pages are order-preserving and 0-based, an encrypted source requires password, and output encryption happens only when encrypt is given. It does not restate every parameter, but the schema already documents those clearly.

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 leads with a concrete action: keep an arbitrary 0-based pages[] subset in exactly one fresh PDF. It clearly distinguishes extract_pages from split_pdf and merge_pdfs and states a finite output scope. There is no ambiguity about the tool's object or effect.

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 to split_pdf when multiple output documents are needed, and it references merge_pdfs for shared behavior. It also gives the encrypted-source conditional: provide password, include encrypt if encrypted output is wanted. These are concrete when-to-use vs when-not-to-use signals.

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 and idempotent, but the description adds crucial behavioral detail: the meaning of `extractable=false` as a legitimate condition explained by `extractableReason` rather than an error, the PASSWORD_REQUIRED/PASSWORD_INVALID error states, and the security note that passwords are never logged. It also explains the verbosity and runs mechanics, which are not expressed by annotations alone. No contradiction.

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

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

The description is dense and front-loaded with the core purpose. Every sentence carries meaningful operational or error-handling information, but the heavy use of parentheticals and one very long sentence make it slightly harder to parse. In comparison to a two-sentence standard, it is longer but justified by the complexity.

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

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

Given the tool's complexity, an output schema exists and the description covers supported input behaviors, edge cases (font mapping failure), encryption, security, and response verbosity tuning. The only minor gap is not enumerating all error codes (like OUTPUT_TOO_LARGE), but that appears in the schema parameter docs. Overall, an agent can select and invoke the tool correctly based on the description plus 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?

The input schema covers all 7 parameters (100%), but the description enriches key ones: it explains that `pages` uses zero-based indices, that `fields` is a dot-path projection, that `verbosity:'summary'` produces a token-frugal response, and that `includeRuns` returns positioned runs. These are semantic overlaps that add value beyond the schema without repeating it fully.

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 line 'Plain-text extraction' plus the technical mechanism ('decodes Tj/TJ operands through each font's /ToUnicode CMap...') states the exact operation and resource. It is clearly distinguished from siblings like extract_attachments and inspect_pdf, which perform different extraction/inspection tasks. The specific mention of pages, fullText, and includeRuns output confirms it is a text extraction tool with unique purpose.

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 gives clear operational context: it explains when to use `password` for encrypted sources, when `extractable` is false, and how `includeRuns` gives layout-aware extraction. It implies this is the tool for extracting text from PDFs, but it does not explicitly state 'use this instead of X' or list exclusions. The guidance is concrete and contextual but lacks direct sibling differentiation.

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 what annotations state, the description discloses several non-obvious behaviors: the update is incremental and preserves prior signatures, flattening stamps appearances and removes the interactive layer, pure flattening works with no values, unknown field names produce FORM_FIELD_OT_FOUND unless ignored, and signature fields are unsupported. This is exactly the kind of behavioral context that annotations cannot cover.

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, roughly five sentences cover target, sibling distinction, value syntax, flatten behavior, error modes, fir signature constraints, and encryption. Every sentence adds a factual constraint needed for safe invocation, and the most important scoping information 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 tool with 8 parameters, 1 requirement, nested values, and an output schema, the description plus rich parameter descriptions are complete enough. It covers the main failure modes and non-obvision side effects, while the output schema handles return value explanations, so nothing necessary for correct invocation 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% and every parameter including `values`, `flatten`, `onUnknownField`, and `password` has a detailed description already. The tool description provides a high-level summary of value types and flatten semantics, but it does not add meaningful information beyond what the input schema already supplies, so 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 description opens with a specific verb and target: 'fill and/or flatten the AcroForm of an EXISTING PDF'. It immediately distinguishes this from add_form by parenthetically identifying that sibling as the creation tool, so an agent can identify the exact resource and action.

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 says this operates on an existing AcroForm and points to add_form ('add_form creates one') as the alternative. The schema's pdfBase6 explanation further tells the agent to call `read_form_fields` first to discover names, and the description says signature fields cannot be filled, making misuse conditions explicit.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, lowering the behavioral burden, and the description contradicts none of them. It adds meaningful context beyond the schema: every block shares its body with the dedicated sibling tool, pdfA requires embedFonts for a valid claim, and optional groups such as outline/pageLabels/viewerPreferences/watermark are folded into functional categories. It does not describe error/edge behavior, but the 100% output schema and annotations cover enough.

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 with no filler; the core purpose and routing are front-loaded and the rest is a compact feature-group summary. The block enumeration makes it long, but every sentence earns its place, so it is tight 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?

This is a high-complexity tool (25 parameters, deeply nested blocks, output schema present), and the description correctly delegates parameter detail to the schema while carrying what the schema cannot: the routing to siblings and the body-parity with dedicated tools. Minor non-obvious interplay such as a printed TOC depending on heading blocks is left to the schema, an acceptable and small gap for such a large surface.

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 input schema itself describes every one of the 25 parameters with defaults, exclusivities and constraints, so the baseline of 3 applies. The description adds only cheap cross-block glue (body parity with dedicated tools, functional groups), which is useful but not required for parameter understanding.

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 'Multi-page PDF composed from ordered blocks' - a specific verb and resource plus the construction principle - and enumerates every block kind the engine offers. It also declares itself the 'DEFAULT' for any document, which clearly separates it from the block-specific sibling tools.

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 selection rule: 'DEFAULT for any document; use the dedicated tools only for a standalone artefact, add_attachment for embedded files and add_international_text for non-Latin scripts.' It names the exact alternatives and the conditions that call for them, so the routing is never left to inference.

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

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

The annotations (readOnlyHint, idempotentHint, destructiveHint) already cover safety, and the description adds meaningful behavior beyond them: it does NOT generate a PDF, it is deterministic, and it has a known engine gap for 'toc' blocks which can make pagination one page short. The token-frugal usage note ('verbosity:'summary', fields:['totalPages']') adds practical behavioral guidance. No contradiction with 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?

Every sentence earns its place: the first sentence states the purpose plus output shape, the second defines the parameter semantics through the sibling relation, the third discloses a known limitation, and the fourth summarizes safety and efficiency. Front-loaded with the most critical fact (no PDF), no filler, and not bloated despite the large schema. The description is short but complete.

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?

The description is complete for a complex 12-parameter tool with 100% schema coverage and a present output schema. It covers the tool's role among siblings, its return semantics, its known edge case, and its performance/token profile. Nothing needed to invoke it correctly is missing — it distinguishes itself from the sibling, states contract with the parameters, and flags the only caveat in the measurement.

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 has 100% description coverage, so the baseline is 3 even without extra description. The description adds cross-cutting semantic value by saying that all these parameters behave exactly as in generate_basic_pdf, meaning the schema descriptions can be interpreted consistently across tools. It also highlights the dependency: pass the same values to get a matching page count. It doesn't duplicate per-parameter schema detail but does add meaning about parameter usage intent.

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 'Pagination preview WITHOUT generating a PDF', a specific verb-resource pairing that immediately distinguishes this tool from generate_basic_pdf. The purpose is further sharpened by listing the exact output: page count and where every block lands (page, x, top, width, height in points). It is far beyond a tautology and clearly names the sibling it is not.

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 instructs the agent to pass the same inputs that would be given to generate_basic_pdf, including the full list of layout-affecting parameters. It names the sibling tool directly and clarifies the precondition/use case: validate pagination before generating a PDF. The line about a toc measured as 0 pt also tells the agent when the page count may be unreliable.

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 builds on this by adding richer behavioral detail: presence-gated fields, password handling for encrypted sources, check/checksPassed semantics, per-page output, and token-frugal verbosity. No contradiction with 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 dense, front-loaded, and every sentence carries actionable information. It earns high marks for efficiency, though it reads as one long paragraph with many semicolon-separated ideas; a slightly clearer structure could make it a 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?

Given the 8 parameters, output schema, and complexity of the flags, description fully covers the important operational semantics: what is returned, how flags change shape, how checks behave, how passwords are used, and how token output can be reduced. The description does not need to restate the full schema because the schema describes the structured requests.

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 even lowering value beyond the schema: signatures:true means every field; pages:true means per-page sizes and boxes; check:list is a CI assertion returning checks + checksPassed; password is called out for encrypted sources; verbosity and fields are tied to token-frugality.

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 "Read-only facts about a PDF" and enumerates concrete properties (version, pageCount, encryption, signatureCount, etc.), so the tool's purpose is immediately obvious. It also clearly distinguishes itself from validation by calling the pdfA result a claim, not its validity.

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 clearly frames the tool as metadata inspection and even redirects pdfA validity checking to veraPDF, giving an explicit alternative. It does not exhaustively map all sibling alternatives—for instance, it does not explicitly say 'signature validity is verify_pdf's job' in the description—but the read-only framing makes the intended use 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?

Given annotations only cover readOnly/destructive/idempotent hints, the description carries substantial behavioral detail: it explicitly states that signatures and AcroForms are dropped, XMP/PDF-A doesn't survive, page boxes and /UserUnit survive, URI links are kept conditionally, encryption is handled with an optional password, and size guards (256 MiB assembly, 50 MiB output). This goes far beyond what annotations alone reveal and precisely informs the agent of post-conditions 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?

The description is dense but well-structured: it opens with the core operation, then systematically discloses page-tree destructive effects, encryption handling, and size guards. Every sentence earns its place; no filler or restatement of the tool name. The front-loaded main operation ensures an agent gets the gist quickly, with edge cases and constraints following logically.

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 fairly complex merge tool with nested `encrypt`/`permissions` objects, 7 parameters, and an existing output schema, the description provides all essential decision-relevant context: drop behavior, encryption behavior, output modes, guard limits, and error signals. Nothing an agent needs to safely invoke this tool is missing.

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

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

Schema coverage is 100%, and the description reinforces the key parameter semantics beyond the schema: it explains the semantic meaning of `pdfsBase64` (concatenation order), the behavioral consequence on signatures/AcroForms, the conditional behavior of `dropAnnotations`, the assembly guard role of `maxOutputSizeBytes`, and the encryption output implications. This adds real value and clarifies edge cases the schema alone doesn't convey.

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 ('Concatenate'), a clear resource ('PDFs'), the input range (2–50), the output type (fresh, self-contained document), and explicitly differentiates behavior from sibling tools by detailing what does and doesn't survive the merge. It is unambiguous and distinctive even among many PDF-related sibling tools.

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 explicit contextual behavior and even names the alternative behavior via 'dropAnnotations:true' and the `encrypt` option. It doesn't explicitly say 'use this tool when...' or name a sibling alternative, but the limit and error-code guards make the intended usage clear. The main gap is that it doesn't contrast with split_pdf/extract_pages for page-level operations, but the description sufficiently covers merge-specific 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 declare idempotentHint=true and destructiveHint=false, so no contradiction. The description adds genuine behavior beyond those: the unsigned file is NOT yet a conformant PDF/A (empty /Contents) and becomes conformant only once signed; signature metadata is frozen at placeholder time and can't be rewritten by sign_pdf later. It also discloses the 'auto-inject' behavior of the sibling, which is a non-obvious interaction an agent needs to predict placeholder sizing.

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 front-loads the core purpose in the first sentence, packs the key behavioral gap (PDF/A non-conformance) in one sentence, and closes with a short cross-tool invariant sentence. The parameter differentiation is compressed into one sentence with a parallel list. No filler, no repetition of schema content.

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

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

With 28 parameters, 100% schema coverage, nested objects and an output schema present, the description's job is mostly to disambiguate the tool within the sibling family and call out cross-parameter interactions, both of which it does well. The gap: the description lacks a compact example payload and does not define a concrete 'how to produce a good placeholder for a >4096-bit key' recipe. The schema and output schema carry a large portion of the load, so this is adequate-but-not-complete for such a large tool signature.

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 per the rubric. The description earns an extra point by explaining the cross-parameter interaction: placeholderBytes default context, reserveTimestamp adds 8 KiB, and reserveTimestamp is ignored when placeholderBytes is set explicitly. It also links subFilter to the sign_pdf profile='pades' and pageIndex to a latent widget. This is real semantic value beyond the schema's per-field descriptions.

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

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

The description opens with a specific verb-plus-resource statement: 'New PDF carrying an unsigned /Sig placeholder for a LATER sign_pdf call.' It clearly distinguishes the tool from sign_pdf by framing this as the placeholder preparation step, and it names the sibling sign_pdf explicitly in the first sentence. The scope (what gets frozen, what can be resized) is specific rather than vague.

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 states when to use this tool and, crucially, when NOT to: 'OPTIONAL — sign_pdf auto-injects one.' The description enumerates concrete use cases (reserve space for >4096-bit keys, pin widget page, choose PAdES subFilter, ship placeholder separately). It also warns that signerName/reason/location/contactInfo/signingTime are frozen here and cannot be rewritten by sign_pdf later, giving the agent a clear decision rule between this tool and its sibling.

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

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

Annotations already 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.

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

The description goes well beyond the annotations (readOnlyHint=false, idempotentHint=false) by disclosing real behavioral consequences: auto-injection of a /Sig placeholder occurs in the same call, the injectable signature parameters are baked only into a newly injected placeholder, allowMultiple creates incremental revisions while previous signatures remain valid, and timestamp:true contacts the operator TSA while otherwise the server never touches the network. Known error states (TSA_NOT_CONFIGURED, PLACEHOLDER_AMBIGUOUS, SECURITY_VIOLATION) are explicitly named, giving the agent accurate failure expectations.

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 long but information-dense, and it is front-loaded with the core one-call capability before covering edge cases, error codes, and cross-tool relationships. Every sentence contributes either a usage constraint, an error condition, or a routing decision, though there is some redundancy with the schema's parameter-level descriptions that could be trimmed. For a 19-parameter signing tool, this length is justified.

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's 19 parameters and intricate PDF-signing semantics, the description covers the full decision surface: placeholder injection, placeholder ambiguity, multi-signature behavior, time-stamping trust, key format acceptance, and sandbox/network failure modes. Since an output schema exists, not restating return values is acceptable, and the description even tells the agent where to verify the result. No critical operational detail 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 structured schema already documents every parameter's meaning, formats, mutual exclusivity, and openssl conversion remedies. The description adds orchestration-level context (how algorithm selects the corresponding key parameter, how the injected placeholder interprets signerName/reason/location/contactInfo/signingTime) rather than new per-parameter semantics. This matches the baseline of 3 for a fully covered 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 names a specific verb (sign), a specific resource (PDF), and the two format families (CMS / PAdES), immediately distinguishing it from sibling utilities like add_ltv, timestamp_pdf, and verify_pdf. It also clarifies the one-call advantage over prepare_signature_placeholder, making the tool's identity unmistakable. The title reinforces the same scope without adding confusion.

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 states when profile:'pades' should be chosen ('right choice when add_ltv / timestamp_pdf follow'), when fieldName is required ('Several unsigned placeholders → pass fieldName'), and when allowMultiple applies ('adds a further signature'). It also names the verification counterpart ('Verify with verify_pdf') and explicitly rejects PEM with a remedy. Conditional usage rules are given with concrete triggers, so no selection is left to inference.

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

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

The description discloses multi-output behavior, output naming conventions in file mode, what happens in base64 mode, and important PDF caveats (signatures/AcroForm/XMP dropped; boxes kept). It also notes encrypted sources using password. These go beyond the annotations, which only describe readOnly/idemptency/destructive hints, and would meaningfully affect ai-agent expectations for the result.

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 and information-dense: four sentences that front-load the core operation, then deliver range semantics, output behavior, page-tree caveats, encrypted-source handling, and the sibling alternative. Every sentence earns its place and no extraneous content is present.

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 with 8 parameters, nested objects, and an output schema, the description covers the defining split behavior, the two output modes with concrete file naming, the main transformation caveats, and the canonical alternative. Given the rich schema and output schema, nothing essential is missing for selecting or invoking 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 input schema already documents every parameter including the zero-based inclusive nature of ranges, outputPath semantics, password behavior, and outputMode defaults. The description reinforces the central `ranges[]` semantics and output naming but does not add meaningful meaning beyond what the schema already 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 clearly states a specific verb and resource: 'Split one PDF into several documents, one per ranges[] entry'. It also distinguishes itself from extract_pages by explicitly naming the alternative for extracting a single document, so an agent can tell the tools apart at the description level.

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?

Includes explicit routing guidance: 'Need ONE document from a page subset? Use extract_pages.' It also references merge_pdfs for shared page-tree caveats, helping the agent understand this tool is best when multiple ranges are wanted, and points to password handling for encrypted sources. Clear enough to select this tool over the alternatives.

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?

Even though annotations mark readOnlyHint=false, the description goes far beyond that: it discloses exact behavior (append over whole document, omitted fieldName auto-naming, TSA dependency, status/imprint/nonce checks, sandbox output behavior, and the SECURITY_VIOLATION risk when the sandbox is unconfigured). It does not contradict the provided 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?

Every sentence in the description is dense and purposeful: scope, procedure, failure mode, configuration dependency, security checks, and constraints are all covered without fluff. The content is compact yet complete for a five-parameter tool.

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 complexity, the annotations, the 100% schema description coverage, and the presence of an output schema, the tool is both internally complete. It covers when to use, ordering relative, constraints, configuration environment, output modes, and security-specific behavior.

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