John's Essentials

convert_file

Universal File Converter — Convert a file between formats: image↔image (jpg/png/webp/bmp/tiff/gif/avif/ico, plus heic/svg/psd as inputs), audio↔audio (mp3/wav/ogg/opus/flac/aac/m4a/wma/aiff, plus alac=Apple Lossless delivered as .m4a), video↔video/GIF (Business gate on some edges) plus legacy flv/wmv/3gp/mpg/vob/ts/m2ts → mp4, extract audio from video (mp4/mov/mkv/webm/avi → mp3/wav/aac/m4a/ogg/flac/opus/aiff/alac), subtitles (srt↔vtt, and srt/vtt→txt), DOC/DOCX/TXT→PDF, image→PDF, comic archive CBZ→PDF. Office/document conversions (xlsx, pptx, csv→xlsx, epub, html) live in convert_document; archives in convert_archive; data formats in convert_data. [category: convert]

Input Schema

TableJSON Schema

Name	Required	Description
`to`	Yes	The format you want back. Apple Lossless (alac) is delivered as a .m4a file.
`file`	Yes	The file to convert. We read its current format from the file itself, so you only need to say what you want back.
`from`	No	Leave blank and we read the format from the file itself. Only set it if the file has no name or an odd one.
`gif_fps`	No	Frames per second. Higher is smoother and bigger. If the width and frame rate together are too heavy we keep the width and ease this down.
`gif_width`	No	How wide the GIF should be, in pixels. Height follows automatically. Very wide plus very smooth is capped - we keep the width you asked for and ease the frame rate down.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 24, 2026
- addedInput schema / properties / from / x-ui
```
Added value: +{
+  "unset_label": "Read from file"
+}
```
Changed2 schema fields changedSep 23, 2026
- addedInput schema / properties / gif_fps / x-ui
```
Added value: +{
+  "unit": "fps"
+}
```
- addedInput schema / properties / gif_width / x-ui
```
Added value: +{
+  "unit": "px"
+}
```

Changed4 schema fields changedSep 11, 2026

changedInput schema / properties / file / description

Previous value: -"Bytes are taken at face value as 'from' — no content sniffing; a wrong 'from' fails inside the engine, not with a clean 400."New value: +"The file to convert. We read its current format from the file itself, so you only need to say what you want back."

addedInput schema / properties / gif_fps

Added value: +{
+  "default": 10,
+  "description": "Frames per second. Higher is smoother and bigger. If the width and frame rate together are too heavy we keep the width and ease this down.",
+  "maximum": 30,
+  "minimum": 1,
+  "type": "integer",
+  "x-show-when": {
+    "to": [
+      "gif"
+    ]
+  }
+}

addedInput schema / properties / gif_width

Added value: +{
+  "default": 320,
+  "description": "How wide the GIF should be, in pixels. Height follows automatically. Very wide plus very smooth is capped - we keep the width you asked for and ease the frame rate down.",
+  "maximum": 1280,
+  "minimum": 64,
+  "type": "integer",
+  "x-show-when": {
+    "to": [
+      "gif"
+    ]
+  }
+}

changedInput schema / properties / to / enum

Previous value: -[
-  "pdf",
-  "jpg",
-  "png",
-  "webp",
-  "bmp",
-  "tiff",
-  "gif",
-  "avif",
-  "ico",
-  "mp3",
-  "wav",
-  "ogg",
-  "opus",
-  "flac",
-  "m4a",
-  "aac",
-  "wma",
-  "aiff",
-  "alac",
-  "mp4",
-  "mov",
-  "webm",
-  "mkv",
-  "avi",
-  "srt",
-  "vtt",
-  "txt",
-  "3gp",
-  "flv",
-  "m2ts",
-  "mpg",
-  "ts",
-  "vob",
-  "wmv"
-]New value: +[
+  "pdf",
+  "jpg",
+  "png",
+  "webp",
+  "bmp",
+  "tiff",
+  "gif",
+  "avif",
+  "ico",
+  "mp3",
+  "wav",
+  "ogg",
+  "opus",
+  "flac",
+  "m4a",
+  "aac",
+  "wma",
+  "aiff",
+  "alac",
+  "mp4",
+  "mov",
+  "webm",
+  "mkv",
+  "avi",
+  "3gp",
+  "flv",
+  "m2ts",
+  "mpg",
+  "ts",
+  "vob",
+  "wmv",
+  "srt",
+  "vtt",
+  "txt"
+]

Changed4 schema fields changedSep 11, 2026

changedInput schema / properties / from / description

Previous value: -"Source format, e.g. 'jpg', 'mp3', 'docx'. OPTIONAL — leave it out and we read the format from the file's own bytes. Only worth setting when the bytes are ambiguous or the file has a synthetic name."New value: +"Leave blank and we read the format from the file itself. Only set it if the file has no name or an odd one."

