pdfnative-mcp

Add a document timestamp (PAdES B-LTA)

timestamp_pdf

Append an RFC 3161 PAdES document timestamp to a PDF to extend long-term signature validity. Run it after adding LTV validation data, before the TSA certificate expires.

Instructions

PAdES B-LTA: append an RFC 3161 document timestamp (/DocTimeStamp, ETSI.RFC3161) over the whole document. Ladder step 4 after add_ltv; re-run before the TSA certificate expires. fieldName omitted → DocTimeStamp1, 2, …; a fieldName colliding with a signed field fails. Uses the OPERATOR TSA (PDFNATIVE_MCP_TSA_URL; TSA_NOT_CONFIGURED otherwise, no network without it). The token's status, imprint and nonce are checked before embedding (its own signature is verified by verify_pdf). Unencrypted PDFs only.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`fieldName`	No	Signature field name for the timestamp. Omit it to get 'DocTimeStamp1', 'DocTimeStamp2', … auto-suffixed on each re-timestamp; an explicit name that collides with an existing signed field fails.
`pdfBase64`	Yes	Base64-encoded PDF (unencrypted). Typically already signed (+ add_ltv) — a document timestamp on an unsigned PDF is allowed but proves only existence at that time.
`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').
`placeholderBytes`	No	Room reserved for the TimeStampToken (default 12288). Raise it for TSAs that return large certificate chains.

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	Engine diagnostics (when includeDiagnostics=true).

Schema Changelog

Changes observed during successful MCP inspections.

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.4/5.0

Behavior5/5

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

Goes well beyond the annotations: discloses the OPERATOR TSA requirement, the TSA_NOT_CONFIGURED failure mode and absence of network without it, pre-embedding checks on status/imprint/nonce, fieldName collision failure, and re-run-before-expiry semantics that explain the non-idempotent annotation.

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?

Dense and front-loaded — the PAdES level and operation lead, with error modes and constraints following. Every sentence carries distinct information, though the single long block could be broken up for faster scanning.

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?

An output schema exists so return values need no explanation; the description instead covers the prerequisites (operator TSA, unencrypted PDF), failure modes (TSA_NOT_CONFIGURED, field collision, SECURITY_VIOLATION), and ladder placement — everything an agent needs to call it correctly.

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 schema already documents every parameter including fieldName auto-suffixing, outputMode sandbox errors, and placeholderBytes sizing. The description largely restates the fieldName rules rather than adding syntax or constraints beyond the schema, making the baseline 3 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?

States a specific verb+resource ('append an RFC 3161 document timestamp over the whole document') and locates itself precisely in the ladder ('step 4 after add_ltv'), distinguishing it from siblings add_ltv and verify_pdf 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?

Explicit sequencing guidance ('Ladder step 4 after add_ltv; re-run before the TSA certificate expires') and a hard exclusion ('Unencrypted PDFs only'). It stops short of naming when an agent should prefer verify_pdf or add_ltv instead, so it is clear context without full when-not routing.

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