Skip to main content
Glama

Detect scene cuts

detect_scenes

Finds hard cuts and large visual changes in local videos, listing each scene's start, end, and length; optionally exports a contact sheet and CSV for edit logs, pacing counts, or shot lists.

Instructions

Find hard cuts and big visual changes, and list every scene with start, end and length — for logging an edit, counting cuts (pacing), pulling a shot list from a reference video, or splitting a montage. Optionally returns a contact sheet of the first frame of each scene and writes CSV.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "path": "<path>"
    },
    "name": "detect_scenes"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoOnly look up to this time.
pathYesAbsolute path to a local video file. ~ is expanded.
startNoOnly look from this time on.
max_rowsNo
overwriteNo
thresholdNoScene-change sensitivity: lower finds more cuts (0.2 catches soft cuts, 0.4 only hard ones).
include_sheetNoReturn a contact sheet of each scene's first frame (up to 30).
csv_output_pathNo
min_scene_secondsNoIgnore cuts closer together than this (flash frames, strobes).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A3.6/5.0
Behavior3/5

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

Annotations declare readOnlyHint=false and destructiveHint=false; the description corroborates by disclosing the optional CSV write and the contact-sheet side output, plus the 30-frame cap on the sheet. It does not explain what happens when the CSV path already exists (the undocumented overwrite flag), where CSV lands by default, or whether results are truncated by max_rows.

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?

A single front-loaded sentence gives the operation, the returned fields, and the use cases with almost no filler. The clause structure is dense but the core action is stated first, so an agent can stop reading after the opening phrase.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter tool with no output schema, the description covers output shape (start/end/length list plus optional contact sheet) reasonably well. It omits the write-related behavior (overwrite, default CSV destination) and the effect of max_rows, which an agent needs before calling on long videos.

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 67%, so several parameters are already documented (threshold, min_scene_seconds, include_sheet, start/end, path). The description adds interpretation for include_sheet and csv_output_path, but leaves max_rows, overwrite, and csv_output_path semantics (default location, truncation, overwrite requirement) unexplained in both schema and prose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — detecting hard cuts/big visual changes and listing scenes with start, end, and length — which an agent can map to a concrete operation. It clearly differs from frame-sampling siblings like sample_frames or grab_frame because the output is a scene list with timing, though it never names those siblings explicitly.

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?

Offers four concrete when-to-use scenarios (logging an edit, counting cuts for pacing, pulling a shot list, splitting a montage), which is more guidance than most tools provide. It stops short of naming alternatives or exclusions — e.g., when to use sample_frames or contact_sheet instead — so an agent still has to infer the boundary.

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