proofcut

Overview Schema Source Related Servers Discussions Admin

timeline_view

Read-onlyIdempotent

Inspect an entire video edit at once: see segments, cut seams, word survival, and shot cues to locate and fix problem cuts.

Instructions

The whole edit at once: segments, cut seams, and every word's fate.

timeline_status counts things; this says what they are. Each segment carries both coordinate systems (source in, timeline out), each seam is named by the surviving words either side of it rather than by the second it currently sits at, and each word reports whether it survived, how much of it did, and where it now plays.

Survival is an overlap test, so a word a cut split reports present with partial set — that is normal on whisper timings, not a defect. Words with a suspect duration carry the same flag attach_transcript reported.

This is locate asked once for the whole clip instead of once per range, and it is what the proofcut web view draws. Read-only.

shots is the picture lane the cue table projects — null when there are no cues, and null with a shots_error message when the plan refuses (a cue that was cut, or a shot longer than the asset it points at). The refusal is reported here rather than raised, because this is the view a person uses to find the cue to fix. shots_rate is the frame grid it was quantised on, which is export's rate and not timebase.

segments/shots/seams stay Edit-relative even with a head configured — see head's own docstring for the two-clock rule. head_seconds is the offset a render-time reader needs (0.0 with none); head is the stored config plus its resolved frame count.

words is a window of limit from first (words_total, words_next); the lanes are always whole. get_transcript with search= finds a word faster than paging here.

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.
`first`	No	Index into the `words` list to start the window at. 0 by default.
`limit`	No	Most entries of `words` to return; `words_next` says where to continue. The segments, seams and shots are always whole.
`clip_id`	No	The transcript whose words' fate to report. A clip that is registered but not on the edit still answers — read `off_timeline`, or every word reads `present: false` and looks cut.

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: +"The transcript whose words' fate to report. A clip that is registered but not on the edit still answers — read `off_timeline`, or every word reads `present: false` and looks cut."

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

addedInput schema / properties / first

Added value: +{
+  "default": 0,
+  "description": "Index into the `words` list to start the window at. 0 by default.",
+  "type": "integer"
+}

addedInput schema / properties / limit

Added value: +{
+  "default": 100,
+  "description": "Most entries of `words` to return; `words_next` says where to continue. The segments, seams and shots are always whole.",
+  "type": "integer"
+}

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

removedInput schema / title

Removed value: -"timeline_viewArguments"

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 readOnly/idempotent, and the description adds substantial non-obvious behavior: partial survival is normal on whisper timings, shots refusals are reported not raised, segments/shots/seams stay edit-relative under head, and the shots_rate grid is export's rate not timebase. This goes well beyond the annotation baseline.

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 and dense but front-loaded with a one-sentence summary and organized into clear thematic paragraphs. Some phrasing is poetic ('every word's fate', 'the picture lane the cue table projects') but generally every paragraph earns its place given the tool's complexity.

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?

The description covers edge cases thoroughly: partial survival, suspect durations, shots null/refusal behavior, head clock relativity, pagination windowing, and the search alternative. With an output schema present and detailed input schema, an agent has everything needed to call and interpret the tool 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?

Schema description coverage is 100%, so the baseline is 3 even without parameter details in the description. The description adds only modest param-level value — noting words is a window while lanes stay whole and recommending get_transcript for faster single-word search — but does not meaningfully override what the schema already provides.

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 line — 'The whole edit at once: segments, cut seams, and every word's fate' — states a specific resource and scope. It explicitly contrasts with timeline_status ('counts things; this says what they are') and frames itself as 'locate asked once for the whole clip instead of once per range,' making differentiation from siblings immediate.

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 names alternatives explicitly and gives selection conditions: use this instead of timeline_status when item-level detail is needed, use get_transcript with search= for faster single-word lookup, and use locate for per-range queries. This satisfies both 'when' and '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