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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false, which already signal this is a mutating, non-idempotent operation. The description adds valuable behavioral context: coordinate system (PDF space, origin bottom-left, pt), the incremental-update behavior for signed PDFs, the default error on signed PDFs unless allowBreakingSignatures is set, and the PDF/UA conformance preservation. It does not contradict 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 two sentences and front-loads the core purpose and annotation types. The second sentence adds important behavioral context about signed PDFs and PDF/UA conformance. It is efficient, though the signed-PDF sentence is dense and could be split for readability. 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 15-parameter tool with no output schema, the description covers the key behavioral aspects: what the tool does, coordinate system, signed-PDF handling, and PDF/UA conformance. The schema covers all parameter semantics. The description does not explain the return value when outputPath is omitted, but the schema's outputPath description covers that. Overall, the description is complete enough for an agent to select and invoke the 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 description coverage is 100%, so the schema already documents all 15 parameters. The description adds meaning beyond the schema by explaining the coordinate system (PDF space, origin bottom-left, pt), the three annotation types, and the signed-PDF behavior. It also clarifies the relationship between preserveSignatures and allowBreakingSignatures, which is not fully captured in the individual parameter 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 states a specific verb ('Add') and resource ('one annotation to a page'), and enumerates the three supported annotation types (sticky note, highlight, rectangle). It also names the coordinate system, which distinguishes it from any other annotation-like tool. The title and description align, and the description clearly differentiates this from sibling tools like add_watermark or stamp_page_numbers.

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 context for when to use the tool: adding sticky notes, highlights, or rectangles to a page. It does not explicitly name sibling alternatives or state when not to use it, but the sibling list shows no other annotation tool, so the usage context is clear. The signed-PDF guidance (preserveSignatures vs allowBreakingSignatures) provides important conditional usage direction.

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 indicate non-readonly, not idempotent, and non-destructive. The description adds valuable behavior: existing bookmarks are replaced, signed PDFs can be edited incrementally without invalidating signatures, and breaking signatures is an opt-in behavior. These go beyond annotation hints and set proper expectations about destructive/replacement semantics.

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 concise but a bit dense. It front-loads the core action and replacement behavior, then covers nested children and the signed-PDF edge case in two sentences. Every clause is informative, but the signed-PDF detail could be clearer for agents unfamiliar with PDF signature semantics.

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 a complete schema (100% coverage), no output schema, and clear annotations, the description sufficiently covers the tool's purpose, key behavioral semantics (replacement, signatures, nesting limits are in schema), and defaults. Missing only an explicit note that outputPath omission returns base64, but that is present in the schema, so the description need not repeat it.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds minimal extra parameter meaning beyond what the schema provides, though it clarifies the overall bookmark hierarchy and replacement behavior. Baseline 3 is appropriate given the schema already carries the burden.

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

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

The description states a specific verb ('Set') and resource ('bookmarks (outline) of a PDF'), clearly distinguishes its replace-existing-bookmarks behavior, and mentions nesting and the signed-PDF preservation option. This is sufficient to differentiate it from sibling tools like stamp_page_numbers or set_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?

The description conveys when to use it: for setting PDF bookmarks/outlines, including for signed PDFs when preserveSignatures is used, and it notes existing bookmarks are replaced. It doesn't explicitly name sibling alternatives or state when not to use it, but the context is clear enough for a tool that is semantically unique among siblings.

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 non-read-only, non-destructive, and idempotent. The description adds valuable context: default faint behind-content drawing, Artifact wrapping for tagged PDFs, and fontPath dependency for CJK. This goes beyond the annotations and clarifies operational behavior. 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?

