pdfnative-mcp

Update document metadata

update_metadata

Rewrite /Info metadata (title, author, subject, keywords) of an existing PDF as an incremental update; XMP stays in sync and prior revisions/signatures remain byte-identical.

Instructions

Rewrite /Info (title, author, subject, keywords) of an EXISTING PDF as an incremental update; XMP stays in sync on PDF/A documents; /ModDate is refreshed (pin modDate for reproducible bytes). Earlier revisions and signatures stay byte-identical — the new revision is unsigned (sign_pdf / timestamp_pdf again if needed). Encrypted sources → ENCRYPTED_SOURCE. For metadata at generation time use the metadata option of the document tools.

Input Schema

Name	Required	Description	Default
`title`	No	New /Info /Title (mirrored to XMP dc:title when the document carries XMP).
`author`	No	New /Info /Author (XMP dc:creator).
`modDate`	No	ISO-8601 modification instant for /ModDate and xmp:ModifyDate. Defaults to now; pin it for reproducible output.
`subject`	No	New /Info /Subject (XMP dc:description).
`keywords`	No	New /Info /Keywords (XMP pdf:Keywords).
`pdfBase64`	Yes	Base64-encoded PDF to update (unencrypted).
`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	Relative path inside PDFNATIVE_MCP_OUTPUT_DIR (required when outputMode='file').

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

A4.7/5.0

Behavior5/5

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

Beyond the annotations, it discloses incremental-update semantics, preservation of earlier revisions and signatures, the unsigned status of the new revision, PDF/A XMP synchronization, ModDate refresh behavior, and the ENCRYPTED_SOURCE failure. These details directly affect reproducibility, safety expectations, and post-call workflows.

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 dense but efficient, with the core operation front-loaded and constraints, consequences, and alternatives compressed into clear clauses. There is no filler, and each statement provides actionable information.

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 an eight-parameter mutation with complete input and output schemas, this supplies the important operational context: input restrictions, revision and signature effects, reproducibility, failure behavior, and the generation-time alternative. Output routing and sandbox requirements are already covered by the schema, so their absence from the description is not a gap.

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 coverage is 100%, and the description largely restates information already present there: the metadata fields, unencrypted input, and pinning `modDate` for reproducibility. It adds little parameter-specific meaning beyond the schema, so the high-coverage baseline applies.

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 opening clause precisely identifies the operation, resource, and scope: rewriting /Info fields of an existing PDF as an incremental update. It also distinguishes this from setting metadata during document generation, making selection among sibling tools straightforward.

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 routes generation-time metadata to the document tools' `metadata` option and directs the agent to `sign_pdf` or `timestamp_pdf` again when needed. The existing-PDF requirement and encrypted-source error further clarify when the tool is unsuitable.

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