John's Essentials

media_add_watermark

Video Watermark — Overlay a text watermark onto a video using FFmpeg, with position and opacity control. [category: media]

Input Schema

TableJSON Schema

Name	Required	Description	Default
`file`	Yes	Video to watermark. Forces a full H.264 re-encode into MP4 (audio copied) — among the platform's slowest ops on long videos.
`text`	Yes	The words burned into every frame, drawn exactly as typed (% signs and backslashes included) on one line of up to 200 characters. Required; there is no default.
`opacity`	No	How solid the watermark looks: 1 is fully solid, 0.3 is a faint ghost.
`fontsize`	No	Text size in pixels. Leave it at 0 and the size is worked out from the video's own height - about 36 on a 1080p video. Sizes below 6 are treated the same as 0.
`position`	No	Which corner of the frame the watermark sits in.	bottomright

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 24, 2026

changedInput schema / properties / text / description

Previous value: -"The words burned into every frame. Required, and there is no default: a step nobody opened used to burn our own company name into the customer's video."New value: +"The words burned into every frame, drawn exactly as typed (% signs and backslashes included) on one line of up to 200 characters. Required; there is no default."

Changed4 schema fields changedSep 23, 2026

addedInput schema / properties / fontsize / x-ui
```
Added value: +{
+  "unit": "px"
+}
```
removedInput schema / properties / text / default
```
Removed value: -"John's Essentials"
```

changedInput schema / properties / text / description

Previous value: -"Watermark text."New value: +"The words burned into every frame. Required, and there is no default: a step nobody opened used to burn our own company name into the customer's video."

changedInput schema / required

Previous value: -[
-  "file"
-]New value: +[
+  "file",
+  "text"
+]

Changed4 schema fields changedSep 11, 2026

addedInput schema / properties / fontsize

Added value: +{
+  "default": 0,
+  "description": "Text size in pixels. Leave it at 0 and the size is worked out from the video's own height - about 36 on a 1080p video. Sizes below 6 are treated the same as 0.",
+  "maximum": 400,
+  "minimum": 0,
+  "type": "integer"
+}

changedInput schema / properties / opacity / description

Previous value: -"Fraction 0.0-1.0; invalid values fall back to 0.7."New value: +"How solid the watermark looks: 1 is fully solid, 0.3 is a faint ghost."

changedInput schema / properties / position / description

Previous value: -"No hyphens — 'bottomright', not 'bottom-right'. Unknown values fall back to bottomright."New value: +"Which corner of the frame the watermark sits in."

addedInput schema / properties / position / x-ui

Added value: +{
+  "labels": {
+    "bottomleft": "Bottom left",
+    "bottomright": "Bottom right",
+    "center": "Centre",
+    "topleft": "Top left",
+    "topright": "Top right"
+  }
+}

First observedSep 5, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations only declare non-read-only and non-destructive. The file parameter description adds key behavioral context: forces full H.264 re-encode into MP4, audio copied, and is among the platform's slowest ops on long videos. This goes beyond annotations, although the main description does not mention it.

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 main description is a single efficient sentence front-loaded with the action and key controls. The [category: media] tag is minor metadata but not verbose. No wasted words.

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?

All 5 parameters are well-explained, including defaults and range constraints. With no output schema, return-value documentation isn't required. However, the description doesn't state whether the input is overwritten or a new file is returned, a moderate gap for a transform tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

100% schema description coverage, and each property has explanatory content beyond the schema type: text escaping and 200-char limit, opacity visual meaning, font size fallback when set to 0, and position enum labels. Substantially helps an agent choose correct values.

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?

States a specific verb ('Overlay'), resource ('video'), and method ('text watermark using FFmpeg') plus controls ('position and opacity'). The title 'Video Watermark' and [category: media] tag make it distinct from photo/pdf watermark siblings.

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?

No guidance on when to use this tool versus alternatives such as photo_watermark or pdf_watermark. The sibling list and title imply video-specific use, but the description itself does not state conditions, exclusions, or preferred scenarios.

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?