The description is compact, with the core action stated first, followed by key behavioral notes. Every sentence earns its place—no redundant phrasing. It is efficiently structured and 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 13 parameters, the description covers the main purpose, defaults (faint, behind), and special cases (tagged PDFs, CJK fonts). The schema handles parameter-level detail, and there is no output schema to explain. The description is sufficiently complete for an agent to use the 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 description coverage is 100%, so all parameters are already documented in the schema. The description adds value by pointing out the CJK font requirement, which is a cross-parameter dependency not apparent from individual schema entries. It doesn't need to repeat schema details.

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 ('Overlay a diagonal watermark') and the target resource ('each page'), with concrete examples of typical watermark text. This distinguishes it from sibling tools like add_annotation or stamp_page_numbers, which serve different purposes.

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 provides context such as the Artifact wrapping in tagged PDFs for PDF/UA conformance and the fontPath requirement for CJK watermarks, which informs when to use it or what to prepare. However, it doesn't explicitly compare to alternative tools or state when this tool is not appropriate, so it falls short of a 5.

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

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

With annotations already indicating readOnlyHint=false and destructiveHint=false, the description adds meaningful behavioral detail: it says the file is registered under specific PDF name trees and the catalog with an AFRelationship. This explains the underlying mutation mechanism without repeating annotation facts.

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 sentences with no filler. The core action is front-loaded, followed by technical registration details and then a concise use-case context. Every sentence adds useful 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 10-parameter tool with no output schema, the description gives enough high-level context to select the tool correctly handed off to the schema for parameter details. It does not describe return behavior, but the schema documents outputPath and returnBase64, so the gap is minor.

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 explain individual parameters, but it does tie the tool's purpose to the relationship field by mentioning AFRelationship and the invoice/CSV/XML bundling use case. The schema itself carries most parameter meaning.

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

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

The description begins with a specific verb and resource: 'Embed (attach) a file into a PDF.' It further clarifies the operation by naming the PDF structures involved (/Names /EmbeddedFiles, /AF, AFRelationship). This clearly distinguishes it from sibling tools like merge_pdfs or add_annotation.

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 concrete use context: PDF/A-3 and Japanese e-bookkeeping-law workflows that bundle invoice PDFs with machine-readable CSV/XML data. It does not explicitly state when not to use it or name an alternative, but the context is specific enough for an agent to decide when this tool applies.

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 indicate this is not read-only and is idempotent; the description adds a valuable behavioral disclosure: inline decoration markers are stripped and text is rendered plain in a single font. This is non-obvious and helps set expectations, though it does not detail file output behavior or 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 two sentences, front-loaded with the core purpose, and then adds a compact list of supported features plus an important behavioral caveat. Every sentence earns its place with no redundancy or filler.

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

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

Given the detailed schema descriptions for all 13 parameters, the description does not need to repeat them. It covers the supported Markdown feature set and a key rendering behavior, which is sufficient for invocation. A small gap is the absence of any guidance about output modes or when to use sibling PDF creation tools, but the schema fills most operational details.

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 parameters are already well documented individually. The description adds no parameter-specific meaning beyond the schema; it only gives a general overview of Markdown support. Baseline 3 is appropriate because the schema carries the burden.

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

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

The description states a specific verb and resource: 'Create a PDF from Markdown,' and enumerates the supported Markdown constructs (headings, lists, code blocks, tables, etc.). It is clear about what the tool does, though it does not explicitly differentiate itself from the sibling tools create_text_pdf or create_table_pdf beyond implying Markdown input.

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

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

The description implies usage: use this tool when you have Markdown content and want a PDF. It lists supported elements, which gives some scope, but it gives no explicit guidance about when to choose this over create_text_pdf or create_table_pdf, and no mention of limitations or exclusions.

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

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

Annotations already provide idempotentHint=true and non-destructive/read-only flags. The description adds useful behaviors beyond annotations: automatic column widths, cell wrapping, and header redrawing after page breaks. It does not mention file side effects, but outputPath and returnBase64 in the schema cover that.

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

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

Two sentences with no filler. The core purpose is front-loaded, and each clause adds meaningful behavior. It is compact while still informative.

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 14-parameter tool, the schema is exhaustive and the description adds table-specific rendering semantics. There is no output schema, but outputPath and returnBase64 explain result delivery well enough. The definition is complete for practical invocation.

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

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

Schema description coverage is 100%, so the baseline applies; the prose mostly repeats the notion of headers and row data. The schema itself thoroughly documents all parameters, defaults, enums, and requirements, so the description adds little parameter-level 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?

