Skip to main content
Glama
pdfops

pdfops-mcp

Official
by pdfops
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Fill PDF form

pdf_fill
Idempotent

Fill AcroForm fields in any PDF and save the completed form or return it inline. Values are validated against existing field definitions, and the source file stays unchanged.

Instructions

Fill AcroForm form fields in a PDF and save or return the result. Field names must exist in the PDF (use pdf_inspect first). All values are strings; checkboxes take "true"/"false"; dropdown/radio/optionlist values must be one of the field's options; text values must respect the field's maxLength from pdf_inspect. The source PDF is never modified. Returns the filled PDF written to output_path, or inline as an application/pdf resource when output_path is omitted; an existing file at output_path is overwritten. Encrypted PDFs are rejected with decrypt advice (common for government blanks with an empty user password), and a rejected fill writes no file at all.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
fieldsYesField name → string value (from pdf_inspect's fillTemplate)
flattenNoBake values into page content and drop the AcroForm so fields are no longer editable
pdf_pathYesTemplate PDF source: an absolute file path, an https:// URL, or a data:application/pdf;base64,… URI. Use a URL or data URI when this server runs remotely (Smithery, hosted gateways) where local paths do not exist.
output_pathNoAbsolute path to write the result. Omit when running remotely: the PDF is then returned inline as an application/pdf resource for the client to save.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
bytesYesSize of the produced PDF in bytes
output_pathNoAbsolute path written, when output_path was supplied
resource_uriNopdfops:// uri of the inline application/pdf resource, when output_path was omitted

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.3.2
    • changedInput schema / properties / output_path / description
      Previous value: -"Absolute path to write the filled PDF"New value: +"Absolute path to write the result. Omit when running remotely: the PDF is then returned inline as an application/pdf resource for the client to save."
    • changedInput schema / properties / pdf_path / description
      Previous value: -"Absolute path to the template PDF"New value: +"Template PDF source: an absolute file path, an https:// URL, or a data:application/pdf;base64,… URI. Use a URL or data URI when this server runs remotely (Smithery, hosted gateways) where local paths do not exist."
    • changedInput schema / required
      Previous value: -[
-  "pdf_path",
-  "fields",
-  "output_path"
-]New value: +[
+  "pdf_path",
+  "fields"
+]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "bytes": {
+      "description": "Size of the produced PDF in bytes",
+      "type": "integer"
+    },
+    "output_path": {
+      "description": "Absolute path written, when output_path was supplied",
+      "type": "string"
+    },
+    "resource_uri": {
+      "description": "pdfops:// uri of the inline application/pdf resource, when output_path was omitted",
+      "type": "string"
+    }
+  },
+  "required": [
+    "bytes"
+  ],
+  "type": "object"
+}
  2. First observedv0.2.0

TDQS

A4.6/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

Deploy Server

Other Tools