proofcut

Overview Schema Source Related Servers Discussions Admin

reframe_coverage

Read-onlyIdempotent

Audit a project's reframed clips for stale stretches and false cuts. Detects window boundaries that miss scene cuts or slide mid-take, reporting timeline_start, shift, and nearest_cut to guide reframe_sheet fixes.

Instructions

Which placed seconds are framed by a window chosen for an earlier shot.

The question reframe_detect cannot answer: that one is about a proposal, this is about the project on disk. A refused proposal writes nothing, so a stretch can sit under a rect chosen for a shot that ended long before — 13.6s of one clip across four camera setups on the film, with the manifest, status and reframe_sheet all clean.

Every placement is walked against its source's scene cuts. A cut with no window boundary within a frame of it opens a stale stretch. Read stale_seconds — an override held across a cut, which looks deliberate — not default_seconds (the centre crop, only the default doing what it always did). Each stretch carries timeline_start; the fix is reframe_sheet to look, then reframe_detect on the clip.

steps is the mirror, and the one a viewer notices: a window boundary with no cut, where the frame slides sideways mid-take and reads as an edit that is not there. Each carries shift and nearest_cut.

Needs no face detector, reads and never writes — but it decodes placed footage, so it is seconds, not free.

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.
`clip_id`	No	Walk one clip's placements. Omit it for the whole project.
`threshold`	No	How strong a scene change has to be to demand a window. Boundaries are scored against every detected cut rather than only these, since a cut too weak to demand a window still explains one.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 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: +"Walk one clip's placements. Omit it for the whole project."

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

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

Added value: +"How strong a scene change has to be to **demand** a window. Boundaries are scored against every detected cut rather than only these, since a cut too weak to demand a window still explains one."

removedInput schema / properties / threshold / title
```
Removed value: -"Threshold"
```

removedInput schema / title

Removed value: -"reframe_coverageArguments"

First observedv0.24.0Sep 15, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces 'reads and never writes' and adds valuable context: 'Needs no face detector, reads and never writes — but it decodes placed footage, so it is seconds, not free' (discloses compute cost). It also discloses output fields ('Each stretch carries `timeline_start`', 'Each carries `shift` and `nearest_cut`'), which goes beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is verbose and narrative, including an extended anecdote ('13.6s of one clip across four camera setups...') and metaphor ('the mirror, and the one a viewer notices'). While rich, it is not front-loaded and each sentence does not earn its place; an agent must parse a lot of prose to extract the core operational details. The structure could be tightened significantly without losing meaning.

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?

The description covers the tool's purpose, its distinction from `reframe_detect`, the concepts of 'stale stretch' and 'steps', output fields, cost, and the follow-up workflow (`reframe_sheet` then `reframe_detect`). Given the tool's complexity and the presence of an output schema, this is quite complete. It could be more systematic, but it does not leave major gaps.

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?

The input schema has 100% description coverage for all three parameters (path, clip_id, threshold). The description does not add any extra parameter-specific meaning beyond what the schema already provides. Since the schema fully documents the parameters, the baseline of 3 is appropriate; there is no additional value from the description.

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 states exactly what the tool does: 'Which placed seconds are framed by a window chosen for an earlier shot.' It uses a specific verb ('framed') and names the resource ('placed seconds'), and it immediately differentiates from sibling `reframe_detect` by contrasting proposal vs. on-disk state. The purpose is unambiguous and distinct.

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 explains when NOT to use it: 'The question `reframe_detect` cannot answer: that one is about a proposal, this is about the project on disk.' It also prescribes the workflow: 'the fix is `reframe_sheet` to look, then `reframe_detect` on the clip.' This gives clear usage guidance and directs the agent to the right alternative.

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

Deploy Server