proofcut

Overview Schema Source Related Servers Discussions Admin

reframe_detect

Idempotent

Proposes per-shot framing windows from detected faces, improving composition over a center crop without applying changes. Review the proposal sheet first; apply only if it fits.

Instructions

Propose a framing window per camera shot, from where the faces are.

Every placement is split at its camera cuts, each window sampled at a few moments and centred on the faces found. Against fifteen hand-framed, approved windows it beats the centre crop on every measure (0.755 mean overlap against 0.568).

It proposes; it does not frame. apply is off by default: the pass is still about a quarter of a window's width out on average, and a wrong window reads as framing in motion. Look at reframe_sheet before applying. Applying writes through reframe and never over an existing override.

A window with no face is refused, never guessed at — expect about one in seven — and nothing is written for it, so read falls_back_to: at a clip's head that is the centre crop, anywhere else the previous shot's framing. Nothing here chooses the subject either.

A window one crop cannot hold comes back as a stacked split (rect and pane). Read subjects (per frame), not faces, which sums detections across samples and calls one face three. Needs PROOFCUT_FACE.

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.
`apply`	No	Write the proposals through `reframe`. Off by default — the opposite of `cut --plan` — because the pass runs 24% of a window's width out on average. Call `reframe_sheet` and look first. It never writes over a window that is already an override.
`split`	No	Offer a stacked split where every sampled frame holds two or three faces one window cannot hold. On by default; `false` turns the offer off.
`frames`	No	How many moments to sample inside each window before centring it on the faces found there.
`clip_id`	No	Propose windows for one clip. Omit it for every placed clip.
`threshold`	No	How strong a scene change has to be to count as a camera cut, 0–1. 0.15 is pinned by judging detections on real footage: every candidate from 0.141 to 0.244 was a real cut, and the first non-cut is 0.137.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed17 schema fields changedv0.25.0Sep 16, 2026

addedInput schema / properties / apply / description

Added value: +"Write the proposals through `reframe`. Off by default — the opposite of `cut --plan` — because the pass runs 24% of a window's width out on average. Call `reframe_sheet` and look first. It never writes over a window that is already an override."

removedInput schema / properties / apply / title
```
Removed value: -"Apply"
```

removedInput schema / properties / clip_id / anyOf

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

addedInput schema / properties / clip_id / description

Added value: +"Propose windows for one clip. Omit it for every placed clip."

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

addedInput schema / properties / frames / description

Added value: +"How many moments to sample inside each window before centring it on the faces found there."

removedInput schema / properties / frames / title
```
Removed value: -"Frames"
```

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

Added value: +"Offer a stacked split where every sampled frame holds two or three faces one window cannot hold. On by default; `false` turns the offer off."

removedInput schema / properties / split / title
```
Removed value: -"Split"
```

addedInput schema / properties / threshold / description

Added value: +"How strong a scene change has to be to count as a camera cut, 0–1. 0.15 is pinned by judging detections on real footage: every candidate from 0.141 to 0.244 was a real cut, and the first non-cut is 0.137."

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

removedInput schema / title

Removed value: -"reframe_detectArguments"

First observedv0.24.0Sep 15, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already mark this as non-read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond those: apply is off by default, refused windows produce no output, falls_back_to behavior at clip heads vs elsewhere, stacked splits, and the PROOFCUT_FACE dependency. It also clarifies the non-destructive 'never over an existing override' behavior, which is consistent with destructiveHint=false.

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 long but front-loaded with the core purpose and then organized into behavioral warnings, edge cases, and dependencies. Some benchmark statistics and repeated accuracy caveats are arguably extra, but they earn their place by justifying why apply is off by default and why review is needed.

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 proposal tool with six optional parameters, an output schema, and several edge cases, this description covers the essential invocation context: what gets proposed, what is refused, what fallback behavior to expect, how splits work, and the required environment variable. The presence of an output schema means return-value documentation is not needed in the description.

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?

Schema description coverage is 100%, so the schema already documents all six parameters thoroughly. The description adds useful behavioral context for apply and split, and warns about reading subjects rather than faces, but it does not need to compensate for missing parameter docs. Baseline 3 is appropriate.

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 first sentence states a specific action and resource: 'Propose a framing window per camera shot, from where the faces are.' It further distinguishes itself from the apply step with the explicit contrast 'It proposes; it does not frame,' making its role among siblings like reframe and reframe_sheet clear.

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 makes the workflow obvious: proposals are not applied by default, one should 'Look at reframe_sheet before applying,' and applying writes through reframe. It does not explicitly enumerate all sibling alternatives or say 'use reframe_detect when...', but the propose-vs-apply framing and the reference to reframe_sheet give strong contextual guidance.

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

Deploy Server