proofcut

Overview Schema Source Related Servers Discussions Admin

describe

DestructiveIdempotent

Labels video footage in fixed time windows so b-roll can be found by what is in it. Supports a plan mode to preview the work before writing.

Instructions

Describe footage in fixed windows, so b-roll can be found by what is in it.

A description is (clip_id, src_start, src_end, text) in source seconds, which is why cutting the edit can never invalidate one. Omit clip_id to describe every video clip that has not been described yet; name one to do just that clip. Audio-only clips are refused — their words are what transcribe indexes.

This is a job, not a request. Cost is about three seconds per window regardless of how much footage the window spans, so a project's footage is minutes of GPU time. Run it with plan=True first: that resolves the whole work list and the estimate, and reports whether this machine can run the model at all, without loading anything.

Already-described clips are skipped unless force. Do not widen window to save time without a reason — a single pass over a whole clip describes six frames as six people, fluently and with nothing saying it is wrong.

Read errors and truncated in the result. A truncated description stops mid-fact and reads exactly like a complete one, and a window is never evidence of a continuous shot: the model narrates across a cut inside one as though it were a single take.

The descriptions are written into the project, and force replaces the ones a clip already has; without it an already-described clip is skipped, so a repeat costs nothing and changes nothing.

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.
`plan`	No	Resolve the whole call and report what it would do, writing nothing. Prefer it over doing the thing and undoing it.
`force`	No	Describe clips that already have descriptions, replacing them. Without it they are skipped.
`window`	No	Seconds of footage per description. Do not widen it to save time: a single pass over a whole clip describes six frames as six people, fluently, with nothing saying it is wrong.
`clip_id`	No	One clip to describe. Omit it for every video clip not described yet; audio-only clips are refused, since their words are what `transcribe` indexes.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed15 schema fields changedv0.25.0Sep 16, 2026

removedInput schema / properties / clip_id / anyOf

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

addedInput schema / properties / clip_id / description

Added value: +"One clip to describe. Omit it for every video clip not described yet; audio-only clips are refused, since their words are what `transcribe` indexes."

removedInput schema / properties / clip_id / title
```
Removed value: -"Clip Id"
```
addedInput schema / properties / clip_id / type
```
Added value: +[
+  "string",
+  "null"
+]
```

addedInput schema / properties / force / description

Added value: +"Describe clips that already have descriptions, replacing them. Without it they are skipped."

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"
+]

addedInput schema / properties / plan / description

Added value: +"Resolve the whole call and report what it would do, writing nothing. Prefer it over doing the thing and undoing it."

removedInput schema / properties / plan / title
```
Removed value: -"Plan"
```

addedInput schema / properties / window / description

Added value: +"Seconds of footage per description. Do not widen it to save time: a single pass over a whole clip describes six frames as six people, fluently, with nothing saying it is wrong."

removedInput schema / properties / window / title
```
Removed value: -"Window"
```
removedInput schema / title
```
Removed value: -"describeArguments"
```

First observedv0.24.0Sep 15, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations declare destructiveHint=true and idempotentHint=true, and the description enriches both: the GPU cost model (~3s per window, minutes of project footage), that plan=True runs without loading the model and reports machine capability, that force replaces while a plain repeat costs nothing, and the two serious pitfalls — truncated descriptions read exactly like complete ones, and a window is never evidence of a continuous shot. No contradiction with annotations.

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?

Front-loaded with the core purpose and data model before the cost and pitfall discussion, and every sentence earns its place. Mild redundancy: the final paragraph restates the force/skip behavior already covered by 'Already-described clips are skipped unless force' earlier, which is the only trimming opportunity in an otherwise tight definition.

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 complex, cost-bearing, GPU-running tool with an output schema present (so return values need not be explained), the description is remarkably complete. It covers cost, machine-capability preflight, idempotency, destructive replacement semantics, and the two failure modes an agent could not guess (truncation that looks complete, narration across cuts). Nothing an agent needs to call it correctly is missing.

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% and the schema descriptions are already rich, so baseline is 3. The tool description adds genuine value on top: the omitting-clip_id semantics (describe all undescribed video clips), the reframe-proof rationale for source seconds, and the concrete 'six frames as six people' example that motivates not widening window. This elevates it above the baseline.

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?

Opens with a specific verb+resource+purpose ('Describe footage in fixed windows, so b-roll can be found by what is in it'), then pins down the data model (clip_id, src_start, src_end, text). It actively distinguishes itself from transcribe ('their words are what transcribe indexes') and describes_ls is implied by the read-the-result guidance, so an agent can tell it apart from its close siblings without opening schemas.

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?

Explicit when-to-use and when-not: audio-only clips go to transcribe, already-described clips are skipped unless force, and it names plan=True as the preferred first invocation for a cost-bearing job. It even warns against widening window to save time. No alternative or condition is left to inference.

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

Deploy Server