proofcut

Overview Schema Source Related Servers Discussions Admin

thumbnail

Read-onlyIdempotent

Extracts a video frame from a clip at a requested time, snapping to a set interval and caching it for repeated requests. Returns a local path that the proofcut web server serves as an image.

Instructions

One filmstrip frame for clip_id, at the source time nearest at.

at snaps to a multiple of interval before anything is extracted, and the frame is cached under cache/thumbs/ keyed by the clip's media size and mtime — a repeated ask for a nearby instant is a cache hit. The result is a path, not the image bytes; proofcut web serves those over /api/thumb/<clip_id>?at=. It never enters the manifest, so nothing that renders can reach it (the same wall the preview proxy has).

Input Schema

TableJSON Schema

Name	Required	Description
`at`	Yes	Source seconds to pull the frame at. It snaps to a multiple of `interval` first, so a repeated ask for a nearby instant is a cache hit.
`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.
`clip_id`	Yes	The clip to pull a frame from.
`interval`	No	The grid `at` snaps to, in seconds.

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

addedInput schema / properties / at / description

Added value: +"Source seconds to pull the frame at. It snaps to a multiple of `interval` first, so a repeated ask for a nearby instant is a cache hit."

removedInput schema / properties / at / title
```
Removed value: -"At"
```
addedInput schema / properties / clip_id / description
```
Added value: +"The clip to pull a frame from."
```
removedInput schema / properties / clip_id / title
```
Removed value: -"Clip Id"
```
addedInput schema / properties / interval / description
```
Added value: +"The grid `at` snaps to, in seconds."
```
removedInput schema / properties / interval / title
```
Removed value: -"Interval"
```

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: -"thumbnailArguments"
```

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 the tool read-only and idempotent. The description adds substantial behavior beyond that: `at` snapping, cache keys based on media size and mtime, cache-hit semantics, path output, and isolation from the manifest. There is no contradiction with the 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?

Purpose is front-loaded and the cache/output caveats are tightly written. The closing simile about the preview proxy is useful context but is the least essential sentence.

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 read-only retrieval tool with a rich output schema and fully documented parameters, the description covers the return contract (a path, not bytes), caching behavior, and render isolation. Nothing an agent needs to invoke it correctly is missing.

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 has 100% description coverage for all four parameters, including the `at` snapping and `path` binding behavior. The description repeats the snapping behavior but adds little new parameter-level meaning beyond what the schema already documents.

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 sentence identifies the exact resource and operation: a filmstrip frame for `clip_id` at source time `at`. It is clearly distinguished from render/manifest tools by stating the result is a path and that it never enters the manifest.

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 gives clear operational context: it returns a cached path, and the actual bytes are served by `proofcut web` via a specific endpoint. It doesn't explicitly name alternative sibling tools, but the manifest exclusion and web-serving note provide a useful boundary for when this tool is appropriate.

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

Deploy Server