ChatCut

preview_timeline

Read-onlyIdempotent

Preview timeline structure, composed viewer pixels, and bounded transcript. Returns facts, not quality judgments.

External MCP viewer note: viewer pixels require full projectId and timelineId UUIDs and a connected authenticated browser executor with access to the media. The visible page need not show that project or timeline. Browser failures do not fall back to cloud. Judge the sheet's pixels, not rendering metadata.

Browser execution requires the full timelineId UUID, never a shortened ID. Get it from editor state, read_project, or manage_timelines action="list". External calls also require full projectId; internal agents may omit it. Non-execution reads need no browser scope. Never switches the visible timeline or silently falls back to cloud.

Choose views:

timeline: tracks, placed items, gaps, layering, effects, transitions and markers.
viewer: exact frames or uniform samples (default 9, max 25). Batch 12-20 for an overview, then exact frames for detail. Samples prove only sampled moments; inspect adjacent entry/exit frames before judging cuts, fades or motion. Returns one labeled contact sheet with times/FPS; the Web agent also saves workspacePath.
transcript: non-muted audio/video text mapped through trim, source offset and playback rate, labeled by track/item/asset; coverage is complete, partial or unavailable.

views:["viewer"], viewerFrames and viewerFrameCount require browser scope; structure/transcript-only reads may omit timelineId. fromFrame/toFrame use half-open timeline frames; tracks filters timeline/transcript, itemIds excludes gaps/markers. Paginate with the same range/filters and offset/timelineId from "more:". Normalizations appear under "Adjusted:".

Use inspect_item for placed-item properties, read_script/apply_script for speech edits, inspect_asset for source media.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "preview_timeline"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Maximum timeline structure entries returned (default 50, max 100; larger values use 100).
`views`	No	One or more views: "timeline", "viewer", "transcript". Defaults to ["timeline"]. "viewer" requires the full timelineId UUID. viewerFrames/viewerFrameCount also include "viewer" without removing other views; offset, limit, itemIds, or tracks without a view they apply to also include "timeline".
`offset`	No	Zero-based timeline structure entry offset (default 0). For continuation, use offset and timelineId from the returned more: line, and keep the same range and filters.
`tracks`	No	Optional track aliases/ids (up to 10) for timeline and transcript views.
`itemIds`	No	Optional placed item ids/prefixes (up to 10). When present, the timeline view returns only matching item entries, transitions into or out of them, and effects attached to them; gaps and markers are omitted.
`toFrame`	No	Optional exclusive timeline end frame. Omit to use the timeline duration; a value past it uses the duration.
`fromFrame`	No	Optional inclusive timeline start frame. Omit to start at frame 0. A start at or after the timeline end returns an empty range with the timeline duration.
`projectId`	No	Full project UUID. Required for external browser work; internal agents may omit. Execution/explicit-timeline calls never change later calls' target.
`timelineId`	No	Full timeline UUID, never a shortened ID. Required with views:["viewer"], viewerFrames, or viewerFrameCount; optional for structure/transcript-only reads. Copy the full target ID from editor state, read_project, or manage_timelines action="list". Execution never switches the visible timeline.
`viewerFrames`	No	Requires the full timelineId UUID, including for "playhead". Requests viewer for these exact timeline frame numbers, or "playhead" when turn-start editor state is available. Renders the first 25 and returns the rest to request next. Frames outside the selected range are skipped and listed; the call fails only when none can be rendered. Takes precedence over viewerFrameCount.
`idempotencyKey`	No	Stable key for this browser execution. Reuse only with identical scope and parameters after a lost acknowledgement; applies only to this call.
`browserProfileId`	No	Optional browser profile override. Omit to select automatically; do not ask the user to choose.
`viewerFrameCount`	No	Requires the full timelineId UUID. Requests viewer and uniformly samples this many frames (default 9, max 25). Ignored when viewerFrames is present.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 5, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

First observedNov 5, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already establish read-only, idempotent, non-destructive behavior, but the description adds substantial context: viewer pixels require a connected authenticated browser executor with media access, browser failures do not fall back to cloud, the visible page need not match the requested target, and the call never switches the visible timeline. Coverage semantics (complete/partial/unavailable) and normalization reporting ('Adjusted:') are also disclosed. Some of this is repeated near-verbatim across sentences, which slightly dilutes the value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The three-view list is well structured and front-loaded, but the browser/UUID requirement is repeated at least three times ('viewer pixels require full projectId and timelineId UUIDs', 'Browser execution requires the full timelineId UUID, never a shortened ID', 'External calls also require full projectId'), and the 'never switches the visible timeline' constraint appears twice. Trimming that redundancy would make the definition noticeably tighter without losing information.

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

Completeness4/5

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

For a 13-parameter tool with no output schema, the description covers the essential ground: view selection, browser prerequisites, frame sampling limits (max 25 rendered), pagination continuation, and filter interactions. Return values are described only partially (a labeled contact sheet with times/FPS, workspacePath), so an agent lacks detail on the timeline and transcript payload shapes, though the 'facts not quality judgments' framing sets expectations.

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 description coverage is 100%, so the schema already documents each of the 13 parameters including the half-open fromFrame/toFrame semantics, viewerFrames precedence over viewerFrameCount, and pagination instructions. The description mostly restates these relationships rather than adding new meaning, which is the baseline case for full coverage.

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 names specific verbs and resources: timeline structure, composed viewer pixels, and bounded transcript, plus an explicit framing ('Returns facts, not quality judgments'). The three-view breakdown makes the tool's scope distinguishable from siblings like inspect_item and read_script, which are named as alternatives.

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?

Explicit routing rules are given for all three views (timeline for tracks/items/gaps/layering, viewer for exact frames or uniform samples, transcript for non-muted audio text) and the closing sentence redirects to inspect_item, read_script/apply_script, and inspect_asset for their respective jobs. It even advises a batching strategy (12-20 frames for overview, then exact frames for detail).

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

All ChatCut tools Inspect

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.