Description states a specific verb and resource: create a ruled table PDF from headers and row data. This clearly distinguishes it from the sibling text/markdown PDF tools and gives an unambiguous account of what the tool produces.

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

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

The description clearly implies use for tabular data via headers and rows, and sibling names like create_text_pdf and create_markdown_pdf make the contrast obvious. However, it never explicitly names alternatives or states when not to use it, so it stops short of full routing 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 discloses layout behavior—honoring \n, treating blank lines as paragraph breaks, and auto-wrapping long lines—which goes beyond the annotations' readOnly/idempotent/destructive hints. It does not mention output side effects like writing to outputPath or base64 return, but those are covered in the rich parameter schema, and there is 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?

Three short sentences, with the core purpose first and formatting details following. Every sentence adds useful behavioral context, and there is no filler or 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?

The tool has 13 parameters and no output schema, but the parameter descriptions are exhaustive, covering defaults, ranges, required conditions (e.g., title for tagged PDF, fontPath for non-Latin). The main description provides the essential plain-text formatting context. Minor context like base64 return or font requirements is fully specified in the schema, so the overall definition is complete enough for an agent to call correctly.

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

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

Schema description coverage is 100%, so the parameter descriptions carry the semantic load. The tool description's line-break and paragraph information largely duplicates what the text parameter already states, adding no new meaning beyond the schema. This matches the baseline of 3 for full schema coverage.

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 resource: 'Create a PDF from plain text.' It further clarifies behavior with line breaks, paragraph breaks, and auto-wrapping, which sets it apart from siblings like create_markdown_pdf and create_table_pdf based on input format. This is a clear, non-tautological statement of the tool's function.

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

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

The description implies usage: use this when input is plain text, as opposed to markdown or table data, but it never names alternatives or states when not to use it. The sibling list provides context, but the description itself does not give explicit routing or exclusion guidance, so this 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?

With annotations already marking the tool as destructive and non-read-only, the description adds substantial behavioral context: it states that pages are copied into a new document, that document-level information (tagged structure, XMP, attachments, AcroForm, bookmarks) is not carried over, that losses are reported in warnings, and that follow-up actions are needed. It also discloses the error condition for deleting all pages and the signature-breaking behavior via the allowBreakingSignatures parameter. This goes well beyond the annotations.

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

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

The description is two sentences long and front-loads the primary action immediately. Every clause contributes value: the operation, the error condition, the loss of metadata, and the follow-up guidance. There is zero redundancy or 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?

The description covers the essential behavioral aspects: what the tool does, what it destroys, error conditions, and what to do afterward. The return format is not explicitly described, but the schema covers outputPath and returnBase64, so that gap is acceptable. Given the tool's complexity (5 params, no output schema), the description is thorough and leaves little ambiguity for an agent deciding to call it.

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

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

Schema description coverage is 100%, so all five parameters are already documented. The description adds a meaningful constraint ('Deleting every page is an error') that isn't in the schema, but it does not elaborate on parameter meaning or format beyond that. The description adds marginal value over the schema, so a 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-resource pair ('Create a new PDF with the given pages removed') that precisely defines the operation. It also states a key error condition ('Deleting every page is an error') and explicitly distinguishes the tool from siblings by describing the outcome as a new PDF with pages removed, which is distinct from extract or reorder. The purpose is unambiguous.

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

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

The description does not explicitly tell the agent when to choose this tool over alternatives like extract_pages or reorder_pages. It implies the use case (removing pages) but provides no comparison or conditions for selection. It also doesn't mention any prerequisites or complementary tools, only suggests follow-up tools for lost metadata, which is post-processing advice rather than selection 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 far beyond the annotations by disclosing that the tool is only a scaffold, not a conformance guarantee; that writing pdfaid creates a 'PDF that lies about itself' on non-conforming input; and that a warning is always returned. It also details signature handling (incremental update, approval-only, refusal conditions) and explicitly states content, structure tree, and fonts are never touched.

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 often redundant with the schema's parameter descriptions, especially the flavour explanation which is nearly duplicated verbatim. While the caveats are important and the bolded emphasis aids navigation, the text is a wall of detail that could be tightened by removing schema-echoed content without losing risk-critical 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?

