John's Essentials

pdf_merge

Merge PDFs — Combine multiple PDF files (at least 2) into a single document in the order provided. Supports per-file page selection, blank separator pages, bookmarks, and output metadata. [category: pdf]

Input Schema

TableJSON Schema

Name	Required	Description
`files`	Yes	Input PDFs — at least 2 required.
`title`	No	Optional output metadata Title.
`author`	No	Optional output metadata Author.
`subject`	No	Optional output metadata Subject.
`pageRanges`	No	Leave blank to use every page. To take only part of a file, give its pages in the same order as the files themselves — 1-3 for the first, 2,5 for the second.
`addBookmarks`	No	Add a bookmark at each document boundary.
`insertBlanks`	No	Insert a blank page between documents.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 26, 2026

addedInput schema / properties / pageRanges / x-ui

Added value: +{
+  "no_recall": true,
+  "page_select": {
+    "per_file": true
+  }
+}

Changed3 schema fields changedSep 26, 2026
- changedInput schema / properties / author / x-ui / unset_label
```
Previous value: -"Left out"New value: +"Kept from the first file"
```
- changedInput schema / properties / subject / x-ui / unset_label
```
Previous value: -"Left out"New value: +"Kept from the first file"
```
- changedInput schema / properties / title / x-ui / unset_label
```
Previous value: -"Left out"New value: +"Kept from the first file"
```
Changed3 schema fields changedSep 26, 2026
- addedInput schema / properties / author / x-ui
```
Added value: +{
+  "unset_label": "Left out"
+}
```
- addedInput schema / properties / subject / x-ui
```
Added value: +{
+  "unset_label": "Left out"
+}
```
- addedInput schema / properties / title / x-ui
```
Added value: +{
+  "unset_label": "Left out"
+}
```

Changed2 schema fields changedSep 11, 2026

changedInput schema / properties / pageRanges / description

Previous value: -"Optional per-file page selection aligned with the files order, e.g. '1-3,5'. The multipart field name is 'pageRanges[]' (with brackets)."New value: +"Leave blank to use every page. To take only part of a file, give its pages in the same order as the files themselves — 1-3 for the first, 2,5 for the second."

addedInput schema / properties / pageRanges / title
```
Added value: +"Pages to take from each file"
```

First observedSep 5, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations include readOnlyHint=false and destructiveHint=false, indicating a non-destructive write operation. The description adds context by listing supported features (page selection, blanks, bookmarks, metadata), which implies it creates a new output file without altering inputs. It does not contradict annotations and provides useful behavioral details.

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 two sentences with the core purpose front-loaded ('Merge PDFs') and a concise list of supported features. Every word earns its place, and it is easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (7 parameters, 1 required) and the absence of an output schema, the description covers the main capabilities and constraints (at least 2 files, ordering). It does not mention return format or file handling, but for a PDF merge operation this is minor and likely implied by the category. Overall, it is sufficient for an agent to call 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 all parameters already have detailed descriptions. The tool description summarizes the feature set (page selection, blanks, bookmarks, metadata) which aligns with the parameters, but it does not add meaning beyond what the schema provides. Baseline 3 is 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?

The description explicitly states 'Merge PDFs' and explains it combines multiple PDF files into a single document in the order provided. It clearly distinguishes from sibling tools like pdf_split and pdf_reorder by focusing on concatenation, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states the core action but does not explicitly mention when to prefer this tool over alternatives like pdf_interleave or pdf_reorder. The purpose is clear enough to infer usage, but no exclusions or alternative references are given.

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

All John's Essentials tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?