ChatCut

read_captions

Read-onlyIdempotent

Start caption/subtitle tweaks here, then use edit_captions for wording, grouping, emphasis, presets, style, layout or translation. Read saved topology-v2 caption tracks and their native items, never raw ASR or a freshly generated plan. On a legacy/v1 timeline this tool rejects without reading caption contents or changing data: call edit_captions {"action":"refresh"} first to convert its SAVED captions to v2, then read again. No legacy Program/Cue fallback or implicit migration exists.

Returns topologyVersion:2, timelineId, inputRevision, revision, global CC settings, compact tracks, captionTrackSummary, availableSources and paginated items/renderedItems. Each item owns exactly one caption trackId. captionTrackSummary labels C1/C2 identify caption tracks; availableSources labels V1/A1 identify MEDIA tracks and list their real ids, itemIds and assetIds. Do not use a media source id as a caption track id. Source-less/manual items have binding:null and never auto-bind.

items contain id (also the cardId for high-level edits), trackId, from, durationInFrames and data:{lines,appearanceOverride,authoredFields,binding,hidden,...}. Lines include timed tokens; token.from is relative to its Card, while Card from/duration are absolute timeline frames. Negative saved token offsets are valid. renderedItems contain effective inherited appearance and geometry, not duplicate text/tokens. All projections omit renderer source, renderer property definitions and track reconciliation internals. Renderer flags indicate omitted code; inspect it explicitly with edit_captions {action:"renderer",cardId:"..."} or sourceId for a track. Original and translated tracks have independent text, pagination, appearance and visibility, linked to the same source media clocks; translated word timing is aligned/estimated, not measured speech.

Use the returned revision for Card edits and batch; every successful edit returns the next revision. Call edits sequentially. Native edits include edit_captions set_card_text, set_card_style, set_card_layout, set_card_span_style, set_card_tokens, split_card and merge_cards. Track-wide style/layout/template select the caption trackId. To move a Card use track_items {operation:"move",itemIds:[""],trackId:""}; to delete a caption track use {operation:"delete-track",trackId:"..."}. Use create-track/update-track/create-item/update-item instead of full upserts: these compact read projections are not complete storage rows.

To add requested languages, use edit_captions translate {languageCode:"zh",mode:"bilingual"}, then translate {languageCode:"ja",mode:"bilingual"}. Each call preserves the original and existing language tracks. If the original already is one requested language, keep it and translate only missing languages rather than adding a duplicate. Do not fabricate translated rows. Use set_card_text for caption wording/spelling and template to discover published ordinary/animated presets. Caption edits do not require changing shared source transcription.

Reads are bounded to 32,000 UTF-8 bytes and paginated by caption item in timeline order. limit defaults to 50 (maximum 100); the byte budget may return fewer complete Cards. Continue using nextOffset plus the returned revision, not offset+limit. Text and timing are never silently truncated. Use words:true only when resolved word details are needed. cardId selects one exact id or unambiguous prefix. atFrame selects Cards covering that exact frame; fromFrame/toFrame use a half-open range. Reading never starts transcription, generation, translation, reconciliation or migration.

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

Input Schema

Name	Required	Description
`json`	No	Optional JSON: {"cardId":"<native item id>","words":true}, {"atFrame":4806}, {"fromFrame":4806,"toFrame":4830}, or {"limit":50,"offset":50,"revision":"..."}. Native item/token ids and frame ranges are returned directly; legacy Program ids are not accepted.
`projectId`	No	Project for this call (full ID or unambiguous prefix). Explicit-timeline calls never change the target of later calls; legacy project selection applies otherwise.
`timelineId`	No

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.7/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses hard behavioral facts: the v1 rejection path reads no caption contents and changes no data, there is no implicit migration, the byte budget is 32,000 and may return fewer complete Cards, text/timing are never silently truncated, and reading never triggers transcription/generation/translation. It also flags that renderer internals are omitted and must be inspected via edit_captions renderer.

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?

Purpose is front-loaded, but the remainder is one undifferentiated ~500-word block that interleaves return-shape documentation, id-namespace warnings, edit guidance, translation workflow, pagination rules and renderer flags with no headers or bullets. Most sentences carry information, yet the density makes it hard to scan and invites misreading of which clause governs which operation.

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 accepts the burden and describes the return surface in detail: topologyVersion, timelineId, revision, global CC settings, tracks, captionTrackSummary, availableSources, items versus renderedItems, and the Card-relative vs absolute frame distinction for tokens. It also warns against using a media source id as a caption track id and explains binding:null for manual items, which is exactly the trap this tool's return shape creates.

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 67% and the json blob is loosely typed, so the description carries real weight: it fixes limit default 50 / max 100, mandates continuing with nextOffset plus the returned revision rather than offset+limit, and defines atFrame (covering frame) vs fromFrame/toFrame (half-open) and cardId as exact id or unambiguous prefix. It stops short of enumerating every accepted json key in one place, leaving some assembly work against the schema example strings.

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?

States a specific verb+resource: "Read saved topology-v2 caption tracks and their native items," and explicitly excludes what it is not (raw ASR, a freshly generated plan, legacy Program/Cue fallback). It also positions itself against the sibling edit_captions, so an agent can separate read from write without opening either 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 entry/exit routing: start here then use edit_captions for wording/style/layout/translation; on a v1 timeline the call rejects and you must run edit_captions {action:"refresh"} first; move Cards via track_items move; delete tracks via delete-track; prefer create-track/update-track over upserts. It also spells out the multi-language translation sequence and the no-duplicate rule when the original already matches a requested language.

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.