Given the tool's complexity, the description covers all essential operational context: prerequisites, limitations, post-verification steps, signature edge cases, and the non-conformance warning behavior. No output schema exists, but the input schema already documents return behavior, so the absence of return-type detail is not a gap; the description fully equips an agent to invoke the 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 description coverage is 100%, so the baseline is 3; the description adds meaningful cross-parameter constraints, most notably the refusal of -4 flavours combined with preserveSignatures unless the input is already PDF 2.0. It also clarifies the flavour-attachment relationship and reinforces the base64-return behavior, providing value beyond the individual parameter 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 and resource: 'Put an existing PDF onto the PDF/A vessel', and explicitly positions itself as 'the PDF/A counterpart of ensure_tagged', distinguishing it from that sibling. It enumerates the exact document-level requirements supplied (trailer /ID, sRGB OutputIntent, XMP pdfaid), leaving no ambiguity about 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?

The description gives explicit when-to-use guidance: apply after attach_file in the e-bookkeeping context, and always confirm with pdf-verify-mcp's validate_conformance. It spells out exclusions — certification signatures are refused, and -4 flavours with preserveSignatures are refused unless the input is already PDF 2.0 — and explains flavour selection for attachments, making alternative choices concrete.

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 explains exactly what mutates: tagged files get only document-level requirements, untagged files get a minimal per-page P-element tree. It also discloses the critical limitation that real semantics (headings, tables, lists, reading order, alt text) are not created and that human review is required. No contradiction with 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 front-loaded with the core purpose, then branches into tagged vs untagged behavior, the important human-review warning, the alternative tool guidance, and signed-PDF handling. Every sentence carries useful decision-relevant information with 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 mutation tool with no output schema, the description covers the important branches: already tagged, untagged, signed, and certification-restricted. Output behavior is handled by the schema's outputPath/returnBase64 descriptions, so an agent has everything needed to invoke the 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?

The schema description coverage is 100%, so all seven parameters are already documented structurally. The description adds only incidental context around preserveSignatures and the lang/title mapping to PDF/UA requirements, not enough to raise it above the baseline for full schema coverage.

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: putting an existing PDF onto the PDF/UA-1 'vessel' and repairing or scaffolding its tag structure. It distinguishes between already-tagged and untagged inputs, and explicitly contrasts itself with the create tools by mentioning their tagged: true option.

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 actionable selection guidance: use this when an existing PDF needs PDF/UA structure, and prefer the create tools with tagged: true when building structure from scratch. It also covers the signed-PDF branch by directing use of preserveSignatures: true and warning that certification signatures are refused.

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 beyond annotations by disclosing that document-level information (tagged structure, XMP, attachments, AcroForm, bookmarks) is stripped, that losses are surfaced in warnings, and that follow-up tools may be needed. This is valuable and consistent with idempotentHint=true, readOnlyHint=false, and destructiveHint=false.

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 sentences with the core purpose first, then behavioral caveats, then actionable follow-up. No filler; each sentence adds unique 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 5-param tool with no output schema, the description plus fully documented schema covers the outcome, side effects, warnings, and follow-up. Missing explicit sibling differentiation is a usage gap, but not a completeness gap for calling the 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?

The schema description coverage is 100% with detailed descriptions for all five parameters, so baseline is 3. The description reiterates the pages-order concept but doesn't add new parameter semantics 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?

States a specific action ('Create a new PDF') and resource ('only the given pages'), and adds the order-preservation detail. It is clear but does not explicitly name or contrast sibling tools such as split_pdf/delete_pages/reorder_pages, so it earns 4 rather than 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 implies when to use it: to extract a subset of pages, and explicitly notes that order preservation means it can also reorder. It provides no explicit when-not-to-use or alternatives, and the follow-up guidance is after-use rather than tool-selection 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?

Annotations already mark this as a non-read-only, idempotent, non-destructive operation. The description adds valuable behavior beyond that: flattening breaks PDF/UA conformance on tagged PDFs and requires allowBreakingTags: true, CJK values need a font, and the error response lists all field names/types when given an unknown field. It does not mention signature-breaking behavior (covered in the schema) or the base64 return option (also in schema), but it covers the most consequential side effects and requirements.

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

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

