Skip to main content
Glama
Sign In

ChatCut

by io.chatcut
OverviewDiscussionsAdmin

manage_markers

Manage note markers on a timeline. Current contract: marker-note-v2. A marker is a point-or-range comment anchored to timeline frames — for example "fix audio dip here" or "this cut is too tight". Each marker has a frame position, optional duration, and one user-visible field: note.

Two marker scopes:

  • Ruler markers (default, scope:"project"): anchored at an absolute timeline frame. Stay where they are when clips move or get edited. Use for section labels, act breaks, timeline-level reminders.

  • Clip markers (scope:"item"): anchored to a specific clip via itemId. Travel with the clip across move, trim (either side), playback-rate change, split, and duplicate, staying glued to the same source moment. Use for clip-specific notes like "color grade this shot" or "tighten the cut here".

Use this tool to:

  • list: show note markers on the active timeline (both scopes), or on timelineId when provided.

  • get: fetch one marker by prefix id.

  • create: drop a note marker. Pass itemId to make it a clip marker; omit to make it a ruler marker. Defaults: durationFrames=0 (point). fromFrame is always in timeline-frame coordinates — the tool converts internally when itemId is set.

  • batch_create / bulk_create: drop multiple note markers in one call (each entry can target a different itemId or none).

  • update: change an existing marker's fromFrame, durationFrames, and/or note.

  • batch_update / bulk_update: update multiple existing markers in one call.

  • delete: remove an existing marker by prefix id, or several at once via markerIds (batch_delete / bulk_delete are aliases) — one call for the whole cleanup, never one call per marker.

  • transcript-backed notes: for exact transcript quotes, pass transcriptSegments plus optional notePrefix instead of free-text note. The tool copies transcript text and fills fromFrame from the first selected segment unless you pass fromFrame explicitly.

Choosing scope:

  • "mark this clip" / "note on this shot" / "remember to fix this take" → clip marker (set itemId from preview_timeline items).

  • "section header at 0:30" / "act break" / "TODO at frame X" → ruler marker (omit itemId).

  • When the user names or selects a specific clip, prefer clip marker.

Evidence-bound placements: when the user asks for a marker at a transcript/caption phrase, visual moment, current selection, or other evidence-derived location, create only after you have exact frame/timestamp evidence from the user or a current tool result. If lookup fails, report that no marker was placed; do not use frame 0 or any placeholder fallback unless the user explicitly asked for start-of-timeline.

Temporary/probe markers are still real project markers. If you create one for verification, delete it before optional work or the final answer; the delete result confirms removal.

By default markers are scoped to the active timeline. If the user names or identifies a non-active timeline, pass timelineId from manage_timelines list instead of switching active timelines. Results echo the target timeline and the resulting scope so you can verify placement without an extra list/read call. Only pass the schema fields for this tool: action, timelineId, fromFrame, itemId, optional durationFrames, markerId, markerIds, note, markers, updates, transcriptSegments, transcriptTrack, and notePrefix.

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": {
      "action": "<action>"
    },
    "name": "manage_markers"
  }
}

Input Schema

NameRequiredDescriptionDefault
noteNoMarker note text (required for create unless transcriptSegments is used)
actionYeslist, get, create, batch_create, bulk_create, update, batch_update, bulk_update, delete, batch_delete, or bulk_delete
itemIdNoOptional timeline item (clip) id or prefix. When set, creates/identifies a clip marker anchored to that clip instead of the timeline ruler. Use for notes that should travel with a clip across move/trim/split/duplicate. Omit for a ruler marker.
markersNoMarkers to create in one call (required for batch_create/bulk_create)
updatesNoMarkers to update in one call (required for batch_update/bulk_update)
markerIdNoTarget marker prefix id from action=list (required for get/update; delete takes this or markerIds)
fromFrameNoInteger timeline frame to anchor the marker at (required for create unless transcriptSegments is used). When itemId is set this is still the timeline frame — the tool converts internally so the marker stays glued to the clip's source content. For evidence-bound requests, do not use 0 as an unknown fallback.
markerIdsNoSeveral marker prefix ids to remove in one delete/batch_delete call. Use this instead of repeated single deletes.
projectIdNoProject for this call (full ID or unambiguous prefix). Explicit-timeline calls never change the target of later calls; legacy project selection applies otherwise.
notePrefixNoOptional label prefix when transcriptSegments derives the note body
timelineIdNoTimeline ID or prefix to target without switching active timelines. Use for non-active timeline marker work.
durationFramesNoDuration in frames (0 = point marker, default 0)
transcriptTrackNoTrack filter for transcriptSegments, e.g. V1 or A1
transcriptSegmentsNoActive Script segment ids/ranges from timeline.md, e.g. "3-4"; note text is copied from read_script output

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare the generic mutating/non-idempotent profile, so the description carries real weight and delivers: what delete removes, that the delete result confirms removal, that temporary probe markers must be cleaned up, that fromFrame is converted to source-relative storage when itemId is set, and that results echo target timeline plus scope so no read-back is needed. It also discloses the failure behavior (report that no marker was placed rather than falling back to frame 0), which is exactly the kind of operational context annotations cannot express.

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?

It is long but front-loaded and well partitioned (scope definitions, per-action usage, scope selection, placement rules, timeline targeting), which is appropriate for a 14-parameter multi-action tool. There is minor redundancy: the closing instruction to 'only pass the schema fields' plus the full field list restates the schema, and 'Current contract: marker-note-v2' earns very little.

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 and 14 parameters, the description still covers what a caller needs: action semantics, scope selection, coordinate conventions, transcript-derived note behavior, cross-timeline targeting via timelineId, and a description of what the response echoes. Nothing material for correct invocation is missing.

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 already 100%, so the baseline is 3; the description goes past it by explaining the semantic meaning of the scope switch (itemId present/absent defines clip vs. ruler), that fromFrame is always in timeline-frame coordinates even for clip markers, and that durationFrames=0 yields a point marker. Some of this material is repeated near-verbatim in the schema field descriptions, which keeps it from a 5.

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 states a concrete verb and resource ('Manage note markers on a timeline') and then defines the two marker scopes (ruler vs. clip) with anchoring behavior, which no sibling tool covers. A model can distinguish this from manage_timelines, edit_item, or edit_captions without opening the schema, because every action (list/get/create/update/delete plus batch variants) is enumerated with its effect.

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

Usage Guidelines5/5

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

It gives explicit routing rules: 'mark this clip' → clip marker with itemId from preview_timeline; 'section header at 0:30' → ruler marker; and prefer clip marker when the user selects a clip. It also names alternatives for adjacent needs (transcriptSegments instead of free-text note, delete with markerIds instead of repeated single deletes) and states a hard when-not rule about evidence-bound placements and placeholder frame 0.

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

All ChatCut toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources