proofcut

Overview Schema Source Related Servers Discussions Admin

overlay_add

Idempotent

Add a lower third, scrim, sticker, or animated graphic over a film clip, anchored to specific words or events so edits move it automatically.

Instructions

Draw a transparent card, an animated graphic or a still over the film — a lower third, a graphic, a sticker.

Make the card first with card_new from lowerthird (a headline and an optional footnote, bottom left) or scrim (a dark gradient for type to sit on). The span starts at a word, phrase or event of clip_id and ends at a word, phrase, event or length; it is resolved through the timeline on every build and never stored as seconds, so cuts move it, and a cut through its start word makes export refuse until it is moved.

The stack is list order: a later overlay draws over an earlier one it overlaps. Put the scrim first (or position=0), then the lowerthird. A staggered footnote is its own lowerthird with an empty headline, starting later. The reply echoes the words or event each end resolved to and where it plays; plan=true writes nothing. Any overlay routes export through the MLT writer, and export's reply lists the overlays it drew.

Input Schema

TableJSON Schema

Name	Required	Description
`x`	No	A sticker's centre across the frame: 0 is the left edge, 1 the right. Default 0.5.
`y`	No	A sticker's centre down the frame: 0 is the top, 1 the bottom. Default 0.5.
`card`	No	The overlay card to place: one made by card_new from an overlay template (`lowerthird`, `scrim`), by name or as `card:NAME`. An ordinary card is opaque and is refused. One of card, graphic or image; each takes its own prefix.
`path`	No	The project directory to act on. Omit it — the usual case — when this server is bound to a project (started as `proofcut -C DIR mcp`, or inside a project; `ping` says which): it then resolves to that one bound project, a relative path resolves against it, and a path outside it is refused by name. Unbound, `path` is the whole address and omitting it refuses rather than guessing.
`plan`	No	Resolve the whole call and report what it would do, writing nothing. Prefer it over doing the thing and undoing it.
`after`	No	A forward cursor over a phrase's matches: any match at or before this word index is skipped. -1, the default, means from the start.
`enter`	No	How it appears: `rise` (moves up while fading in), `fade`, `pop` (scales up past full size and settles), `slide-left`/`slide-right`/`slide-top`/`slide-bottom` (in from that edge), or `none` (a cut). Default rise for a card, pop for an image, none for a graphic.
`event`	No	Start on this event of clip_id: `name`, or `name#k` when the name repeats.
`image`	No	A still (image_add) to place as a sticker, instead of a card or graphic. It pops in and fades out unless enter/leave say otherwise.
`leave`	No	How it goes: `fade`, `rise` (moves down while fading out), `pop`, a `slide-` out to that edge, or `none`. Default fade for a card or image, none for a graphic.
`style`	No	`plain`, or `photo`: a white border and a soft shadow, a photo card.
`width`	No	A sticker's width, as a fraction of the frame's width. Default 0.3.
`phrase`	No	Start on this phrase's FIRST word, resolved against clip_id's transcript.
`rotate`	No	Degrees to turn a sticker, clockwise; negative turns it the other way.
`clip_id`	Yes	The clip whose words or events address the span — the transcript the word indices index, or the recording the events belong to.
`graphic`	No	An animated graphic (graphic_new) to place instead of a card. Its intro plays from the start, its outro ends at the end, and its hold fills the span between; a span shorter than intro plus outro is refused. It enters and leaves with no motion of its own unless enter/leave say so.
`seconds`	No	End this long after the start. A length, so a cut inside the span does not shorten it.
`position`	No	Where in the stack it goes: 0 is the bottom, omitted is the top. A later overlay draws over an earlier one it overlaps, so a scrim goes before its type.
`enter_ease`	No	The entrance's curve: linear, ease, ease-in or ease-out. Default ease-out.
`leave_ease`	No	The exit's curve: linear, ease, ease-in or ease-out. Default ease-in.
`occurrence`	No	Disambiguate a phrase by count when it matches more than once, 1-based in transcript order among the matches after `after`: 1 is the first, 2 the second. Unset, an ambiguous phrase is refused — listing every candidate's range and text — rather than guessed at.
`word_index`	No	The word the overlay starts on. One of word_index, phrase or event.
`until_event`	No	End on this event of clip_id.
`until_phrase`	No	End as this phrase's LAST word ends.
`enter_seconds`	No	How long the entrance takes. Default 0.45.
`leave_seconds`	No	How long the exit takes. Default 0.3.
`until_word_index`	No	End as this word ends. One of until_word_index, until_phrase, until_event or seconds.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed13 schema fields changedv0.43.0Sep 24, 2026