The description is a compact paragraph of four sentences, each earning its place: main purpose, field-discovery tip, CJK requirement, and flatten side-effect warning. It is front-loaded with the core action and keeps the most important caveats early. No redundant or filler 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?

For a tool with 8 parameters, nested objects, and no output schema, the description covers the essential behavioral and usage context an agent needs: how to discover field names, font requirements for non-Latin text, the flattening caveat, and the unsupported XFA case. Output format and signature-breaking behavior are already documented in the schema, so they do not need repetition. The description is complete for successful invocation.

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

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

The schema already describes all 8 parameters with 100% coverage, so the baseline is 3. The description enhances this by explaining cross-parameter dependencies (CJK requires fontPath or the PDF_WRITER_FONT env var, flatten on a tagged PDF requires allowBreakingTags), and it explains the field-naming trick that affects how the fields parameter is used. This goes beyond simply restating the schema and gives the agent practical guidance on parameter usage.

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

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

The description opens with a specific verb-resource pair ('Fill field values into an existing PDF's interactive form (AcroForm)') and explicitly scopes the tool to AcroForm, distinguishing it from the sibling flatten_form and other PDF tools. It also notes XFA forms are unsupported, further clarifying its domain. An agent can unambiguously identify this as the tool for populating interactive form fields.

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 practical guidance: a trick for discovering field names by passing a nonexistent one, a prerequisite for CJK values (fontPath or env var), and a clear exclusion (XFA not supported). It does not explicitly point to the sibling flatten_form for flatten-only workflows, and it does not contrast with other form-related tools, but the scope and exclusions are sufficient for most selection decisions.

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 adds significant behavioral detail beyond the annotations: it discloses side effects (removal of interactivity, Widget annotation disappearance, dangling Form structure), refusal behavior on tagged PDFs, and signature-breaking consequences. This is especially valuable given destructiveHint and idempotentHint are already present.

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 the primary purpose, followed by targeted usage notes. Every sentence contributes meaningful information and there is no redundant 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?

The description covers the main purpose, key side effects, refusal conditions, and font caveats. Since the input schema thoroughly explains parameters including base64 return behavior, the description does not need to repeat that; it is complete enough for an agent to select and invoke the 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 description coverage is 100%, so the schema already documents all six parameters and their meanings. The description adds helpful context for fontPath and allowBreakingTags, but this is augmentative rather than necessary; the baseline of 3 applies.

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

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

The description uses a specific verb ('flatten') and a clear resource ('an existing PDF's interactive form (AcroForm)'), and distinguishes the action from fill-related siblings by emphasizing removal of interactivity while preserving filled appearance. It is immediately obvious what the tool accomplishes.

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

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

It gives a concrete use case ('freeze values before distribution') and provides conditional guidance for special cases such as CJK text, fontPath, and tagged PDFs. It does not explicitly name an alternative sibling like fill_form, but the context clearly implies when flattening 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?

The description goes well beyond the annotations by detailing what is retained (metadata from the first file), what is lost (tagged structure, XMP, attachments, AcroForm, bookmarks), and how to detect or remediate losses via warnings and follow-up tools. This is rich, accurate behavioral disclosure and matches 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?

Every sentence contributes: the first states the action, the second discloses metadata and document-level loss, and the third provides actionable remediation. The structure front-loads the core behavior and uses the remaining space for high-value caveats. It is dense but not bloated.

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 schema fully documents all four parameters and annotations cover idempotence and read/write intent, the description completes the picture with merge order, metadata carry-over, page copying semantics, and loss remediation. Nothing essential to invoking the tool correctly or interpreting its behavior is missing.

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

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

The input schema already documents all parameters with 100% coverage, including inputPaths ordering, outputPath behavior, returnBase64, and allowBreakingSignatures. The description adds little parameter-specific meaning beyond reinforcing that merge order matters, which is already in the schema. 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 uses a specific verb (merge) with a clear resource (multiple PDFs) and scope (in the given order). It is immediately distinguishable from sibling tools like split_pdf, extract_pages, and create_text_pdf. The core action and result are unambiguous.

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

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

The description clearly implies that the tool is for combining multiple PDFs into one, and it suggests follow-up tools for restoring lost document-level features. However, it does not explicitly state when to use this tool versus alternatives or mention exclusions. The usage context is understandable but left largely 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 explicitly discloses that pages are copied into a new document, that document-level information such as tagged structure, XMP, attachments, AcroForm, and bookmarks is not carried over, and that lost items are reported in warnings. This goes well beyond what the annotations provide and helps the agent anticipate important side effects.

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 concise, front-loaded with the core operation, and every sentence carries meaningful guidance. It communicates the requirement, the data-loss behavior, and the remediation steps in three sentences without redundancy.

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 five parameters but the schema fully documents them, while the description covers the main behavioral caveat and follow-up actions. There is no output schema, but the description mentions warnings, and the returnBase64/outputPath parameter descriptions clarify output behavior. Minor gaps such as return-value detailing are adequately covered by schema and context.

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

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

Schema description coverage is 100%, so parameter names and types are already documented. The description adds crucial semantics not enforced by the schema—that 'order' must be a permutation listing every page exactly once—which is essential for calling the tool correctly.

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 the specific operation ('Reorder pages') and the essential constraint on the 'order' array (every page exactly once). This clearly distinguishes the tool from sibling operations like rotate_pages, extract_pages, and delete_pages.

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 context for use: reordering pages in a new document and following up with other tools to restore lost document-level features. It does not explicitly state when not to use this tool versus alternatives, but the lossiness caveat effectively communicates the tradeoff.

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?

Annotation contradiction: idempotentHint=true is inconsistent with a rotation operation, because a second identical 90-degree call produces a 180-degree result rather than the same result as the first call. The description also does not disclose side effects beyond the schema, such as signed-PDF handling or output behavior when outputPath is omitted.

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 concise sentence that front-loads the operation, degree range, and default page scope. Every phrase carries useful information and there is no redundant filler.

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

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

Given the six-parameter schema with full descriptions for outputPath, returnBase64, and allowBreakingSignatures, the terse description is largely sufficient for invocation. It loses one point because there is no output schema and the description itself leaves return-value behavior unstated, though the parameter docs compensate.

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 fully documents all six parameters. The description's 'All pages when pages is omitted' only restates the pages parameter's existing schema description and adds no new parameter meaning, which matches the baseline of 3.

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

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

The description states a specific verb and resource: rotate pages, with explicit clockwise directions (90/180/270 degrees) and default scope. This clearly distinguishes it from page-manipulation siblings like extract_pages, delete_pages, and reorder_pages without needing to open 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?

No explicit guidance on when to use rotate_pages versus alternatives such as reorder_pages or extract_pages. The only usage nuance provided, 'All pages when pages is omitted', describes parameter scope rather than tool selection, so the agent is left to infer 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 already set readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context: the partial-update preservation rule, XMP synchronization to prevent divergence, and the two distinct signed-PDF behaviors (preserveSignatures vs allowBreakingSignatures). These details go well beyond the annotations and help an agent predict side effects.

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, no fluff. The purpose is front-loaded, followed by the non-destructive update nuance, the XMP sync detail, and the signed-PDF handling. Each sentence earns its place, and the structure leads with the core action before edge cases.

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 mutation tool with 10 parameters and no output schema, the description covers the essential behavioral decisions an agent needs: partial updates, input requirement, XMP handling, and signature preservation. It omits the output/return behavior (base64 when outputPath omitted), but that is documented in the schema, so the description does not need to repeat it. Given the complexity, this is adequately complete.

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 enriches parameter understanding by stating that omitted fields are preserved, clarifying the effect of not passing title/author/etc. It also explains the interplay between preserveSignatures and allowBreakingSignatures (default error for signed PDFs). This adds meaning beyond the static schema 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 clearly states the tool updates an existing PDF's metadata (the Info dictionary), exactly specifying the resource and action. It also clarifies that only given fields change, distinguishing it from any creation or transformation tools. No ambiguity exists among siblings since none perform metadata updates.

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 implicitly states when to use it (when updating PDF metadata) and gives concrete usage conditions: 'At least one of title / author / subject / keywords / creator is required.' It also addresses the special case of signed PDFs with preserveSignatures. It does not explicitly exclude other tools, but no sibling operates on metadata, so the context 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?

The description goes well beyond the annotations by disclosing that document-level information is not carried over, that losses are reported in warnings, and by naming specific follow-up tools for repair. This is rich behavioral context that an agent would not otherwise know.

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

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

Three dense sentences, each earning its place: the core action, the file naming behavior, and the critical caveat with remediation. Information is front-loaded and there is 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?

For a multi-file creation tool with no output schema, the description covers naming, output location context, data-loss behavior, warnings, and recommended follow-ups. Combined with the fully documented input schema, an agent has enough to invoke it correctly and anticipate side effects.

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 meaningful parameter semantics: it explains that each ranges element becomes one file and defines the naming pattern as '<prefix>1.pdf', '<prefix>2.pdf', etc. This connects ranges and prefix in a way the schema alone does not.

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 a PDF into multiple files by page range.' It also explains the one-file-per-range behavior, which is precise. However, it does not explicitly distinguish itself from the sibling tool 'extract_pages,' so it stops short of the full 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 usage is implied through the description of splitting by page range and generating multiple files. There is no explicit when-to-use or when-not-to-use guidance, nor are alternatives like 'extract_pages' mentioned. The follow-up tool list is about post-processing, not selection among siblings.

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 indicate a non-read-only, idempotent, non-destructive operation. The description adds useful behavioral context beyond those hints: tagged PDFs keep PDF/UA conformance via Artifact wrapping, and CJK formats require a fontPath or environment variable. This does not contradict 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?

Two sentences carry the core action first and the key exceptions second. Every sentence adds information without repeating schema defaults or parameter 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?

The schema fully documents parameters, defaults, ranges, enum, and base64-output behavior, and the description contributes the non-obvious PDF/UA and CJK caveats. The main missing piece is alternative-selection guidance, but that is more a usage-guidelines gap than an invocation-completeness 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 adds no real parameter meaning beyond the schema; the note about CJK and fontPath essentially repeats what the fontPath parameter already states.

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 the specific action and resource: 'Stamp a page number on each page.' This distinguishes the tool from siblings like add_watermark or add_annotation, and the additional tagged-PDF/Artifact detail reinforces its niche.

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

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

There is no guidance on when to choose this tool over sibling tools such as add_watermark or add_annotation, and no when-not-to-use conditions. The CJK font requirement is a prerequisite, not guidance about choosing among 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?

Annotations declare mutation (readOnlyHint false) and idempotency (idempotentHint true). The description reinforces idempotency and adds crucial behavior not in annotations: signature handling (preserveSignatures vs allowBreakingSignatures, certification refusal) and skipping of already-bound widgets. 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 a single dense paragraph but well-organized, front-loading the core action and then layering idempotency, scope, and signature behavior. Every sentence carries information; no fluff 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 tool's complexity (6 parameters, nested labels object, no output schema), the description covers scope, idempotency, signature rules, and outputPath fallback behavior. An agent has enough context to invoke it correctly without seeking external details.

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 tool description adds only a brief summary of the labels parameter ('Pass human-readable names for screen readers via labels') which is already elaborated in the schema. It does not materially extend parameter meaning beyond the schema.

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

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

The description opens with a precise action ('Repair a tagged PDF's form to PDF/UA-1') and enumerates the exact technical steps (enclose Widget annotations, set /Tabs S, set /TU). It clearly separates this from siblings like fill_form, flatten_form, and ensure_tagged, which have different goals.

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

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

Explicitly states untagged documents are out of scope and directs to run ensure_tagged first or use create tools with tagged: true. Also notes idempotency ('safe to run repeatedly'), giving agents clear when-to-use and when-not-to-use guidance, though it doesn't explicitly compare to form-filling tools.

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