proofcut

Overview Schema Source Related Servers Discussions Admin

caption_view

Read-onlyIdempotent

Preview captions and style for any moment before writing a file. Read-only: returns cues in timeline seconds, grouped by project rules, or errors for missing transcripts.

Instructions

The captions this timeline would produce, and the style in force.

add_captions without writing a file: the same cues, in timeline seconds, already grouped by the project's own break rules — so this is how to check a restyle, or read back what a caption actually says at some moment, before committing a file to it.

Reports rather than refuses: a project with no transcript, or one whose every word has been cut, comes back with an empty cues and a cues_error saying which. Read-only.

cues is a window of limit from first; cues_total is how many the film has and cues_next, when present, where to continue. Use locate to find the cue at a moment rather than paging to it.

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 of the first cue to return. 0 by default.
`limit`	No	Most cues to return; `cues_next` says where to continue.
`clip_id`	No	Show one transcript's captions rather than every clip's.

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: +"Show one transcript's captions rather than every clip's."

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 of the first cue to return. 0 by default.",
+  "type": "integer"
+}

addedInput schema / properties / limit

Added value: +{
+  "default": 30,
+  "description": "Most cues to return; `cues_next` says where to continue.",
+  "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: -"caption_viewArguments"
```

First observedv0.24.0Sep 15, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds beyond this by explaining that it reports rather than refuses (empty `cues` and a `cues_error` for missing transcripts) and describes the pagination fields (`cues_total`, `cues_next`). It also notes that cues are grouped by the project's break rules. This is useful behavioral context not covered by annotations.

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

Conciseness5/5

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

The description is compact and each sentence serves a purpose. It front-loads the core purpose, then usage, then error behavior, then pagination. No fluff; every line contributes to accurate tool selection and invocation.

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?

Given that an output schema exists, the description still explains the important return fields (cues, cues_error, cues_total, cues_next) and how to navigate them. It addresses edge cases (missing transcript) and recommends an alternative for time-based lookup. For a read-only tool, this is complete.

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 description coverage is 100%, so the baseline is 3. The description adds meaning by explaining the relationship between `first`, `limit`, and `cues_next` (a window of `limit` from `first`), and suggests using `locate` instead of paging. It also clarifies that `cues` is a window, which goes beyond the individual parameter descriptions.

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 states a specific purpose: it returns the captions a timeline would produce along with the active style, and explicitly contrasts itself with add_captions (which writes a file). This clearly distinguishes it from siblings like caption_style or cue_ls. The phrase 'The captions this timeline would produce, and the style in force' is a precise verb-resource pairing.

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?

It explicitly states when to use this tool: 'this is how to check a restyle, or read back what a caption actually says at some moment, before committing a file to it.' It also names the alternative (add_captions) that writes, and recommends using `locate` for finding a cue at a moment rather than paging. This gives clear when-to and when-not-to guidance.

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

Deploy Server