proofcut

Overview Schema Source Related Servers Discussions Admin

graphic_new

DestructiveIdempotent

Create an animated graphic from a template or custom HTML, with intro, hold, and outro phases for precise placement in a video timeline.

Instructions

Make an animated graphic — a web page, captured frame by frame — from a template or your own HTML.

A graphic has three phases, in seconds of the page's own timeline: an intro that plays once from the start of wherever it is placed, a hold that fills whatever the span leaves (the page's last intro frame, or loop seconds repeated), and an outro that plays once to end the span. The span decides the length, never the graphic, so cuts cannot break it. Write the page's outro animations to start where the intro ends (after one loop, if it loops). Nothing on the page may load from the network.

Place it with overlay_add(graphic=name). Then look at it with graphic_sheet. The capture draws at the project's canvas and export rate; changing either makes it stale, and export refuses a stale graphic.

Input Schema

TableJSON Schema

Name	Required	Description
`html`	No	A whole page, written by hand. CSS animations and transitions are seeked frame by frame; a script animating from its own clock must define window.proofcutSeek(seconds). Fonts load from /_proofcut/fonts/static/Outfit-Regular.ttf and Outfit-Bold.ttf; nothing loads from the network.
`loop`	No	Seconds of the page after the intro to repeat through the hold, for a hold that moves (a blinking caret). Unset, the hold is the page's last intro frame, still; a page still moving there is refused.
`name`	Yes	The graphic's name: lowercase letters, digits, - and _. overlay_add places it by this name.
`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.
`intro`	No	Seconds of the page that play once from the start of the span.
`outro`	No	Seconds of the page, from the hold on, that play once to end the span.
`pages`	No	Browser pages capturing side by side, 1 to 8. Default 2.
`slots`	No	The template's slots, as text. A colour is #rrggbb, a number a number.
`capture`	No	Capture it now. False writes the page and draws nothing.
`replace`	No	Replace a graphic of this name. Unset, an existing one is refused.
`template`	No	A template to fill (graphic_templates lists them). One of template or html.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.43.0Sep 24, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Even with annotations present, the description adds substantial behavioral context: the three-phase timeline, the fact that the span decides length, the network-loading prohibition, the stale-on-canvas-change behavior, and that export refuses stale graphics. This goes well beyond the structured annotations and gives an agent critical non-obvious constraints.

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 four dense sentences, front-loaded with purpose, then the phase model, then hard constraints, then lifecycle actions. Every sentence carries necessary information without filler or repetition.

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?

For a tool with 11 parameters, an output schema, and annotations, the description covers the conceptual model (phases, span, staleness), hard constraints (no network, no still-moving holds), and integration (overlay_add, graphic_sheet). It also relies on the schema for per-parameter details and the output schema for return values, 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.

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning around the phased semantics — intro, hold, loop, and outro — and explains the relationship between these durations and the page's timeline, which is not fully captured by the individual parameter descriptions. This lifts it above baseline, though the schema already does most of the per-parameter work.

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 opens with 'Make an animated graphic — a web page, captured frame by frame — from a template or your own HTML,' which names a specific verb, resource, and means of creation. This clearly distinguishes graphic_new from siblings like graphic_edit, graphic_capture, and graphic_ls.

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?

The description gives concrete lifecycle guidance: 'Place it with overlay_add(graphic=name)' and 'Then look at it with graphic_sheet,' and points to graphic_templates for available templates. It doesn't explicitly contrast graphic_new with graphic_edit or state when not to use it, but the creation-vs-editing role is strongly implied by the name, description, and sibling set.

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

Deploy Server