proofcut

Overview Schema Source Related Servers Discussions Admin

footage_sheet

DestructiveIdempotent

See what's inside a video clip as labeled thumbnails, even without an edit, cues, or transcript. Use it to browse b-roll, recordings, or gameplay and pick the right footage.

Instructions

Look at a clip's own footage — one labelled tile per moment, as an image.

The tool to see what is in some footage, as opposed to shot_sheet, which shows an existing edit's picture track. It needs no edit, cues or transcript, so it is the first look at b-roll, recordings and gameplay — material describe can search by text but cannot show. The bytes come back in the reply.

mode picks the instants: auto (described windows if the clip has any, else the interval), interval, describe (each tile beside its window's sentence), or scenes (one per detected cut — opt-in, since a continuous take has none and a scan decodes the whole clip). page walks a long recording. A tile with nothing in it is marked [blank] on the picture, so a black square is never mistaken for a frame that failed to extract.

What you see is a hypothesis, not a check — and this sheet is read to choose footage. synopsis is where a person says what a clip is; a tile shows what the camera saw, which is a different fact.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`out`	No	Write the image to this path as well, replacing whatever file is there. Unset, it goes to the project's own sheet cache and only the bytes come back.
`mode`	No	Which instants to draw: `auto` (the default) uses the clip's described windows if it has any and the interval otherwise, and never scans; `interval` draws every `interval` seconds; `describe` draws one tile per described window, beside its text; `scenes` draws one per detected cut. Scenes is opt-in because its yield is uncorrelated with anything the caller knows — 0 cuts on a 29s b-roll loop, 17 in 60s of gameplay — and it decodes the whole clip.	auto
`page`	No	Which page of rows to draw, from 1. Unset, the first.
`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.
`clip_id`	Yes	The registered clip to browse. This sheet reads the clip's own source, so it needs no edit, no cues and no transcript.
`interval`	No	Seconds between tiles when drawing by interval (`interval`, or `auto` on a clip with no descriptions). It is `describe`'s own window length, so a tile lines up with a description.
`per_page`	No	Rows per page. `null` draws the whole project in one montage, which returns a path rather than readable bytes — for a person to open, not for an agent to read.

Schema Changelog

Changes observed during successful MCP inspections.

Changed19 schema fields changedv0.25.0Sep 16, 2026

addedInput schema / properties / clip_id / description

Added value: +"The registered clip to browse. This sheet reads the clip's **own source**, so it needs no edit, no cues and no transcript."

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

addedInput schema / properties / interval / description

Added value: +"Seconds between tiles when drawing by interval (`interval`, or `auto` on a clip with no descriptions). It is `describe`'s own window length, so a tile lines up with a description."

removedInput schema / properties / interval / title
```
Removed value: -"Interval"
```

addedInput schema / properties / mode / description

Added value: +"Which instants to draw: `auto` (the default) uses the clip's described windows if it has any and the interval otherwise, and never scans; `interval` draws every `interval` seconds; `describe` draws one tile per described window, beside its text; `scenes` draws one per detected cut. Scenes is opt-in because its yield is uncorrelated with anything the caller knows — 0 cuts on a 29s b-roll loop, 17 in 60s of gameplay — and it decodes the whole clip."

removedInput schema / properties / mode / title
```
Removed value: -"Mode"
```

removedInput schema / properties / out / anyOf

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

addedInput schema / properties / out / description

Added value: +"Write the image to this path as well, replacing whatever file is there. Unset, it goes to the project's own sheet cache and only the bytes come back."

removedInput schema / properties / out / title
```
Removed value: -"Out"
```

addedInput schema / properties / out / type

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

addedInput schema / properties / page / description

Added value: +"Which page of rows to draw, from 1. Unset, the first."

removedInput schema / properties / page / title
```
Removed value: -"Page"
```

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 / per_page / description

Added value: +"Rows per page. `null` draws the whole project in one montage, which returns a path rather than readable bytes — for a person to open, not for an agent to read."

removedInput schema / properties / per_page / title
```
Removed value: -"Per Page"
```

removedInput schema / title

Removed value: -"footage_sheetArguments"

First observedv0.24.0Sep 15, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations declare destructiveHint=true and idempotentHint=true, but the description adds meaningful behavioral context: it returns bytes in the reply, marks blank tiles as '[blank]' to avoid confusion with failed extraction, and warns that the sheet is 'a hypothesis, not a check' and is read to choose footage. It also discloses that scenes mode decodes the whole clip. This goes beyond the annotations without contradicting them.

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?

The description is dense but well-organized: a one-sentence summary, a paragraph on positioning, a paragraph on modes, and a paragraph on interpretation. Every sentence earns its place, though the mode paragraph is long and could be tightened. The key contrast with shot_sheet is front-loaded.

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?

For a 7-parameter tool with no output schema, the description covers the main behavioral concerns: what the output looks like (image tiles, bytes in reply), how modes interact, and the caveat that it's a hypothesis. It doesn't explicitly describe the full return structure, but the description's emphasis on 'bytes come back' and 'path rather than readable bytes' covers the essential return distinction. The blank-tile behavior and scenes opt-in warning are valuable completeness additions.

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%, so the baseline is 3. The description adds value by explaining the relationship between interval and describe windows ('It is describe's own window length, so a tile lines up with a description'), clarifying that per_page=null returns a path rather than bytes, and explaining the path resolution behavior for bound vs unbound servers. These are semantic details beyond the schema.

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 a specific verb and resource: 'Look at a clip's own footage — one labelled tile per moment, as an image.' It immediately distinguishes itself from shot_sheet ('shows an existing edit's picture track') and describe ('can search by text but cannot show'). The purpose is unmistakable and differentiated 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 Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: 'the first look at b-roll, recordings and gameplay' and contrasts it with shot_sheet and describe. It also explains mode selection semantics (auto, interval, describe, scenes) and when scenes is appropriate ('opt-in, since a continuous take has none'). This is explicit when/when-not guidance.

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

Deploy Server

footage_sheet

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools