proofcut

Overview Schema Source Related Servers Discussions Admin

synopsis

DestructiveIdempotent

Define what a clip is—its work, scene, and people—to choose b-roll that matches your narrative. Read, set, or clear this meaning for any clip.

Instructions

Read, set or clear what a clip is — the corpus b-roll gets chosen from.

No clip_id lists every clip's synopsis and which are missing one; clip_id alone reads one; text writes; clear removes.

A synopsis is a different fact from a describe window. A description says what is in front of the camera — rooms, clothing, lighting. A synopsis says what the footage is: the work, the scene, the people, and whatever else decides whether it belongs under a sentence. It is meant to carry what no camera can see, because that is where the signal turned out to be — measured on real footage, the vision index chose the same clip a human did 2 times in 25, and this catalogue read by something that knows the material chose it 13.

Write these yourself. Nothing generates them: a model looking at the pixels cannot, and guessing a title from a filename would produce confident wrong placements rather than an obviously empty catalogue.

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.
`text`	No	What this footage is — the work, the scene, the people. A different fact from a `describe` window, which says what is in front of the camera. Write it yourself: nothing generates one, because a model reading the pixels measurably cannot.
`clear`	No	Remove this clip's synopsis.
`clip_id`	No	The clip to read or write. Omit it to list every clip's synopsis and which are missing one.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed15 schema fields changedv0.25.0Sep 16, 2026

addedInput schema / properties / clear / description
```
Added value: +"Remove this clip's synopsis."
```
removedInput schema / properties / clear / title
```
Removed value: -"Clear"
```

removedInput schema / properties / clip_id / anyOf

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

addedInput schema / properties / clip_id / description

Added value: +"The clip to read or write. Omit it to list every clip's synopsis and which are missing one."

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

removedInput schema / properties / text / anyOf

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

addedInput schema / properties / text / description

Added value: +"What this footage **is** — the work, the scene, the people. A different fact from a `describe` window, which says what is in front of the camera. Write it yourself: nothing generates one, because a model reading the pixels measurably cannot."

removedInput schema / properties / text / title
```
Removed value: -"Text"
```

addedInput schema / properties / text / type

Added value: +[
+  "string",
+  "null"
+]

removedInput schema / title
```
Removed value: -"synopsisArguments"
```

First observedv0.24.0Sep 15, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already provide idempotentHint=true and destructiveHint=true (with readOnlyHint=false), and the description adds genuine value on top: omitting clip_id lists all clips' synopses, clip_id alone reads, text writes, clear removes. It also discloses the destructive nature of `clear` in plain terms and explains the expected agent behavior (write synopses, don't guess from filenames). No contradiction with annotations.

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 front-loaded: purpose and operational modes come in the first two short paragraphs, followed by the describe distinction and the write-it-yourself directive. The statistical anecdote (2 in 25 vs 13) is slightly tangential but earns partial keep by motivating why careful synopsis writing matters. A bit longer than strictly necessary, but every section serves the agent's decision to invoke and write well.

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?

For a four-optional-parameter multi-mode tool, the description covers all operation modes, the key sibling distinction, and the expected authoring behavior. An output schema exists so return values need not be spelled out, and annotations carry the safety profile. Minor omissions like error behavior for unknown clip_ids are acceptable given the annotation and schema richness.

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 coverage is 100%, so the baseline is 3, but the description adds the mode semantics that the schema does not: how to combine the four optional parameters to get list, read, write, or clear behavior (no clip_id → list; clip_id alone → read; text → write; clear → removes). It also reinforces the meaning of `text` as carrying what no camera can see, beyond the schema's wording.

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 line states a specific set of verbs (read, set, clear) on a specific resource (a clip's synopsis), defined as 'what a clip *is* — the corpus b-roll gets chosen from.' It explicitly differentiates itself from the sibling `describe` tool, telling the agent that a synopsis is a different fact from a describe window. An agent can immediately distinguish this from describe_ls and clip_role.

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 clearly draws the when-to-use line against `describe`: descriptions say what is in front of the camera, synopses say what the footage is and whether it belongs under a sentence. It also gives the operational rule 'write these yourself,' warning that nothing generates them. It does not enumerate other sibling alternatives, but the key exclusion (describe) is explicit and central.

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

Deploy Server