pdfnative-mcp

Inspect PDF metadata

inspect_pdf

Read-onlyIdempotent

Extract read-only PDF facts: version, page count, encryption, signatures, PDF/A claims. Turn them into CI assertions for signed, encrypted, or PDF/A checks.

Instructions

Read-only facts about a PDF: version, pageCount, encryption, pdfA claim (the claim, not its validity — use veraPDF for that), signatureCount, hasSignaturePlaceholder, attachments[], info; presence-gated dss / docTimestampCount / trapped; signatures:true lists every field (subFilter, isDocTimestamp, isPlaceholder, byteRange, vriKey); pages:true adds per-page sizes and boxes. check:[…] turns it into a CI assertion ('pdfa','signed','encrypted','placeholder','attachments','dss','docTimestamp','trapped') → checks (requested keys only) + checksPassed. Encrypted sources: pass password. Token-frugal: verbosity:'summary', fields:[…].

Input Schema

TableJSON Schema

Name	Required	Description	Default
`check`	No	CI assertions → checks (requested keys only) + checksPassed (all hold). 'signed' = a signature field with signed content exists (structural; validity is verify_pdf's job), 'placeholder' = an unsigned placeholder exists, 'dss' = /DSS present, 'docTimestamp' = a /DocTimeStamp exists, 'trapped' = /Info /Trapped set, 'annotations' = at least one page annotation exists, 'pdfx' = the XMP claims PDF/X (the claim, not its validity — validate_pdf standard:'pdf-x-4').
`pages`	No	When true, include per-page metadata in the response.
`fields`	No	Optional dot-path projection applied to the structured result (e.g. ['pageCount','signatureCount']). Composes after verbosity. Unknown paths are omitted.
`password`	No	Password (user or owner) of an encrypted source. Never logged or echoed.
`pdfBase64`	Yes	Base64-encoded PDF bytes to inspect.
`verbosity`	No	'full' (default) or 'summary' (scalars only: version, pageCount, encryption, pdfA, signatureCount, hasSignaturePlaceholder, attachmentCount, + docTimestampCount / trapped / pdfX / checksPassed when present; arrays and dss dropped).	full
`signatures`	No	When true, include a signatures[] array describing every signature field (field name, SubFilter, document-timestamp flag, placeholder flag, ByteRange, /Contents length, /VRI key). Off by default to keep responses compact.
`annotations`	No	When true, include an annotations[] array listing every page annotation (/Annots: links, text notes, highlights, shapes, widgets…) with its 0-based page, subtype, rect and, when present, contents (truncated to 200 chars), title, color, quadPoints and link url. Off by default to keep responses compact.

Output Schema

TableJSON Schema

Name	Required	Description
`dss`	No	Document Security Store summary (ISO 32000-2 §12.8.4.3), present only when the catalog has a /DSS.
`info`	No	Document /Info dictionary entries decoded as strings.
`pdfA`	No	Detected PDF/A claim (e.g. '1B', '2B', '2U', '3B') from XMP metadata, or null when absent.
`pdfX`	No	PDF/X claim from XMP (pdfxid:GTS_PDFXVersion, e.g. 'PDF/X-4'), present only when the document makes one. A claim, not a verdict: validate_pdf standard:'pdf-x-4' checks it.
`checks`	No	One boolean per REQUESTED check (keys = the check[] you passed, nothing else).
`perPage`	No
`trapped`	No	/Info /Trapped flag, present only when the document carries one.
`version`	No	PDF version (e.g. "1.7").
`pageCount`	No
`encryption`	No
`pageLabels`	No	Logical page-numbering ranges from the /PageLabels number tree (ISO 32000-1 §12.4.2), or absent when the document has none. Each range gives the 0-based first page, numbering style, optional prefix and start value.
`signatures`	No	Signature fields (opt-in via the `signatures` input). Document timestamps are listed inline with isDocTimestamp=true.
`annotations`	No	Page annotations (opt-in via the `annotations` input), in page order then /Annots order. Only the keys the annotation actually carries are emitted.
`attachments`	No	Embedded files exposed via /Names → /EmbeddedFiles (PDF/A-3, Factur-X).
`checksPassed`	No	Present when check[] was supplied: true when every requested check holds.
`encryptionInfo`	No	Precise Standard Security Handler details (pdfnative v1.6.0), present only when the document is encrypted and was opened successfully. Objects served by the reader are already decrypted.
`signatureCount`	No
`annotationCount`	No	Total number of page annotations (opt-in via the `annotations` input).
`attachmentCount`	No	summary only: number of embedded files.
`docTimestampCount`	No	Number of /DocTimeStamp signature fields, present only when at least one exists.
`hasSignaturePlaceholder`	No	True when at least one signature widget exists with empty /Contents — i.e. an unsigned placeholder awaiting `sign_pdf`.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv1.6.2Sep 27, 2026

changedInput schema / properties / check / description

Previous value: -"CI assertions → checks (requested keys only) + checksPassed (all hold). 'signed' = a signature field with signed content exists (structural; validity is verify_pdf's job), 'placeholder' = an unsigned placeholder exists, 'dss' = /DSS present, 'docTimestamp' = a /DocTimeStamp exists, 'trapped' = /Info /Trapped set, 'annotations' = at least one page annotation exists."New value: +"CI assertions → checks (requested keys only) + checksPassed (all hold). 'signed' = a signature field with signed content exists (structural; validity is verify_pdf's job), 'placeholder' = an unsigned placeholder exists, 'dss' = /DSS present, 'docTimestamp' = a /DocTimeStamp exists, 'trapped' = /Info /Trapped set, 'annotations' = at least one page annotation exists, 'pdfx' = the XMP claims PDF/X (the claim, not its validity — validate_pdf standard:'pdf-x-4')."

changedInput schema / properties / check / items / enum

Previous value: -[
-  "pdfa",
-  "signed",
-  "encrypted",
-  "placeholder",
-  "attachments",
-  "dss",
-  "docTimestamp",
-  "trapped",
-  "annotations"
-]New value: +[
+  "pdfa",
+  "signed",
+  "encrypted",
+  "placeholder",
+  "attachments",
+  "dss",
+  "docTimestamp",
+  "trapped",
+  "annotations",
+  "pdfx"
+]

changedInput schema / properties / check / maxItems
```
Previous value: -9New value: +10
```

changedInput schema / properties / verbosity / description

Previous value: -"'full' (default) or 'summary' (scalars only: version, pageCount, encryption, pdfA, signatureCount, hasSignaturePlaceholder, attachmentCount, + docTimestampCount / trapped / checksPassed when present; arrays and dss dropped)."New value: +"'full' (default) or 'summary' (scalars only: version, pageCount, encryption, pdfA, signatureCount, hasSignaturePlaceholder, attachmentCount, + docTimestampCount / trapped / pdfX / checksPassed when present; arrays and dss dropped)."

addedOutput schema / properties / pdfX

Added value: +{
+  "description": "PDF/X claim from XMP (pdfxid:GTS_PDFXVersion, e.g. 'PDF/X-4'), present only when the document makes one. A claim, not a verdict: validate_pdf standard:'pdf-x-4' checks it.",
+  "type": "string"
+}

AddedAug 24, 2026
Removedv1.6.0Jul 22, 2026

Changed1 schema field changedv1.4.0Jul 5, 2026

addedOutput schema / properties / pageLabels

Added value: +{
+  "description": "Logical page-numbering ranges from the /PageLabels number tree (ISO 32000-1 §12.4.2), or absent when the document has none. Each range gives the 0-based first page, numbering style, optional prefix and start value.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "prefix": {
+        "type": "string"
+      },
+      "start": {
+        "type": "integer"
+      },
+      "startPage": {
+        "minimum": 0,
+        "type": "integer"
+      },
+      "style": {
+        "enum": [
+          "decimal",
+          "roman",
+          "Roman",
+          "alpha",
+          "Alpha",
+          "none"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "startPage"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed2 schema fields changedv1.2.0Jun 24, 2026

addedInput schema / properties / fields

Added value: +{
+  "description": "Optional dot-path projection applied to the structured result (e.g. ['pageCount','signatureCount']). Composes after verbosity. Unknown paths are omitted.",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 16,
+  "type": "array"
+}

addedInput schema / properties / verbosity

Added value: +{
+  "default": "full",
+  "description": "Response verbosity. 'full' (default) returns every field; 'summary' returns a token-frugal scalar subset (version, pageCount, encryption, pdfA, signatureCount, hasSignaturePlaceholder, attachmentCount) — drops the attachments[], info and perPage arrays.",
+  "enum": [
+    "summary",
+    "full"
+  ],
+  "type": "string"
+}

First observedv1.1.0Jun 20, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: encrypted sources require a `password`, `check` returns only requested keys plus a `checksPassed` aggregate, and the tool is deliberately token-frugal via verbosity/fields. Nothing about failure modes or limits beyond that, hence not a 5.

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 but front-loaded: the core output shape comes first, optional flags next, encryption and token notes last. Backtick-heavy jargon makes it terse rather than skim-friendly, but every clause carries 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 8-parameter inspection tool with an output schema, the description covers everything an agent needs: scope, field/claim distinction, CI-mode behavior, password handling and compactness controls. Return values are also briefly mapped even though the output schema carries them.

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 the description largely restates what the schema already documents (check semantics, signatures/pages flags, verbosity contents). It adds little parameter meaning beyond the schema, though the 'composes after verbosity' projection ordering and token-frugal framing have some value.

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?

Opens with a precise verb+resource ('Read-only facts about a PDF') and enumerates exactly which facts are returned, then explicitly separates what it does NOT judge ('the claim, not its validity — use veraPDF for that'). This lets an agent distinguish it from validate_pdf 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?

Clear about context: it routes validity questions to veraPDF/verify_pdf and frames the `check` option as a CI assertion workflow. It does not, however, give an explicit when-to-use-this-instead-of-verify_pdf/Sibling routing sentence for the common 'is this signed and valid?' question, which the schema partially covers.

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