pdfnative-mcp

Extract embedded files from PDF

extract_attachments

Read-onlyIdempotent

Pull embedded files from PDFs (PDF/A-3, Factur-X, ZUGFeRD) and get their metadata and base64 payloads. Supports selecting specific attachments, metadata-only probing, and password-protected PDFs.

Instructions

Read-only extraction of embedded files (PDF/A-3, Factur-X, ZUGFeRD): name, mimeType, AFRelationship, description, sizeBytes and (by default) the payload as dataBase64. filename selects one file; includeData:false probes metadata only. Encrypted sources: pass password. Token-frugal: verbosity:'summary'.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`fields`	No	Optional dot-path projection applied to the structured result (e.g. ['attachments.name']). Composes after verbosity. Unknown paths are omitted.
`filename`	No	Optional exact attachment name to extract. When omitted, every embedded file is returned.
`password`	No	Password (user or owner) of an encrypted source. Never logged or echoed.
`pdfBase64`	Yes	Base64-encoded PDF bytes to read embedded files from.
`verbosity`	No	Response verbosity. 'full' (default) returns the attachments[] array; 'summary' returns a token-frugal { attachmentCount } and drops the array.	full
`includeData`	No	When true (default) each attachment carries its decoded payload as dataBase64. Set false for a metadata-only probe (names, sizes, relationships) with no payload bytes.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`attachments`	No
`attachmentCount`	No

Schema Changelog

Changes observed during successful MCP inspections.

AddedAug 24, 2026
Removedv1.6.0Jul 22, 2026
Addedv1.2.0Jun 24, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and idempotentHint, and the description reinforces this with 'Read-only extraction'. It adds valuable behavioral details beyond annotations: default payload inclusion, metadata-only probing, password handling, and token-frugal summary mode. These add meaningful context without contradicting 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three tightly-worded sentences with no fluff. The core action is front-loaded (read-only extraction), key formats are named in the first sentence, and the remaining sentences efficiently cover optional behaviors and parameter interactions.

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 tool has a high-quality output schema, rich parameter descriptions, and complete annotations, the description covers the necessary behavioral context: file selection, payload vs metadata probing, encrypted sources, and response verbosity. Nothing appears missing for an agent to correctly invoke this tool.

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?

The schema already provides 100% parameter coverage with detailed descriptions, so the baseline is 3. The description adds concise semantic layer by explaining the practical intent of includeData:false as metadata-only probing and verbosity:'summary' as token-frugal. It also hints at the relationship between filename and single-file selection, complementing the schema.

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 clearly identifies a specific verb-object pair ('Read-only extraction') targeting embedded files in PDFs, including recognizable formats like PDF/A-3 and ZUGFeRD. This distinguishes it from sibling tools such as add_attachment and extract_text without ambiguity.

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: extracting embedded files from a PDF, including how to select a single file, probe metadata only, handle encrypted sources, and save tokens. It stops short of explicitly naming alternative tools or stating when not to use this tool, but the context is strong enough for an agent to route correctly.

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