pdfnative-mcp

Fill / flatten an existing AcroForm

fill_form

Idempotent

Fill AcroForm fields in an existing PDF with text, choices, or booleans, and optionally flatten them into page content while preserving existing digital signatures.

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

TableJSON 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

TableJSON Schema

Name	Required	Description
`mode`	Yes
`summary`	No	Tool-specific summary, when produced.
`filePath`	No	Sandboxed absolute path (file mode).
`sizeBytes`	Yes
`diagnostics`	No	PDF/A diagnostics (when includeDiagnostics=true).

Schema Changelog

Changes observed during successful MCP inspections.

AddedAug 24, 2026

TDQS

A4.7/5.0

Behavior5/5

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

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

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

Conciseness5/5

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

The description is compact yet information-dense, roughly five sentences cover target, sibling distinction, value syntax, flatten behavior, error modes, fir signature constraints, and encryption. Every sentence adds a factual constraint needed for safe invocation, and the most important scoping information is front-loaded.

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

Completeness5/5

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

For a tool with 8 parameters, 1 requirement, nested values, and an output schema, the description plus rich parameter descriptions are complete enough. It covers the main failure modes and non-obvision side effects, while the output schema handles return value explanations, so nothing necessary for correct invocation is missing.

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

Parameters3/5

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

Schema description coverage is 100% and every parameter including `values`, `flatten`, `onUnknownField`, and `password` has a detailed description already. The tool description provides a high-level summary of value types and flatten semantics, but it does not add meaningful information beyond what the input schema already supplies, so baseline 3 is appropriate.

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

Purpose5/5

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

The description opens with a specific verb and target: 'fill and/or flatten the AcroForm of an EXISTING PDF'. It immediately distinguishes this from add_form by parenthetically identifying that sibling as the creation tool, so an agent can identify the exact resource and action.

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

Usage Guidelines5/5

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

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

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