pdfops-mcp

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

Goes well beyond the annotations by disclosing that the source PDF is never modified, that the filled PDF is returned inline as an application/pdf resource, and that encrypted PDFs are rejected with decrypt advice. This adds concrete behavioral context (idempotent rewrite into a new artifact, encryption failure mode) that readOnlyHint/destructiveHint alone do not convey.

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

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

Every sentence carries a distinct, decision-relevant rule (purpose, prerequisite, value typing, immutability, return format, encryption failure) with the core action front-loaded in the first clause. No filler or restatement of the name 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?

Covers the prerequisite tool, input value constraints, immutability guarantee, encryption error path, and output delivery method for a tool with nested object params and an output schema. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: all values are strings, checkboxes take "true"/"false", dropdown/radio/optionlist values must be one of the field's options, and text values must respect maxLength from pdf_inspect. It is not a 5 because 'flatten' is only explained by the schema, not the description.

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

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

States a specific verb and resource ('Fill AcroForm form fields in a PDF') plus the return behavior ('return the result'). Names the sibling pdf_inspect as a prerequisite, so an agent can distinguish it from pdf_merge/pdf_invoice without opening any schema.

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

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

Gives an explicit sequencing instruction ('Field names must exist in the PDF (use pdf_inspect first)'), which tells the agent when to reach for this tool and what must precede it. It stops short of stating when NOT to use it or comparing it against pdf_merge/pdf_invoice, so it is clear context without full alternative routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real behavioral context beyond them: XFA data loss on hybrid inputs when filled, and the fill-time rejection semantics of unknown/over-length fields. The 'read-only, never modified' sentence partially duplicates readOnlyHint, which keeps this from a 5.

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

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

Three front-loaded sentences with no filler: what is returned, the XFA/empty-form caveats, then the read-only guarantee and the call-first guidance. Every clause carries actionable 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?

An output schema exists, yet the description still usefully summarizes the return shape, and it covers the one input constraint, the ordering prerequisite relative to pdf_fill, and the data-loss caveat. Nothing needed to call it correctly is missing.

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

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

Only one parameter (pdf_path) and schema description coverage is 100%, so the schema already specifies the accepted URL/data-URI forms and the no-local-paths limitation. The description adds no parameter-level detail, so 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?

States a specific verb + resource (list AcroForm form fields) and enumerates exactly what is returned: names, types, options, current values, maxLength, plus a fillTemplate object and hasXFA flag. It also implicitly distinguishes itself from pdf_fill by being the read-side counterpart.

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 to call this FIRST when filling an unfamiliar PDF and names the reason (pdf_fill rejects unknown field names and over-length values), which routes the agent to the correct sibling and ordering. It also states the empty-form case ('returns count 0') so the agent knows how to interpret a null result.

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 and openWorldHint, and the description reinforces determinism ('byte-identical output, safe to re-run') plus two facts not in annotations: the unlicensed watermark footer and the inline application/pdf return format. It stops short of stating auth/permission requirements beyond the key note, so it adds real value without being exhaustive.

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, front-loaded with the core capability before the determinism, watermark, and routing notes. Every sentence carries actionable information with no padding.

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 single-parameter nested-object tool with an output schema and rich annotations, the description covers the value proposition, determinism, licensing caveat, return format, and sibling routing. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the single nested invoice object is fully documented in-schema (date format, currency pattern, item constraints), so the description adds no parameter-level detail. Baseline 3 is appropriate when 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?

States a specific verb (Generate) and resource (invoice PDF) with scope ('from structured data — no template needed'). It explicitly names the sibling it is not (pdf_fill) and the condition that distinguishes them, so an agent can route 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?

Gives explicit when-to-use ('when you have invoice DATA and no document') and when-not ('if you already have an invoice PDF or a fillable template... use pdf_fill instead'). The alternative is named with its selecting condition, 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?

Goes well beyond annotations by disclosing that sources are read-only and never modified, that the output is returned inline as an application/pdf resource, that only whole documents are concatenated, and that failures abort rather than yield a partial merge. Consistent with readOnlyHint=false (it produces a new artifact) with 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?

Front-loads the core action and return type, then scopes limits and alternatives. Every sentence carries distinct 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?

An output schema exists so return details are optional, yet the description still confirms the inline resource form and error behavior. For a one-param merge tool with sibling alternatives, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and there is a single param, so the schema already defines the accepted URI forms. The description still adds value by emphasizing 'in the order given', clarifying that array ordering is semantically significant.

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

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

States a specific verb and resource (merge PDFs into one, in order given) plus the return form. It distinguishes itself from siblings by naming pdf_fill and pdf_invoice as the tools for non-concatenation tasks.

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 scopes when to use this vs alternatives: only whole-document concatenation, no reorder/rotate/delete, and names pdf_fill and pdf_invoice with the conditions that select them. Includes the negative case (unreadable input fails).

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: it discloses the auth dependency ('Uses the API key this connection authenticated with'), which is not derivable from the annotations.

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

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

Two compact sentences, front-loaded with the core action, then the return payload, then the safe-to-call guidance. No filler or 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?

An output schema exists, so the description needn't explain return values, and the annotations cover safety. The addition of auth scoping and the pre-batch use case makes this complete for a no-param read 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?

Zero parameters, so the baseline is 4 per the rubric. There is nothing further the description could add on parameter 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?

States a specific verb+resource ('Check the current PDFops API quota') and enumerates the exact fields returned. It is unmistakably distinct from the pdf_* operation siblings, which all act on documents rather than account state.

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?

Provides clear usage context: 'Read-only and safe to call before a batch to confirm there is headroom,' which tells the agent when to reach for it. It stops short of naming alternatives or explicit when-not-to-use conditions, so it falls 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.