John's Essentials

pdf_excel_to_pdf

Excel to PDF — Convert Excel spreadsheets (.xlsx / .xls / .csv / .ods) to PDF with fit-to-page, orientation control, paper size, sheet selection, repeat header rows, custom header/footer, PDF/A output, password protection, watermark, and per-sheet split mode. Hybrid pipeline: excelize preprocesses the xlsx (page layout, sheet visibility) then LibreOffice converts. [category: pdf]

Input Schema

TableJSON Schema

Name	Required	Description	Default
`file`	Yes	Input spreadsheet (.xlsx, .xls, .csv, .ods)
`pdfa`	No	Save in the PDF/A archive format, which embeds everything the file needs to open correctly in decades' time. Off unless you need it; 2b is the version most archives ask for.	none
`scale`	No	Print size as a percentage, where 100 is life size and less shrinks the sheet to fit more on a page. Leave it blank unless you want a specific percentage - setting any value here turns Fit to page off.
`footer`	No	Per-page footer template. Same tokens as header.
`header`	No	Per-page header template. Tokens: {page}, {pages}, {sheet}, {date}, {filename}.
`sheets`	No	Which sheets to convert: all, or the names or positions you want — Sales,Ledger or 0,2.	all
`margins`	No	default\|narrow\|normal\|wide (Excel's inch presets); default keeps the sheet's own margins. Only applies to .xlsx input; unknown → default.	default
`quality`	No	How sharp the pictures and charts stay in the PDF. Leave blank for the converter's own setting.
`password`	No	Open password for the output PDF (user password).
`bookmarks`	No	Add PDF bookmarks, one per sheet.
`fitToPage`	No	Fit each sheet to a page. 'width' prevents column cutoff; 'one-page' squeezes each sheet onto a single page.	none
`gridlines`	No	Print the faint grid between cells. Leave blank to keep whatever the sheet already does.
`paperSize`	No	a4 (default) \| letter \| legal \| tabloid \| a3. Only applies to .xlsx input (excelize preprocess); unknown values silently become a4.	a4
`splitMode`	No	One PDF containing every sheet, or a ZIP holding one PDF per sheet.	combined
`repeatRows`	No	Print titles — rows that repeat on every page. e.g. '1' or '1-3'.
`orientation`	No	Page orientation. 'auto' picks landscape for sheets with ≥8 data columns.	auto
`showHeaders`	No	Print the A B C column letters and 1 2 3 row numbers down the edges. Leave blank to keep the sheet's own setting.
`permPassword`	No	A second, different password that locks printing, copying and editing. Only takes effect if you also set an open password above.
`watermarkFont`	No	Lettering style for the watermark. Latin alphabet only. Only used when there is watermark text.	Helvetica
`watermarkText`	No	Optional text watermark stamped on every page of the output.
`watermarkColor`	No	Colour of the watermark lettering, as #rgb or #rrggbb. Anything else becomes mid-grey. Only used when there is watermark text.	#808080
`watermarkScale`	No	Size multiplier applied on top of the lettering size. Only used when there is watermark text.
`watermarkOpacity`	No	How solid the watermark looks: 1 is fully solid, 0.3 is a faint ghost. This is a fraction, not a percent. Only used when there is watermark text.
`watermarkFontSize`	No	Height of the watermark lettering in points. Only used when there is watermark text.
`watermarkPosition`	No	Where the watermark sits on the page. Only used when there is watermark text.	c
`watermarkRotation`	No	Angle of the watermark in whole degrees; 45 is the classic diagonal. Only used when there is watermark text.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 26, 2026
- changedInput schema / properties / footer / x-ui / unset_label
```
Previous value: -"No footer"New value: +"Sheet's own footer"
```
- changedInput schema / properties / header / x-ui / unset_label
```
Previous value: -"No header"New value: +"Sheet's own header"
```
- changedInput schema / properties / repeatRows / x-ui / unset_label
```
Previous value: -"No rows repeated"New value: +"Sheet's own print titles"
```

Changed6 schema fields changedSep 26, 2026

addedInput schema / properties / footer / x-ui

Added value: +{
+  "unset_label": "No footer"
+}

addedInput schema / properties / header / x-ui

Added value: +{
+  "unset_label": "No header"
+}

addedInput schema / properties / password / x-ui

Added value: +{
+  "unset_label": "No password"
+}

addedInput schema / properties / permPassword / x-ui

Added value: +{
+  "unset_label": "Same as the open password"
+}

addedInput schema / properties / repeatRows / x-ui

Added value: +{
+  "unset_label": "No rows repeated"
+}

addedInput schema / properties / watermarkText / x-ui

Added value: +{
+  "unset_label": "No watermark"
+}

Changed3 schema fields changedSep 24, 2026
- addedInput schema / properties / gridlines / x-ui / unset_label
```
Added value: +"Sheet's own setting"
```
- addedInput schema / properties / quality / x-ui / unset_label
```
Added value: +"Converter's setting"
```
- addedInput schema / properties / showHeaders / x-ui / unset_label
```
Added value: +"Sheet's own setting"
```
Changed4 schema fields changedSep 23, 2026
- addedInput schema / properties / scale / x-ui
```
Added value: +{
+  "unit": "%"
+}
```
- addedInput schema / properties / watermarkFontSize / x-ui
```
Added value: +{
+  "unit": "pt"
+}
```
- addedInput schema / properties / watermarkRotation / x-ui
```
Added value: +{
+  "unit": "deg"
+}
```
- addedInput schema / properties / watermarkScale / x-ui
```
Added value: +{
+  "unit": "x"
+}
```

Changed26 schema fields changedSep 11, 2026

changedInput schema / properties / gridlines / description

Previous value: -"Show gridlines. Empty leaves the sheet's own setting."New value: +"Print the faint grid between cells. Leave blank to keep whatever the sheet already does."

changedInput schema / properties / gridlines / enum

Previous value: -[
-  "",
-  "true",
-  "false"
-]New value: +[
+  "true",
+  "false"
+]

addedInput schema / properties / gridlines / x-ui

Added value: +{
+  "labels": {
+    "false": "Hide gridlines",
+    "true": "Show gridlines"
+  }
+}

addedInput schema / properties / margins / x-ui

Added value: +{
+  "labels": {
+    "default": "Keep the sheet's own margins",
+    "narrow": "Narrow",
+    "normal": "Normal",
+    "wide": "Wide"
+  }
+}

changedInput schema / properties / pdfa / description

Previous value: -"Archival PDF/A output. 2b is the safe default."New value: +"Save in the PDF/A archive format, which embeds everything the file needs to open correctly in decades' time. Off unless you need it; 2b is the version most archives ask for."

addedInput schema / properties / pdfa / x-ui

Added value: +{
+  "labels": {
+    "1b": "PDF/A-1b",
+    "2b": "PDF/A-2b (most asked for)",
+    "3b": "PDF/A-3b",
+    "none": "Ordinary PDF"
+  }
+}

changedInput schema / properties / permPassword / description

Previous value: -"Owner password for permission restrictions. Optional."New value: +"A second, different password that locks printing, copying and editing. Only takes effect if you also set an open password above."

addedInput schema / properties / permPassword / title
```
Added value: +"Owner password"
```

changedInput schema / properties / quality / description

Previous value: -"Output compression quality preset."New value: +"How sharp the pictures and charts stay in the PDF. Leave blank for the converter's own setting."

changedInput schema / properties / quality / enum

Previous value: -[
-  "",
-  "low",
-  "medium",
-  "high"
-]New value: +[
+  "low",
+  "medium",
+  "high"
+]

addedInput schema / properties / quality / x-ui

Added value: +{
+  "labels": {
+    "high": "Best quality (no downsizing)",
+    "low": "Smallest file (96 DPI pictures)",
+    "medium": "Balanced (150 DPI pictures)"
+  }
+}

changedInput schema / properties / scale / description

Previous value: -"Print scaling percent. Overrides fitToPage when set."New value: +"Print size as a percentage, where 100 is life size and less shrinks the sheet to fit more on a page. Leave it blank unless you want a specific percentage - setting any value here turns Fit to page off."

addedInput schema / properties / scale / x-show-when

Added value: +{
+  "fitToPage": [
+    "none"
+  ]
+}

addedInput schema / properties / sheets / default
```
Added value: +"all"
```

changedInput schema / properties / sheets / description

Previous value: -"Sheet selection: 'all', comma-separated names (e.g. 'Sales,Ledger'), or comma-separated 0-based indexes (e.g. '0,2'). Non-selected sheets are hidden before conversion."New value: +"Which sheets to convert: all, or the names or positions you want — Sales,Ledger or 0,2."

changedInput schema / properties / showHeaders / description

Previous value: -"Show row/column headers (A/B/C + 1/2/3). Empty leaves the sheet's own setting."New value: +"Print the A B C column letters and 1 2 3 row numbers down the edges. Leave blank to keep the sheet's own setting."

changedInput schema / properties / showHeaders / enum

Previous value: -[
-  "",
-  "true",
-  "false"
-]New value: +[
+  "true",
+  "false"
+]

addedInput schema / properties / showHeaders / x-ui

Added value: +{
+  "labels": {
+    "false": "Hide row & column headings",
+    "true": "Show row & column headings"
+  }
+}

changedInput schema / properties / splitMode / description

Previous value: -"combined = one multi-page PDF; per-sheet = ZIP with one PDF per sheet."New value: +"One PDF containing every sheet, or a ZIP holding one PDF per sheet."

addedInput schema / properties / watermarkColor

Added value: +{
+  "default": "#808080",
+  "description": "Colour of the watermark lettering, as #rgb or #rrggbb. Anything else becomes mid-grey. Only used when there is watermark text.",
+  "type": "string"
+}

addedInput schema / properties / watermarkFont

Added value: +{
+  "default": "Helvetica",
+  "description": "Lettering style for the watermark. Latin alphabet only. Only used when there is watermark text.",
+  "enum": [
+    "Helvetica",
+    "Times-Roman",
+    "Courier"
+  ],
+  "type": "string"
+}

addedInput schema / properties / watermarkFontSize

Added value: +{
+  "default": 48,
+  "description": "Height of the watermark lettering in points. Only used when there is watermark text.",
+  "maximum": 1000,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / watermarkOpacity

Added value: +{
+  "default": 0.3,
+  "description": "How solid the watermark looks: 1 is fully solid, 0.3 is a faint ghost. This is a fraction, not a percent. Only used when there is watermark text.",
+  "maximum": 1,
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / watermarkPosition

Added value: +{
+  "default": "c",
+  "description": "Where the watermark sits on the page. Only used when there is watermark text.",
+  "enum": [
+    "c",
+    "tl",
+    "tc",
+    "tr",
+    "ml",
+    "mr",
+    "bl",
+    "bc",
+    "br"
+  ],
+  "type": "string",
+  "x-ui": {
+    "labels": {
+      "bc": "Bottom centre",
+      "bl": "Bottom left",
+      "br": "Bottom right",
+      "c": "Centre",
+      "ml": "Middle left",
+      "mr": "Middle right",
+      "tc": "Top centre",
+      "tl": "Top left",
+      "tr": "Top right"
+    }
+  }
+}

addedInput schema / properties / watermarkRotation

Added value: +{
+  "default": 45,
+  "description": "Angle of the watermark in whole degrees; 45 is the classic diagonal. Only used when there is watermark text.",
+  "maximum": 180,
+  "minimum": -180,
+  "type": "integer"
+}

addedInput schema / properties / watermarkScale

Added value: +{
+  "default": 1,
+  "description": "Size multiplier applied on top of the lettering size. Only used when there is watermark text.",
+  "maximum": 20,
+  "minimum": 0.01,
+  "type": "number"
+}

First observedSep 5, 2026

TDQS

B3.4/5.0

Behavior4/5

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

Annotations only provide basic flags (readOnlyHint=false, destructiveHint=false). The description adds meaningful behavioral context by disclosing the hybrid pipeline: excelize preprocesses the xlsx for page layout and sheet visibility, then LibreOffice performs the conversion. This helps explain why some options apply only to .xlsx input and gives the agent insight into internal behavior not available in annotations or schema.

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 compact and front-loads the core purpose before the pipeline detail. The feature enumeration is dense but relevant, and there is no filler. It could be slightly better structured with scannable features, but it earns its place and stays appropriately sized for a 26-parameter tool.

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

Completeness3/5

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

For a high-complexity tool with 26 parameters and no output schema, the description gives a solid overview of capabilities and pipeline behavior. However, it omits practical invocation context: output shape (beyond what splitMode schema implies), behavior for unsupported input edge cases, or explicit routing to sibling batch/inspect tools. The schema compensates heavily, but the description alone is not fully complete.

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 each parameter has a rich description or enum labels, so the schema already carries the semantic burden. The tool description lists feature categories like fit-to-page, orientation, and watermark, but these repeat what the schema documents and do not meaningfully add param-level meaning. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb and resource: 'Convert Excel spreadsheets to PDF,' and lists supported extensions and major features. This is a specific, non-tautological purpose. However, it does not explicitly distinguish itself from close siblings like pdf_excel_to_pdf_batch or pdf_excel_to_pdf_inspect, so the boundary relies on the tool name rather than the description.

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

Usage Guidelines2/5

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

The description says what the tool does but provides no guidance about when to choose it over alternatives, such as the batch variant for multiple files or the inspect variant for examining spreadsheets. There are no stated exclusions, prerequisites, or 'use this instead when...' signals. The only implied usage is the general 'Excel to PDF' conversion context.

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?