Skip to main content
Glama
tydude001

proofcut

by tydude001
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

spot_frames

Read-onlyIdempotent

Sample a render at evenly spaced intervals, returning PNG frames ranked darkest-first, plus optional explicit times and a montage overview.

Instructions

Pull count evenly-spaced frames (plus any explicit times) from a render as PNGs with signalstats luma, ranked darkest-first.

When target's own probed duration still matches the current timeline within a frame (mapping_trusted), each frame also reports which clip/word it lands near via Edit.source_at — refused, not guessed, when the render looks stale.

Like shot_sheet/footage_sheet/contact_sheet, the reply also carries a montage of the sampled frames as an image — frames[].png is a path, and an agent confined to proofcut's tools (the agent panel's --tools ToolSearch) has no Read to open one (TRIAL.md § spot_frames hands back paths the agent cannot open).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
fpsNoThe rate used to map a frame back to the clip and word it lands near — refused rather than guessed when the render's duration no longer matches the timeline.
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.
countNoHow many evenly-spaced frames to pull. They come back ranked darkest-first, with a montage of them as an image.
timesNoExplicit seconds to sample as well as the evenly-spaced ones.
targetYesThe render to pull frames from.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed18 schema fields changedv0.25.0
    • addedInput schema / properties / count / description
      Added value: +"How many evenly-spaced frames to pull. They come back ranked darkest-first, with a montage of them as an image."
    • removedInput schema / properties / count / title
      Removed value: -"Count"
    • removedInput schema / properties / fps / anyOf
      Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedInput schema / properties / fps / description
      Added value: +"The rate used to map a frame back to the clip and word it lands near — refused rather than guessed when the render's duration no longer matches the timeline."
    • removedInput schema / properties / fps / title
      Removed value: -"Fps"
    • addedInput schema / properties / fps / type
      Added value: +[
+  "number",
+  "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"
+]
    • addedInput schema / properties / target / description
      Added value: +"The render to pull frames from."
    • removedInput schema / properties / target / title
      Removed value: -"Target"
    • removedInput schema / properties / times / anyOf
      Removed value: -[
-  {
-    "items": {
-      "type": "number"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedInput schema / properties / times / description
      Added value: +"Explicit seconds to sample as well as the evenly-spaced ones."
    • addedInput schema / properties / times / items
      Added value: +{
+  "type": "number"
+}
    • removedInput schema / properties / times / title
      Removed value: -"Times"
    • addedInput schema / properties / times / type
      Added value: +[
+  "array",
+  "null"
+]
    • removedInput schema / title
      Removed value: -"spot_framesArguments"
  2. First observedv0.24.0

TDQS

A4.2/5.0
Behavior5/5

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

Beyond the readOnly/idempotent/non-destructive annotations, the description adds crucial behavioral detail: mapping is refused rather than guessed when the render is stale, and the returned PNG paths cannot be opened by an agent limited to proofcut tools. This significantly improves an agent's ability to predict tool behavior.

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 dense but each sentence earns its place: core operation, trust/mapping behavior, and output/agent-access limitation. It is longer than minimal, but that length is justified by genuinely useful caveats; the first sentence front-loads the primary action.

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?

With no output schema, the description compensates by explaining the key return aspects: PNG frames, montage, darkest-first ranking, and per-frame source mapping. It also warns about the agent's inability to open returned paths, which is critical context for a proofcut-bound agent. Inputs, outputs, and edge-case behavior are all covered.

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 coverage is 100%, so the schema already documents all five parameters thoroughly. The description reuses `count`, `times`, and `target` but does not add much meaning beyond what the parameter descriptions already provide; the baseline of 3 is appropriate.

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, concrete operation: pull `count` evenly-spaced frames (plus `times`) from a render as PNGs with signalstats luma, ranked darkest-first. This clearly identifies the tool's resource and behavior, and the sibling references (shot_sheet/footage_sheet/contact_sheet) place it in a family without obscuring its distinct purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description signals that it belongs with sheet-like tools by naming shot_sheet/footage_sheet/contact_sheet, but it never states when an agent should choose spot_frames over those siblings. The mapping_trusted caveat describes behavior, not selection criteria, so usage guidance is implied rather than explicit.

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