pdfnative-mcp

Inspect PDF metadata

inspect_pdf

Read-onlyIdempotent

Retrieve a PDF's structural metadata (version, page count, encryption, signature count, attachments) and run pass/fail checks for PDF/A, signing, encryption, placeholders, and more.

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.
`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 / 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.
`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.

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

Behavior5/5

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

Annotations already declare readOnlyHint and idempotentHint, and the description builds on this by adding richer behavioral detail: presence-gated fields, password handling for encrypted sources, check/checksPassed semantics, per-page output, and token-frugal verbosity. No contradiction with 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, front-loaded, and every sentence carries actionable information. It earns high marks for efficiency, though it reads as one long paragraph with many semicolon-separated ideas; a slightly clearer structure could make it a 5.

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?

Given the 8 parameters, output schema, and complexity of the flags, description fully covers the important operational semantics: what is returned, how flags change shape, how checks behave, how passwords are used, and how token output can be reduced. The description does not need to restate the full schema because the schema describes the structured requests.

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

Parameters5/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine even lowering value beyond the schema: signatures:true means every field; pages:true means per-page sizes and boxes; check:list is a CI assertion returning checks + checksPassed; password is called out for encrypted sources; verbosity and fields are tied to token-frugality.

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 "Read-only facts about a PDF" and enumerates concrete properties (version, pageCount, encryption, signatureCount, etc.), so the tool's purpose is immediately obvious. It also clearly distinguishes itself from validation by calling the pdfA result a claim, not its validity.

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 clearly frames the tool as metadata inspection and even redirects pdfA validity checking to veraPDF, giving an explicit alternative. It does not exhaustively map all sibling alternatives—for instance, it does not explicitly say 'signature validity is verify_pdf's job' in the description—but the read-only framing makes the intended use clear.

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