proofcut

Overview Schema Source Related Servers Discussions Admin

restore

DestructiveIdempotent

Bring back cut word ranges from a source clip into the timeline, restoring only the absent material and leaving present content untouched.

Instructions

Un-cut whichever part of these inclusive word ranges is not currently in the timeline.

Same range shape as cut_by_transcript's cut=/keep=. Each range resolves to source time exactly like a cut does; only the part Edit.gaps says is actually absent comes back — material still present in the request is left alone, a request spanning two separate cuts restores both as separate pieces, a request only touching part of one cut restores only that part. Restoring only ever brings back material the source recording already has (bounded by the clip's own registered duration), so the timeline stays a subset of the source throughout — this is not vo_extend (PLAN.md parks that separately), which would add material the source never had.

pad matches cut_by_transcript's own pad: pass the same value used on the original cut to bring back its padding sliver, not just the words.

Unlike a cut, there is no suspect-duration refusal — a boundary that looks like it swallowed a retake is exactly the kind of thing restore exists to bring back, not a mistake to guard against.

Refused if clip_id has no surviving segment anywhere in the edit (nothing left of it to splice the range next to — undo or re-seed instead), or if its segments are not contiguous in the edit (an interleaved multi-source timeline, which restore does not support yet).

plan=True resolves and reports without writing, identically to cut_by_transcript.

Input Schema

TableJSON Schema

Name	Required	Description
`pad`	No	Pass the same `pad` the original cut used to bring its padding sliver back, not only the words.
`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.
`ranges`	Yes	Inclusive word ranges, the shape `cut_by_transcript` takes. Only the part the edit says is actually absent comes back; material still present is left alone.
`clip_id`	Yes	The clip whose cut material to bring back.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed13 schema fields changedv0.25.0Sep 16, 2026

addedInput schema / properties / clip_id / description

Added value: +"The clip whose cut material to bring back."

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

addedInput schema / properties / pad / description

Added value: +"Pass the same `pad` the original cut used to bring its padding sliver back, not only the words."

removedInput schema / properties / pad / title
```
Removed value: -"Pad"
```

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

Added value: +"Inclusive word ranges, the shape `cut_by_transcript` takes. Only the part the edit says is actually absent comes back; material still present is left alone."

removedInput schema / properties / ranges / title
```
Removed value: -"Ranges"
```
removedInput schema / title
```
Removed value: -"restoreArguments"
```

First observedv0.24.0Sep 15, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial behavioral detail: it explains partial restoration, multiple-cut handling, padding sliver recovery, the subset-of-source constraint, and the refusal conditions. It explicitly contrasts with vo_extend and notes the plan mode writes nothing. No contradiction with annotations; idempotentHint=true aligns with 'material still present is left alone.'

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 well-structured and front-loaded with the core purpose. It flows logically from the primary function to range behavior, pad handling, differences from cuts, refusal conditions, and plan mode. Every sentence adds meaningful context; it is not bloated with fluff, though it could be tightened slightly for brevity.

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 of this complexity, the description covers all necessary aspects: what it does, how ranges behave, pad semantics, differences from cut, refusal conditions, and plan mode. It references the output schema exists, and the description does not need to explain return values since an output schema is present. It is complete for an agent to call correctly.

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 already provides 100% coverage with detailed descriptions for every parameter, including pad, ranges, and clip_id. The tool description reiterates some of these (e.g., 'pad matches cut_by_transcript's own pad') but adds little beyond what the schema states. It offers helpful context on range resolution, but since the schema already does the heavy lifting, a baseline of 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 description opens with a clear verb-resource pair: 'Un-cut whichever part of these inclusive word ranges is not currently in the timeline.' It explicitly states the tool's purpose (restoring removed material) and distinguishes it from siblings like cut_by_transcript and vo_extend, leaving no ambiguity about what it does.

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 gives explicit when-to-use and when-not-to-use guidance. It names vo_extend as the alternative for adding material the source never had, notes the absence of suspect-duration refusal that a cut would have, and lists two refusal conditions (no surviving segment or non-contiguous segments) with the fallback actions (undo or re-seed). It also recommends plan=True for preview.

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

Deploy Server