addedInput schema / properties / from / enum

Added value: +[
+  "jpg",
+  "png",
+  "webp",
+  "bmp",
+  "tiff",
+  "gif",
+  "avif",
+  "ico",
+  "heic",
+  "svg",
+  "psd",
+  "mp3",
+  "wav",
+  "ogg",
+  "opus",
+  "flac",
+  "m4a",
+  "aac",
+  "wma",
+  "aiff",
+  "alac",
+  "mp4",
+  "mov",
+  "webm",
+  "mkv",
+  "avi",
+  "flv",
+  "wmv",
+  "3gp",
+  "mpg",
+  "vob",
+  "ts",
+  "m2ts",
+  "srt",
+  "vtt",
+  "docx",
+  "doc",
+  "txt",
+  "cbz"
+]

changedInput schema / properties / to / description

Previous value: -"Target format, e.g. 'png', 'pdf', 'mp3'."New value: +"The format you want back. Apple Lossless (alac) is delivered as a .m4a file."

addedInput schema / properties / to / enum

Added value: +[
+  "pdf",
+  "jpg",
+  "png",
+  "webp",
+  "bmp",
+  "tiff",
+  "gif",
+  "avif",
+  "ico",
+  "mp3",
+  "wav",
+  "ogg",
+  "opus",
+  "flac",
+  "m4a",
+  "aac",
+  "wma",
+  "aiff",
+  "alac",
+  "mp4",
+  "mov",
+  "webm",
+  "mkv",
+  "avi",
+  "srt",
+  "vtt",
+  "txt",
+  "3gp",
+  "flv",
+  "m2ts",
+  "mpg",
+  "ts",
+  "vob",
+  "wmv"
+]

Changed1 schema field changedSep 11, 2026

changedInput schema / properties / from / description

Previous value: -"Source format, e.g. 'jpg', 'mp3', 'docx' — REQUIRED and must match the uploaded file."New value: +"Source format, e.g. 'jpg', 'mp3', 'docx'. OPTIONAL — leave it out and we read the format from the file's own bytes. Only worth setting when the bytes are ambiguous or the file has a synthetic name."

Changed1 schema field changedSep 10, 2026

changedInput schema / required

Previous value: -[
-  "file",
-  "from",
-  "to"
-]New value: +[
+  "file",
+  "to"
+]

First observedSep 5, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations are default false hints (readOnlyHint=false, destructiveHint=false), so the description carries the disclosure burden and adds real behavioral context: source-format auto-detection, alac delivered as .m4a, GIF frame-rate gracefully easing down when width+fps is too heavy, and a 'Business gate' caveat on some video edges. What is missing is the output/return contract (no output schema) and which edges are exactly gated, but the disclosures present are genuine and non-tautological.

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?

Long, but every clause contributes a distinct capability list, a routing rule, or a behavioral caveat — there is no filler. The purpose statement is front-loaded in the first sentence, media-type sections are cleanly grouped, and the trailing [category: convert] tag is lightweight metadata.

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?

High-complexity tool with 5 parameters, two large enums, and no output schema; the description covers the main decision surface exhaustively — what source formats are readable, what targets exist, and which conversions belong to other tools. Remaining gaps are the unspecified shape of a successful conversion result and the vague 'Business gate on some edges' — the exact gated edges are never listed.

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?

Schema coverage is 100%, so the baseline is 3; the description earns the 4 by adding directional semantics the bare enums cannot express: heic/svg/psd are input-only, alac is delivered wrapped in .m4a, legacy flv/wmv/3gp/mpg/vob/ts/m2ts convert only to mp4, and audio extraction pairs mp4/mov/mkv/webm/avi sources to mp3/wav/aac/m4a/ogg/flac/opus/aiff/alac targets. The gif_fps/gif_width degradation behavior in the description reinforces the schema's own limits note, adding a small incremental layer.

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?

Leads with a specific verb+resource ('Convert a file between formats') and then pins down scope with an exhaustive matrix: image↔image, audio↔audio, video↔video/GIF, audio extraction, subtitles, DOC/DOCX/TXT→PDF, image→PDF, and CBZ→PDF. It explicitly differentiates from siblings by stating that office/document, archive, and data conversions 'live in convert_document / convert_archive / convert_data.' The only weakness is unaddressed overlap with convert_video or photo_format_converter, but the matrix already answers those cases.

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?

Provides explicit when-not guidance and named alternatives for the most ambiguous categories: document/office conversions route to convert_document, archives to convert_archive, and data formats to convert_data, plus a 'Business gate on some edges' warning that signals limited availability on some video paths. However, it gives no when-to-use guidance for overlapping siblings like convert_video, media_extract_audio, or photo_format_converter, and the gated edges are never enumerated.

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?