pdfnative-mcp

Split PDF into ranges

split_pdf

Idempotent

Split one PDF into multiple documents by specifying page ranges; each range produces a separate PDF file or embedded resource.

Instructions

Split one PDF into several documents, one per ranges[] entry ({ start, end? }, 0-based inclusive; end defaults to start). Multi-output result: base64 mode returns one embedded resource per part; file mode writes indexed siblings ('out.pdf' → 'out-1.pdf', 'out-2.pdf', …). Same page-tree caveats as merge_pdfs (signatures/AcroForm/XMP dropped; boxes kept). Encrypted sources: password. Need ONE document from a page subset? Use extract_pages.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`ranges`	Yes	Page ranges to extract, one output PDF per range. 0-based, inclusive; `end` defaults to `start` (a single page).
`encrypt`	No	Re-encrypt the output (Standard Security Handler; AES-128 default or AES-256; RC4 never emitted). Applied to every produced range.
`password`	No	Password (user or owner) of an encrypted source. Never logged or echoed.
`pdfBase64`	Yes	Base64-encoded source PDF. Pass `password` for an encrypted source.
`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	Base output path (file mode). Each PDF is written to an indexed sibling: 'out.pdf' → 'out-1.pdf', 'out-2.pdf', …
`dropAnnotations`	No	When true, drop ALL annotations. Default keeps self-contained URI link annotations.
`maxOutputSizeBytes`	No	Maximum size, in bytes, of each produced PDF. Defaults to 268435456 (256 MiB).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`mode`	Yes
`count`	Yes
`parts`	Yes
`totalBytes`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedAug 24, 2026

changedInput schema / properties / encrypt / description

Previous value: -"Re-encrypt the produced PDF with the PDF Standard Security Handler (AES-128 V4/R4 default, or AES-256 V5/R6). RC4 is never emitted. Requires a Web Crypto CSPRNG. Applied to every produced range."New value: +"Re-encrypt the output (Standard Security Handler; AES-128 default or AES-256; RC4 never emitted). Applied to every produced range."

changedInput schema / properties / encrypt / properties / algorithm / description

Previous value: -"Content cipher: aes128 (V4/R4, widest compatibility) or aes256 (V5/R6, strongest)."New value: +"aes128 (V4/R4, widest compatibility) or aes256 (V5/R6)."

changedInput schema / properties / encrypt / properties / ownerPassword / description

Previous value: -"Owner password (required, non-empty). Controls permissions and full access."New value: +"Owner password (full access)."

changedInput schema / properties / encrypt / properties / permissions / description

Previous value: -"Access permission flags (enforced by conforming readers). Each defaults to allowed when omitted."New value: +"Permission flags; each defaults to allowed."

changedInput schema / properties / encrypt / properties / userPassword / description

Previous value: -"User (open) password. Omitted or empty string means the document opens without a password prompt."New value: +"Open password; omitted/empty = opens without a prompt."

addedInput schema / properties / outputMode / description

Added value: +"'base64' (default) returns the PDF inline; 'file' writes it inside the PDFNATIVE_MCP_OUTPUT_DIR sandbox (SECURITY_VIOLATION when the sandbox is not configured)."

changedInput schema / properties / password / description

Previous value: -"Password to open an encrypted source PDF (user or owner — both are tried). Omit for unencrypted documents. Never logged or echoed back."New value: +"Password (user or owner) of an encrypted source. Never logged or echoed."

changedOutput schema / properties / parts / items / properties / filePath / description

Previous value: -"Absolute sandboxed file path (when mode='file')."New value: +"Sandboxed absolute path (file mode)."

Changed3 schema fields changedv1.6.0Jul 22, 2026

addedInput schema / properties / encrypt

Added value: +{
+  "additionalProperties": false,
+  "description": "Re-encrypt the produced PDF with the PDF Standard Security Handler (AES-128 V4/R4 default, or AES-256 V5/R6). RC4 is never emitted. Requires a Web Crypto CSPRNG. Applied to every produced range.",
+  "properties": {
+    "algorithm": {
+      "default": "aes128",
+      "description": "Content cipher: aes128 (V4/R4, widest compatibility) or aes256 (V5/R6, strongest).",
+      "enum": [
+        "aes128",
+        "aes256"
+      ],
+      "type": "string"
+    },
+    "ownerPassword": {
+      "description": "Owner password (required, non-empty). Controls permissions and full access.",
+      "maxLength": 4096,
+      "minLength": 1,
+      "type": "string"
+    },
+    "permissions": {
+      "additionalProperties": false,
+      "description": "Access permission flags (enforced by conforming readers). Each defaults to allowed when omitted.",
+      "properties": {
+        "copy": {
+          "type": "boolean"
+        },
+        "extractText": {
+          "type": "boolean"
+        },
+        "modify": {
+          "type": "boolean"
+        },
+        "print": {
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "userPassword": {
+      "description": "User (open) password. Omitted or empty string means the document opens without a password prompt.",
+      "maxLength": 4096,
+      "type": "string"
+    }
+  },
+  "required": [
+    "ownerPassword"
+  ],
+  "type": "object"
+}

addedInput schema / properties / password

Added value: +{
+  "description": "Password to open an encrypted source PDF (user or owner — both are tried). Omit for unencrypted documents. Never logged or echoed back.",
+  "maxLength": 4096,
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / properties / pdfBase64 / description

Previous value: -"Base64-encoded source PDF. Must not be encrypted."New value: +"Base64-encoded source PDF. Pass `password` for an encrypted source."

Addedv1.2.2Jul 4, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The description discloses multi-output behavior, output naming conventions in file mode, what happens in base64 mode, and important PDF caveats (signatures/AcroForm/XMP dropped; boxes kept). It also notes encrypted sources using password. These go beyond the annotations, which only describe readOnly/idemptency/destructive hints, and would meaningfully affect ai-agent expectations for the result.

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 compact and information-dense: four sentences that front-load the core operation, then deliver range semantics, output behavior, page-tree caveats, encrypted-source handling, and the sibling alternative. Every sentence earns its place and no extraneous content is present.

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 a tool with 8 parameters, nested objects, and an output schema, the description covers the defining split behavior, the two output modes with concrete file naming, the main transformation caveats, and the canonical alternative. Given the rich schema and output schema, nothing essential is missing for selecting or invoking 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 input schema already documents every parameter including the zero-based inclusive nature of ranges, outputPath semantics, password behavior, and outputMode defaults. The description reinforces the central `ranges[]` semantics and output naming but does not add meaningful meaning beyond what the schema already provides.

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 states a specific verb and resource: 'Split one PDF into several documents, one per ranges[] entry'. It also distinguishes itself from extract_pages by explicitly naming the alternative for extracting a single document, so an agent can tell the tools apart at the description level.

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?

Includes explicit routing guidance: 'Need ONE document from a page subset? Use extract_pages.' It also references merge_pdfs for shared page-tree caveats, helping the agent understand this tool is best when multiple ranges are wanted, and points to password handling for encrypted sources. Clear enough to select this tool over the alternatives.

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