Skip to main content
Glama
tydude001

proofcut

by tydude001
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

contact_sheet

Read-onlyIdempotent

Generate a contact sheet of a clip's first seconds to preview its head before cueing anything. Uses cached thumbnails to show labeled frames, helping avoid cueing to black or unwanted credits.

Instructions

Look at a clip's own head — the first look, as an image.

The sheet to call before cueing anything to a clip you have not seen. Two shots of the film were cued to a clip's own head and got 4.5s of "BASED ON THE NOVEL BY THOMAS HARRIS" over black, because nobody had looked at its first seconds. Ten seconds at 1.5s spacing by default, each tile labelled with the source second it is.

The frames come from thumbnail()'s cache — no new cache location, no new manifest key, no new web route — and the montage of them comes back here as bytes, since an agent confined to proofcut's tools (the agent panel's --tools ToolSearch) cannot open a path. import_media makes the frames for every clip it registers, so this is usually a cache hit; call it to see them, to look further than ten seconds, or to redraw after a re-import.

An audio-only clip returns frames: [] and no sheet, not a refusal — the same "nothing to look at is not a failure" as check_frames. A box without magick returns the frames and a sheet_error.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathNoThe 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_idYesThe clip whose head to look at.
secondsNoHow much of the head to cover, in seconds. Ten by default — long enough to catch credits, black or a slate before anything is cued to the clip.
intervalNoSeconds between tiles.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv0.25.0
    • addedInput schema / properties / clip_id / description
      Added value: +"The clip whose head to look at."
    • removedInput schema / properties / clip_id / title
      Removed value: -"Clip Id"
    • addedInput schema / properties / interval / description
      Added value: +"Seconds between tiles."
    • 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"
+]
    • addedInput schema / properties / seconds / description
      Added value: +"How much of the head to cover, in seconds. Ten by default — long enough to catch credits, black or a slate before anything is cued to the clip."
    • removedInput schema / properties / seconds / title
      Removed value: -"Seconds"
    • removedInput schema / title
      Removed value: -"contact_sheetArguments"
  2. First observedv0.24.0

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already cover read-only/idempotent safety, but the description adds valuable edge-case behavior: returns bytes rather than a path, audio-only clips yield frames:[] without refusal, and boxes without magick return a sheet_error. It also discloses the cache origin (thumbnail()) and that no new cache/manifest/route is created.

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 longer than average but front-loaded with a bolded purpose, and all parts serve a function: the anecdote illustrates the failure mode, and the middle paragraphs explain cache/bytes and edge cases. It could be tightened, but it's structured and not bloated.

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?

Without an output schema, the description must explain return behavior, and it does: montage as bytes, audio-only returns empty frames, and missing magick yields sheet_error. It also covers integration with import_media and thumbnail cache, which is enough for an agent to invoke it 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?

Input schema covers all four parameters with detailed descriptions, so baseline is 3. The tool description restates defaults ('Ten seconds at 1.5s spacing by default') but adds little meaning beyond that; no parameter is explained more deeply than the schema already does.

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 specific verb and resource: 'Look at a clip's own head — the first look, as an image.' It also brands it as 'The sheet to call before cueing anything to a clip you have not seen,' which clearly differentiates it from sibling tools like thumbnail or check_frames by its role in the workflow.

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 explicit when-to-use guidance: 'The sheet to call before cueing anything to a clip you have not seen' and 'call it to see them, to look further than ten seconds, or to redraw after a re-import.' It does not explicitly name alternatives or list when-not-to-use, but the context is clear enough for an agent to decide.

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

Deploy Server

Other Tools