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

The description goes well beyond the annotations: it explicitly states the source PDF is never modified, an existing output file is overwritten, encrypted PDFs are rejected with decrypt advice, and a rejected fill writes no file. These are important behavioral details not present in 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 dense but well-organized, front-loading the core action and then covering prerequisites, value formats, safety behavior, and error handling. Every clause contributes useful information, though it is longer than strictly necessary.

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 form-filling tool with an output schema and annotations, the description covers all necessary operational aspects: validation via pdf_inspect, value constraints, output file vs inline behavior, overwrite semantics, source immutability, and encrypted-file handling. The agent has enough context 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?

While the schema already has 100% parameter coverage, the description adds crucial semantic detail beyond the schema: checkbox values must be "true"/"false", dropdown/radio values must match field options, text values must respect maxLength, and fields are always strings. This meaningfully helps the agent construct valid parameter values.

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 and resource: "Fill AcroForm form fields in a PDF and save or return the result." It clearly distinguishes this tool from siblings like pdf_inspect, pdf_merge, and pdf_invoice by focusing on form filling.

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: use pdf_inspect first to get field names, follow field-specific value constraints, and omit output_path when running remotely to get an inline result. It does not explicitly contrast with all sibling tools, but the prerequisites and conditions are specific enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'never modified' statement is consistent with them — no contradiction. It adds genuinely useful context beyond the annotations: the hasXFA caveat that hybrid AcroForm/XFA inputs 'lose their XFA layer when filled' and the count-0 edge case for PDFs with no fillable form.

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 zero fluff: the core return value is front-loaded, the edge case occupies one short sentence, and the workflow guidance closes it out. The parenthetical XFA caveat is dense but earns its place because it warns of a destructive downstream side effect an agent would otherwise discover only after filling.

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 single well-documented parameter, a full safety profile in annotations, and an output schema present, the bar is low and the description clears it easily. It covers purpose, return contents, the no-fields edge case, the XFA caveat, and ordering relative to pdf_fill — nothing an agent needs to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so the parameter semantics are fully carried by the input schema, which already documents absolute paths, https URLs, data URIs, and the remote-server caveat. Baseline 3 applies; the description's 'fetched or read' phrasing loosely reinforces the URL/data-URI guidance but adds no new parameter-level 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 starts with a specific verb and resource — 'List a PDF's AcroForm form fields' — and enumerates exactly what is returned (names, types, options, values, maxLength, a paste-ready fillTemplate, and a hasXFA flag). It distinguishes itself from the sibling pdf_fill by framing the output as direct input for that tool, so an agent can tell them apart without opening either schema.

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

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

The final sentence gives explicit when-to-use guidance: 'Call this FIRST when filling an unfamiliar PDF,' and justifies it with a concrete failure mode of the alternative — 'pdf_fill rejects unknown field names and over-length values.' This names the alternative, the triggering condition, and the rationale, leaving nothing to inference.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds valuable behavioral context beyond those hints: it states the output is byte-identical for the same input, safe to re-run, overwrites existing files at output_path, and includes a footer without a paid key. These are meaningful operational details an agent needs to invoke and reason about the tool correctly.

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 information-dense but tightly structured, with the core purpose first, followed by determinism, licensing footer, output behavior, and sibling routing. Every sentence adds distinct value and none are redundant with the schema or annotations.

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

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

Given the nested invoice schema, annotations, and output schema, the description covers all essential operational aspects: what the tool does, when to use it, what output to expect, side effects like overwriting, determinism guarantees, and licensing-related watermarking. No important invocation-relevant 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 baseline is 3. The description goes beyond the schema by explaining the output_path behavior: omitting it returns the PDF inline as an application/pdf resource, while providing it writes to that path and overwrites existing files. It also clarifies that the invoice parameter is structured data, reinforcing the 'no template needed' claim.

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 ('generate') and resource ('invoice PDF'), and further clarifies it produces a complete professionally laid-out PDF from structured data with no template needed. It explicitly distinguishes itself from pdf_fill, which handles existing PDFs or fillable templates, making sibling differentiation clear.

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: use when you have invoice DATA and no document. It also names the alternative (pdf_fill) and the condition for choosing it, i.e., if you already have an invoice PDF or a fillable template. This leaves no ambiguity about tool selection.

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 excellent behavioral detail: sources are never modified, an existing output_path is overwritten, failures write no file, and no partial merge is left behind. However, the explicit overwrite statement contradicts destructiveHint=false, which indicates the tool performs no destructive operations. Per the rubric, this annotation contradiction forces 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?

The description is tightly written and front-loaded: operation, safety/overwrite behavior, return behavior, exclusions, and failure semantics each get one clear sentence. No sentence is filler.

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

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

The description covers return format, remote vs local invocation, failure atomicity, and exclusions of related tools. Given the schema and output schema already exist, nothing an agent needs to invoke this tool correctly is missing apart from the annotation conflict already flagged.

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 both parameters already have detailed descriptions, so the baseline is 3. The description reinforces ordering and the inline return when output_path is omitted, but it does not add parameter meaning beyond what the schema provides.

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

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

Opens with a specific verb and resource: 'Merge two or more PDFs into one, in the order given'. It also distinguishes itself from siblings by explicitly stating it does not fill forms and by routing to pdf_fill and pdf_invoice, so an agent can select it confidently.

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

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

Explicitly says when to use alternatives: 'use pdf_fill for a fillable form and pdf_invoice to build a document from data.' It also gives conditional guidance for output_path (omit when running remotely) and notes it only concatenates whole documents, providing a clear boundary versus related tools.

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

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

Annotations already mark it read-only, idempotent, and non-destructive; the description adds a prerequisite ('Requires PDFOPS_API_KEY') and clarifies that it performs no mutation and is safe for pre-batch checks. This meaningfully supplements the annotation metadata.

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: the first states the resource and expected return fields, and the second covers safety, usage timing, and configuration requirements. There is no filler or redundant restatement.

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 zero parameters, rich annotations, and an output schema, the description supplies all necessary extra context: what to expect, when to call it, and the required environment variable. Nothing important 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 is empty with 100% coverage, so the baseline is 4 for zero parameters. The description adds no parameter details, but none are needed.

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

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

The description names a specific verb ('Check'), a specific resource ('current PDFops API quota for the configured key'), and enumerates the returned fields (tier, limit, used, remaining, billing period, reset timestamp). This clearly separates it from sibling tools like pdf_fill and pdf_merge, which are about document operations.

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

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

It gives an explicit use case: 'safe to call before a batch to confirm there is headroom.' It does not explicitly name sibling alternatives or state when not to use the tool, but the context is strong enough for an agent to select it correctly.

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