ChatCut

edit_item

Add, update, or delete timeline items: video (incl. B-roll), audio, image, gif, svg, motion-graphic, and attached effect / transition items. Pass one or more of adds, updates, deletes; each parameter description lists its entry fields. The batch commits atomically and one invalid entry rolls back all of it, so bundle related ops (delete+add swap, update+add reposition, chained alignTo:"track-end" splices) in one call.

Placement

Preserve existing positions by default. Use ripple:true when the intent is to insert, make room, shift later items, or close gaps; do not use it merely because an overlap happened. "Move to 5s" alone is not ripple.
Omit trackId to let auto-placement pick a non-overlapping track (V1 is the back layer). If the user names an exact track and the range overlaps, do not silently move other items: ask, or compare options with validateOnly:true (a dry run; never with ripple).
Items on a non-active timeline need timelineId on each entry.
Effects, transitions, and fromItemId must reference committed items: add a clip first, then attach to the id the result returns.

Units

Timeline start and length are integer frames (fromFrame, durationInFrames) or time strings (from:"5s", duration:"3s"). sourceStartFromInSeconds and every fade are seconds, not frames. decibelAdjustment is dB (0 unchanged, -60 silent); volume / audioVolume are 0–1 linear only. Layout is canvas pixels, and visual items keep their source aspect ratio: use fit, or pass only one of width/height.

Other tools

Which spoken words, sentences, or takes play → Script (read_script → edit timeline.md → apply_script).
Do not use edit_item for captions: they are not items. Use edit_captions / read_captions.
Title cards, backgrounds, color mattes → opaque Motion Graphics; existing legacy solid and text items can only be deleted. MG templates → manage_template action:"apply". Music ducking → edit_track roles.

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": "edit_item"
  }
}

Input Schema

Name	Required	Description
`adds`	No	Items, effects, and transitions to create. Entry: type ("video"\|"audio"\|"image"\|"gif"\|"svg"\|"motion-graphic"\|"effect"\|"transition") + assetId, or fromItemId to duplicate a committed item. Asset type must match: a video with embedded audio stays type "video". Start: fromFrame (integer frame) or from ("5s"), or alignTo:"track-end"\|"timeline-end"; optional trackId ("V1", "A1"). Length: durationInFrames, or duration as a time string ("3s"), never a bare number; required for image/gif/svg, otherwise the asset length. Source trim (video/audio/gif): sourceStartFromInSeconds, seconds into the source; the range must stay inside the asset and its end follows from the length (no startFrame, trimIn, or sourceRange). Layout (visual): left/top/width/height or right/bottom insets, in canvas pixels, one anchor per axis; fit:"cover"\|"contain" fits the source into that box (or the canvas), derives crop* from the full source frame and replaces any crop; cropTop/cropBottom/cropLeft/cropRight 0–1 for a manual crop without fit; opacity 0–1; rotation in degrees; borderRadius. Width/height are aspect-locked: pass both only with fit, otherwise pass one. There is no scale, end-position, or layout-effect field; split screen and picture-in-picture are boxes on each item. Audio: decibelAdjustment in dB (-60 mutes); playbackRate (audio/gif/video). Fades are seconds, not frames: fadeIn/fadeOut (opacity; volume on audio-only items), audioFadeIn/audioFadeOut (volume). A 60-frame fade at 30fps is audioFadeOut:2 or audioFadeOutDurationInFrames:60, never audioFadeOut:60. Effect on a clip: {type:"effect", assetId, targetItemId} (not motion-graphic), optional fromFrame/durationInFrames for part of it; on a track range: {type:"effect", assetId, trackId, fromFrame, durationInFrames}. LUT effects take propertyOverrides {intensity:0–1}. Transition: {type:"transition", assetId:"builtin:tr-cross-dissolve" or another builtin:tr-* id, outgoingItemId, incomingItemId, durationInFrames}; both clips need source beyond the cut, and it replaces a same-kind transition on that seam.
`json`	No	Legacy JSON string wrapper for adds/updates/deletes; pass those parameters directly instead.
`ripple`	No	Shift later items to insert, make room, or close gaps.
`deletes`	No	Items to delete: [{id}], or {id, type:"effect"\|"transition"} for attached items; add timelineId for a non-active timeline. Transitions attached to a deleted item are deleted with it.
`updates`	No	Existing items, effects, and transitions to change. Entry: id (prefix from preview_timeline) plus only the changed fields. Timeline: fromFrame, fromDeltaFrames, trackId (omit to keep the track, or to let only this item move off an overlap), durationInFrames, sourceStartFromInSeconds. Layout, audio, and fade fields as in adds; volume/audioVolume are 0–1 linear aliases only. Motion Graphic propertyOverrides merge per key (null removes a key, propertyOverrides:null clears all); find keys with inspect_item. type, assetId, and fromItemId are immutable: swap media with deletes + adds and carry over the timing and layout to keep. Shortening an MG item cuts its animation; regenerate the MG for a new length.
`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, not a prefix. Required for browser work, even unplaced assets. Get it from read_project or manage_timelines action="list". Never switches visible timeline.
`validateOnly`	No	Dry run: validate and plan without committing. Not with ripple.
`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.

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

Behavior2/5

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

The description adds a lot beyond annotations: atomic batch commit with full rollback on one invalid entry, ripple shifting of later items, unit conventions (frames vs seconds vs dB vs 0-1 linear), and the requirement that effects/transitions reference already-committed items. However, it states the tool 'delete[s]' items and closes timeline gaps, which conflicts with the supplied destructiveHint=false, so the described side-effect profile does not match the declared one.

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?

Long, but front-loaded with the core capability, then split into scannable Placement / Units / Other tools sections, so an agent can stop reading once it has what it needs. A few sentences are dense run-ons (the adds entry description) and the placement/units material is anchored to parameters rather than left purely prose-style.

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?

For a 10-parameter mutation tool with no output schema, the description covers everything an agent needs to call it safely: batching/atomicity, ripple semantics, placement rules, unit conventions, ID provenance (committed-item ids from the prior result, prefixes from preview_timeline), and dry-run behavior. Return values are the only omission, and the delete/attach flows reference ids returned by the result.

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, but the description supplies semantic distinctions the schema cannot convey cheaply: integer frames vs time strings, seconds for fades and sourceStartFromInSeconds, dB vs linear volume aliases, and aspect-locked width/height that may only be paired with fit. It also clarifies omission semantics (trackId omitted = auto-place) and immutability (type/assetId/fromItemId).

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?

Opens with a precise verb set and resource: 'Add, update, or delete timeline items' followed by the exact item types covered (video, audio, image, gif, svg, motion-graphic, effect, transition). It also explicitly disambiguates from siblings (captions, script, motion-graphic templates, tracks), so an agent can route correctly without opening any schema.

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?

Gives explicit when-to/when-not-to guidance for the riskiest decision points: ripple:true is for inserting/closing gaps, not for overlap repair; omit trackId to auto-place; ask or use validateOnly instead of silently moving other items. It also names the alternative tools per intent (read_script/apply_script, edit_captions, manage_template, edit_track) with the boundary condition for each.

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