pdfnative-mcp

Fill / flatten an existing AcroForm

fill_form

Idempotent

Fill AcroForm fields in an existing PDF and optionally flatten them, preserving prior signatures by writing an incremental update.

Instructions

Fill and/or flatten the AcroForm of an EXISTING PDF (add_form creates one) as an incremental update — prior signatures stay valid for their revision. values: fully-qualified name → string (array for multi-select), boolean or export state for checkbox/radio. flatten:true stamps appearances and drops the interactive layer (with no values = pure flatten). Unknown names → FORM_FIELD_NOT_FOUND unless onUnknownField:'ignore'; signature fields cannot be filled (FORM_UNSUPPORTED). Encrypted sources: password.

Input Schema

Name	Required	Description	Default
`values`	No	Map of fully-qualified field name → value. Text/choice: a string (array of strings for multi-select listboxes). Checkbox/radio: a boolean or the export-state string. Omit (or pass {}) with flatten:true for a pure flatten.
`flatten`	No	When true, stamp appearances into page content and remove the interactive fields after filling.
`password`	No	Password (user or owner) of an encrypted source. Never logged or echoed.
`pdfBase64`	Yes	Base64-encoded source PDF containing the AcroForm to fill. Use read_form_fields first to discover field names.
`nonWinAnsi`	No	Behaviour when a value contains non-WinAnsi characters (appearance font is Helvetica/WinAnsi). 'throw' (default) rejects it; 'needAppearances' writes the value and sets /NeedAppearances so the viewer regenerates the appearance.	throw
`outputMode`	No	'base64' (default) returns the PDF inline; 'file' writes it inside the PDFNATIVE_MCP_OUTPUT_DIR sandbox (SECURITY_VIOLATION when the sandbox is not configured).	base64
`outputPath`	No	Required when outputMode='file'. Relative path inside the sandbox; must end with .pdf.
`onUnknownField`	No	Behaviour for a value key that matches no field. 'throw' (default) → FORM_FIELD_NOT_FOUND; 'ignore' skips it.	throw

Output Schema

Name	Required	Description
`url`	No	Public URL of the file (file mode, only when PDFNATIVE_MCP_OUTPUT_BASE_URL is set): base URL + sandbox-relative path, percent-encoded.
`mode`	Yes
`summary`	No	Tool-specific summary, when produced.
`filePath`	No	Sandboxed absolute path (file mode).
`sizeBytes`	Yes
`diagnostics`	No	Engine diagnostics (when includeDiagnostics=true).

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.8.0Nov 3, 2026

changedOutput schema / description

Previous value: -"Result of a PDF-producing tool. base64 mode: the PDF arrives as an embedded `resource` content block (not duplicated here); file mode: `filePath`."New value: +"Result of a PDF-producing tool. base64 mode: the PDF arrives as an embedded `resource` content block (not duplicated here); file mode: `filePath` (and `url` when the operator maps the sandbox to a public base URL)."

addedOutput schema / properties / url

Added value: +{
+  "description": "Public URL of the file (file mode, only when PDFNATIVE_MCP_OUTPUT_BASE_URL is set): base URL + sandbox-relative path, percent-encoded.",
+  "type": "string"
+}

Changed1 schema field changedv1.6.2Sep 27, 2026

changedOutput schema / properties / diagnostics / description

Previous value: -"PDF/A diagnostics (when includeDiagnostics=true)."New value: +"Engine diagnostics (when includeDiagnostics=true)."

AddedAug 24, 2026

TDQS

A3.9/5.0

Behavior3/5

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

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

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

Conciseness4/5

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

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

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

Completeness4/5

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

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

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

Parameters3/5

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

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

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

Purpose5/5

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

States a specific verb pair (fill/flatten) against a specific resource (the AcroForm of an EXISTING PDF) and explicitly contrasts with the sibling add_form, which creates one. An agent can distinguish this from add_form and read_form_fields without opening any schema.

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

Usage Guidelines4/5

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

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

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