proofcut

Overview Schema Source Related Servers Discussions Admin

proxy_transcode

Idempotent

Transcodes unplayable footage into a downscaled H.264/AAC/MP4 proxy in the project cache so the preview can play it; skips clips with a current proxy or that already play.

Instructions

Make footage the preview cannot decode playable in the window.

The other half of what the viewer already reports: an unplayable clip names its reason (hev1, 10-bit, an unopenable container, an undecodable audio track) and shows black. This transcodes a downscaled h264/aac/mp4 stand-in into the project's cache so it plays. One ffmpeg pass; a long clip is minutes.

The result is a preview artefact and cannot reach a render: nothing records it in the manifest, so media_path() — what export, verify and check_frames all resolve through — has no way to see it. That containment is structural, not a convention to be careful about.

Skips the work when a current proxy already exists (keyed by the source's size and mtime), so calling it on every unplayable clip in a project is cheap after the first pass. Refuses a clip that already plays, and refuses a file with no decodable streams — that is a broken file, not a codec problem, and it is the one refusal a transcode cannot close. force rebuilds a current proxy but does not override either refusal.

Input Schema

TableJSON Schema

Name	Required	Description
`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.
`force`	No	Rebuild a proxy that is already current. It touches nothing authored: a proxy is a preview artefact the manifest never records, so no render can reach one. It overrides neither refusal.
`clip_id`	Yes	The clip the preview cannot decode. A clip that already plays is refused, and so is one with no decodable streams — that is a broken file, not a codec problem.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv0.25.0Sep 16, 2026

addedInput schema / properties / clip_id / description

Added value: +"The clip the preview cannot decode. A clip that already plays is refused, and so is one with no decodable streams — that is a broken file, not a codec problem."

removedInput schema / properties / clip_id / title
```
Removed value: -"Clip Id"
```

addedInput schema / properties / force / description

Added value: +"Rebuild a proxy that is already current. It touches nothing authored: a proxy is a preview artefact the manifest never records, so no render can reach one. It overrides neither refusal."

removedInput schema / properties / force / title
```
Removed value: -"Force"
```

removedInput schema / properties / path / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / path / description

Added value: +"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."

removedInput schema / properties / path / title
```
Removed value: -"Path"
```

addedInput schema / properties / path / type

Added value: +[
+  "string",
+  "null"
+]

removedInput schema / title

Removed value: -"proxy_transcodeArguments"

First observedv0.24.0Sep 15, 2026

TDQS

A4.5/5.0

Behavior5/5

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

The description is unusually transparent: it discloses the side effect (writing a cache proxy), the performance profile (one ffmpeg pass; long clips take minutes), the structural containment from renders, the idempotent caching behavior, both refusal conditions, and what `force` does and does not override. These go well beyond the annotations, which already mark the tool as non-read-only, non-destructive, and idempotent. No contradiction exists between the description and annotations.

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 front-loaded with a one-sentence purpose and then expands into distinct, clearly separated concerns: mechanics, render containment, idempotency, and refusals. Every paragraph earns its place given the tool's nuanced non-obvious behavior; there is no filler or redundant 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 this complexity and with rich annotations and schema, the description covers everything needed to invoke it correctly: what it produces, where it writes, how long it takes, when it skips, when it refuses, what `force` does, and why the proxy cannot leak into renders. An output schema exists, so not describing return values is acceptable.

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?

Input schema coverage is 100%, and the schema already explains `path` binding rules, `force` behavior, and `clip_id` refusals in detail. The free-text description adds useful operational context, such as the ffmpeg pass and proxy-cache behavior, but it does not add new per-parameter semantics beyond what the schema already provides. Baseline 3 is appropriate for full schema coverage.

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 names the precise verb ('transcodes'), the resource (a downscaled h264/aac/mp4 stand-in in the project cache), and the triggering condition (footage the preview cannot decode). It clearly separates this preview-only proxy behavior from render/export behavior, so it distinguishes itself from siblings.

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 clearly says when to call the tool — on unplayable clips — and gives strong exclusions: refuse clips that already play, refuse files with no decodable streams, and skip work when a current proxy exists. It also clarifies that the result cannot reach a render, which sets expectations versus export/verify/check_frames. It does not name a specific sibling alternative, but no obvious sibling competes for this action.

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

Deploy Server