addedInput schema / properties / card / default
```
Added value: +null
```

changedInput schema / properties / card / description

Previous value: -"The overlay card to place: one made by card_new from an overlay template (`lowerthird`, `scrim`). An ordinary card is opaque and is refused."New value: +"The overlay card to place: one made by card_new from an overlay template (`lowerthird`, `scrim`), by name or as `card:NAME`. An ordinary card is opaque and is refused. One of card, graphic or image; each takes its own prefix."

changedInput schema / properties / card / type

Previous value: -"string"New value: +[
+  "string",
+  "null"
+]

changedInput schema / properties / enter / description

Previous value: -"How it appears: `rise` (moves up while fading in), `fade`, or `none` (a cut). Default rise."New value: +"How it appears: `rise` (moves up while fading in), `fade`, `pop` (scales up past full size and settles), `slide-left`/`slide-right`/`slide-top`/`slide-bottom` (in from that edge), or `none` (a cut). Default rise for a card, pop for an image, none for a graphic."

addedInput schema / properties / graphic

Added value: +{
+  "default": null,
+  "description": "An animated graphic (graphic_new) to place instead of a card. Its intro plays from the start, its outro ends at the end, and its hold fills the span between; a span shorter than intro plus outro is refused. It enters and leaves with no motion of its own unless enter/leave say so.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / properties / image

Added value: +{
+  "default": null,
+  "description": "A still (image_add) to place as a sticker, instead of a card or graphic. It pops in and fades out unless enter/leave say otherwise.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedInput schema / properties / leave / description

Previous value: -"How it goes: `fade`, `rise` (moves down while fading out), or `none`. Default fade."New value: +"How it goes: `fade`, `rise` (moves down while fading out), `pop`, a `slide-` out to that edge, or `none`. Default fade for a card or image, none for a graphic."

addedInput schema / properties / rotate

Added value: +{
+  "default": null,
+  "description": "Degrees to turn a sticker, clockwise; negative turns it the other way.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedInput schema / properties / style

Added value: +{
+  "default": null,
+  "description": "`plain`, or `photo`: a white border and a soft shadow, a photo card.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / properties / width

Added value: +{
+  "default": null,
+  "description": "A sticker's width, as a fraction of the frame's width. Default 0.3.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedInput schema / properties / x

Added value: +{
+  "default": null,
+  "description": "A sticker's centre across the frame: 0 is the left edge, 1 the right. Default 0.5.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedInput schema / properties / y

Added value: +{
+  "default": null,
+  "description": "A sticker's centre down the frame: 0 is the top, 1 the bottom. Default 0.5.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

changedInput schema / required

Previous value: -[
-  "card",
-  "clip_id"
-]New value: +[
+  "clip_id"
+]

Addedv0.36.0Sep 17, 2026

TDQS

A5/5.0

Behavior5/5

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

Beyond the annotations, the description reveals substantial behavioral details: spans are resolved through the timeline and never stored as seconds, cuts move them, a cut through the start word makes export refuse, the stack order determines draw order, and any overlay routes export through the MLT writer. This is meaningful context the annotations alone do not provide.

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 dense but every sentence earns its place: purpose, prerequisites, span semantics, stack ordering, and call consequences. It is front-loaded with the clearest statement of what the tool does and then layers supporting detail logically, which is efficient for a tool with this many parameters.

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?

Given 27 parameters, a fully documented input schema, an output schema, and meaningful annotations, the description adds the missing conceptual glue needed to call the tool correctly. Return values are covered by the output schema, and defaults are covered by the schema descriptions, so nothing essential is left unexplained.

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?

Although schema coverage is 100%, the description supplies the unifying conceptual model: what a span is, how start/end selectors relate, that card/graphic/image are alternative sources, and that position expresses stack order. This helps an agent choose among the many interrelated parameters rather than treating each parameter in isolation.

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 opening sentence names a concrete action ('Draw ... over the film') and a precise resource, then enumerates supported content types: a transparent card, an animated graphic, or a still, with examples like lower third and sticker. This clearly differentiates it from overlay_ls/overlay_rm and from the content-creation tools card_new, graphic_new, and image_add.

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?

It gives explicit preconditions ('Make the card first with card_new from lowerthird or scrim'), stacking rules ('Put the scrim first ... then the lowerthird'), and a preview path ('plan=true writes nothing'). It also covers edge cases such as a staggered footnote and warns about timeline-sensitive span behavior, giving an agent clear guidance on how and when to invoke this tool.

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

Deploy Server