Integrates with FFmpeg to render frame-accurate cuts from talk recordings and verify the rendered output, including frames, audio, decode, and A/V sync at joins.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@rostrum init talk.mp4, then plan the cuts before I render"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Clean up talk recordings, from one video to a whole event, by hand or through your agent. rostrum finds redos, retakes, repeats and dead air, shows you every cut with its reason, then renders with ffmpeg and checks the result. Everything runs on your machine.
A 58-second synthetic demo talk. The terminal shows the real output, trimmed to the main lines.
Recording a talk in one take means restarting sentences, slides and clicks. Cutting those by hand takes hours, and one bad join ruins a clip. rostrum proposes each cut with the evidence behind it, you approve or adjust it, and it renders frame-accurate joins and then verifies sync at every join.
uv tool install rostrum
rostrum init talk.mp4pipx install rostrum works too.
You also need ffmpeg (winget install Gyan.FFmpeg, brew install ffmpeg, apt install ffmpeg).
init does the whole first pass:
probes the file (or files) and writes rostrum.json with defaults,
transcribes with a local speech engine (the first run downloads the model, about 480 MB),
finds cuts: spoken cues ("redo", "stop", "restart"), retakes, repeats, long pauses, dead air at the start and end, and garbled or untranscribed speech for you to listen to,
writes review.html, where you can play each join, flip keep/cut and nudge edges.
Nothing is cut before you see it.
rostrum plan lists every cut and the expected length.
render refuses until the cuts are reviewed: with rostrum decide, or by saving from the page
and importing that file. --yes skips that check.
The page saves <talk>-decisions.json. Importing it never undoes a newer decision: for each
cut, the newer one wins.
Sources are never modified and outputs are never overwritten.
rostrum plan # every cut, its reason, and the expected output length
rostrum decide <cut-id> keep # or: cut, with --start/--end to move its edges
rostrum decide --import talk-decisions.json # apply what you saved from review.html
rostrum render # frame-accurate render into <talk>.rostrum/renders/render-N/
rostrum verify --mode full # checks the newest render: frames, audio, decode, A/V sync at every join
rostrum map 23:30 --from render-1 # a time in the edited video -> the source timeBare rostrum shows the project status, and rostrum doctor checks your setup.
Related MCP server: free-video-edit-mcp
These numbers come from one 60-minute single-take talk, run on CPU only (8 cores, small.en):
Speed:
first pass: about 11 minutes;
render: about 4 minutes;
full verify: about 1.5 minutes.
Accuracy: against the speaker's final edit, cuts marked auto covered 69% of the removed
time, and 95% of what they removed was right to remove. Adding the proposals raised coverage to
90%. Review closes the rest of the gap, which is why it is the default.
When you fumble, say "redo" (or "stop", "restart"), pause for a second, and restart from the start of the sentence.
Restarting a slide or a click is fine: the bad attempt and your restart look like any other retake.
Keep recording. The fewer separate files, the easier the review; several files work as well.
rostrum init talk-part1.mp4 talk-part2.mp4 # one talk recorded in parts: one timeline, one output
rostrum init talks/ # one talk per file; *-part1/*-part2 files are groupedFiles join into one talk when their names end in -part1, -part2 and so on (_ or a space
works too; set init.partPattern to change it). Every other file is a talk of its own.
Parts are analyzed as one timeline, so a redo that starts at the end of one file and is said again in the next is still caught. An event shares one settings block (engine, cue words, render settings, loudness target, naming) and any talk can override any of it.
Settings are plain JSON in layers, where later wins:
built-in defaults;
~/.rostrum/config.json, your defaults;
rostrum.json, the event or talk file;
command-line flags.
Every threshold, word list, engine and render option is a key, and the published schema gives
your editor autocomplete. rostrum config prints the effective value of every key and where it
came from. See examples/rostrum.example.json.
{
"$schema": "https://raw.githubusercontent.com/girishkvs/rostrum/main/src/rostrum/schema/rostrum.schema.json",
"defaults": {
"cues": { "words": ["redo", "stop", "restart"] },
"pauses": { "maxSec": 2.0, "keepSec": 0.5 },
"render": { "crf": 18, "name": "{speaker}-{title}" }
},
"talks": [
{ "id": "keynote", "speaker": "Jane Doe", "title": "Keynote", "sources": ["part1.mp4", "part2.mp4"] }
]
}Each detector has a level:
auto: shown with cut pre-selected.
propose: shown with keep pre-selected.
off: not run.
Detector | Finds | Default |
Spoken cues | "redo", "stop", "restart"; cuts back to where you restarted | auto |
Retakes | a sentence said again soon after; "said again with a different word" is only proposed | auto when the match is strong, otherwise propose |
Repeats | "now, now", or a restarted phrase | propose |
Pauses | dead air over | auto |
Lead-in and lead-out | dead air at the start and end | auto |
Off-talk | "is this recording?" and similar asides | propose |
Unclear | garbled, hallucinated or untranscribed speech | propose |
Fillers | "um", "uh" | off |
Slide-aware checks from your deck are planned for 0.2.
Engine | Use |
| The default. Local, on CPU or GPU. |
| Any program that prints words JSON, SRT or VTT, such as whisper.cpp or a vendor CLI. |
| A transcript you already have. |
The command and import engines work without any extra setup. Third-party engines can register
through the rostrum.engines entry point, naming a rostrum.engines.SpeechEngine subclass; rostrum
builds it as Engine(settings, tools, report). Speech workers size themselves to your CPU and memory
(speech.workers: "auto"); set a number to override.
Defaults are English: the small.en model and the cue, filler and off-talk word lists. For
another language, set speech.model to a multilingual model such as small, set
speech.language, and replace the word lists.
Every command except mcp takes --json. rostrum mcp runs an MCP server over stdio; long steps run as jobs
that your agent polls.
One-step installs (the MCP server plus the agent skill):
Host | Install |
Claude Code |
|
Copilot CLI |
|
Gemini CLI |
|
Claude Desktop | Open |
Cursor |
|
Or add the server by hand. uvx runs the PyPI package, so there is nothing else to install:
Host | Add the server |
Copilot CLI |
|
Claude Code |
|
VS Code | MCP: Add Server, then Command (stdio), then |
Codex CLI |
|
Gemini CLI, Cursor |
|
The first start downloads rostrum's dependencies, which can take longer than a host waits for a
server to start. Run uvx rostrum doctor once first.
Then ask: "Clean up talk.mp4 and show me anything you're unsure about."
skills/rostrum/SKILL.md tells the agent the rules:
show the cuts before rendering;
ask about the uncertain ones;
import what you saved from the review page when you say so (import_decisions);
render only after you say so (the agent then passes confirmed).
mcp-pacemaker can host the server and keep it warm
across sessions. Add this entry to ~/.mcp-pacemaker/servers.json; pacemaker reloads the file when
it is saved:
{ "rostrum": { "command": "uvx", "args": ["rostrum", "mcp"] } }verify checksDuration: output length equals the kept time to within one frame.
Video: frames are continuous at a constant step.
Audio: packets are continuous, with no gaps or overlaps.
Decode: a full decode completes with no errors.
Joins: timestamps are continuous at every join.
A/V offset: measured against the source at the joins, sampled in fast mode and at every join in full mode.
Python 3.11+ and ffmpeg/ffprobe 6.1 or newer (CI runs 6.1 and 9.0). If they aren't on PATH, set
ROSTRUM_FFMPEG / ROSTRUM_FFPROBE, or defaults.tools.ffmpeg / defaults.tools.ffprobe in
rostrum.json.
Windows, macOS and Linux.
MIT
Transcribe recordings and find proposed cuts. paths are video files or folders. Files named like
talk-part1, talk-part2 are joined into one talk; every other file is a talk of its own. Writes rostrum.json in
project_dir. Long-running: returns a job id.
| Name | Required | Description | Default |
|---|---|---|---|
| paths | Yes | ||
| engine | No | ||
| project_dir | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to lean on, the description carries the full burden and does well, disclosing that it writes rostrum.json into project_dir, that it is long-running, and that it returns a job id — critical async/side-effect context. It omits re-run behavior (does it overwrite rostrum.json?), failure handling, and permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five short sentences, front-loaded with the core action and followed by the two facts an agent most needs (output file location, job id). Every sentence earns its place, though the joining rule could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no annotations and no output schema, the description covers the essentials: what it does, how inputs are grouped, where output lands, and that the call is asynchronous. The only real hole is the undocumented `engine` parameter and the format of rostrum.json.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains `paths` well (video files or folders, with talk-part1/talk-part2 joining rules) and implies project_dir is the output location, but the `engine` parameter is left completely undefined, leaving a real gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb-and-resource pair: 'Transcribe recordings and find proposed cuts.' That is clearly distinguishable from functional siblings such as plan, render, verify, and list_cuts. It falls short of a 5 only because it never names an alternative tool to route the agent away from.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: transcribe-then-cut suggests this is the entry point of the pipeline and that plan/render come later, but the description never says when to choose it or what must exist first. No exclusions or alternative tools are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record the user's decision for one cut: decision is "keep" or "cut"; start/end adjust its edges.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| talk | No | ||
| start | No | ||
| cut_id | Yes | ||
| project | No | ||
| decision | Yes | ||
| project_dir | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It labels the operation as a record/commit but says nothing about persistence, whether it overwrites a prior decision, how it interacts with plan/render, or what happens on failure. The only real behavioral content is the allowed decision values, which is thin for a state-mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with the core action front-loaded and no filler. It is terse rather than verbose, though the brevity is partly responsible for the missing semantics noted elsewhere.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage, the description addresses only 3 of 7 parameters and none of the lifecycle context. An agent would have to guess at cut_id, project_dir, project, and talk, making this inadequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 7 parameters, so the description must compensate and largely does not. It clarifies 'decision' (keep/cut) and that start/end adjust cut edges, but project_dir, cut_id, talk, and project are left entirely undocumented in both the schema and the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource pair: 'Record the user's decision for one cut'. Combined with the stated decision values, an agent can tell this is a per-cut decision commit operation. It doesn't differentiate itself from siblings such as import_decisions or list_cuts, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance, no mention of prerequisites (e.g. needing a plan or existing cuts first), and no routing to alternatives like import_decisions for bulk operations. Usage must be inferred entirely from the name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check ffmpeg, the speech engine, model cache, disk and memory.
| Name | Required | Description | Default |
|---|---|---|---|
| project_dir | No | . |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Check' hints at read-only, but the description never confirms it performs no mutations, whether it remediates problems, what permissions it needs, or how results are surfaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One tightly packed sentence with the scope front-loaded and no filler. It is efficient, though the terseness contributes to gaps captured in other dimensions rather than being a structural flaw.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and an undocumented parameter, the definition leaves too much open: what the check returns, whether failure output identifies which component broke, and how project_dir affects the scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'project_dir' has 0% schema description coverage and is not mentioned in the description at all. The agent must guess whether the check applies to the project directory, the FFmpeg binary location, or something else.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Check' plus an explicit enumeration of resources (ffmpeg, speech engine, model cache, disk, memory) makes clear this is an environment/dependency diagnostic. It does not, however, distinguish itself from siblings like 'status' or 'verify', which could plausibly overlap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to run this versus alternatives such as 'status' or 'verify'. The purpose implies troubleshooting, but nothing tells the agent the trigger condition or whether it belongs before a render or after a failure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a decisions file saved from review.html. For each cut the newer decision wins, so decisions made after the page was built are kept. The result says whether it counts as a review.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| talk | No | ||
| project | No | ||
| project_dir | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose real merge semantics (per-cut, newer decision wins, later decisions are kept) plus a hint about the result. It omits permissions, expected file format, error/failure behavior, and whether existing decisions can be overwritten, so it is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the purpose and followed by the key merge rule. No filler, though the trailing 'result says whether it counts as a review' clause is vague rather than informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter mutation/import tool with no annotations and no output schema, the description leaves major gaps: all four parameters are unexplained and return behavior is only hinted at. It conveys the core merge rule but is not complete enough to call the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 4 parameters, and the description never explains what `path`, `project_dir`, `talk`, or `project` mean. Only `path` is obliquely implied by the 'decisions file' phrasing; the scoping parameters are entirely undocumented, so the description fails to compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Apply a decisions file saved from review.html" gives a specific verb (apply) and resource (decisions file from review.html), which an agent can act on. It stops short of explicitly distinguishing this import path from the sibling `decide` tool, so it is clear but not fully differentiating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the mention of "saved from review.html" and "decisions made after the page was built" hints this runs after a review page exists, but there is no explicit when/when-not and no alternative sibling (e.g. `decide`) is named or contrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Progress and, when finished, the result of a long-running job.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that the tool returns progress while running and a result when finished, but omits whether it is read-only, idempotent, rate-limited, or what errors occur for invalid or expired job IDs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence with no filler and the key concept front-loaded. The comma-heavy 'and, when finished,' is slightly awkward but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no annotations or output schema, the description is under-specified. It does not say where to obtain job_id, how to interpret progress/result, or what happens on errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should explain the sole job_id parameter. It only implies the ID refers to a long-running job and gives no format, source, or example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the resource (a job) and what the tool returns (progress and final result), so the core purpose is clear. However, it does not distinguish itself from the sibling 'status' tool or explicitly name the action verb, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'of a long-running job' implies this tool is for monitoring asynchronous jobs, which is an implied usage context. But there is no explicit when-to-use guidance, no mention of alternatives like 'status' or 'analyze', and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All cut candidates with evidence, for one talk or all talks.
| Name | Required | Description | Default |
|---|---|---|---|
| talk | No | ||
| project | No | ||
| project_dir | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. 'With evidence' hints at the payload but nothing is said about permissions, read-only vs mutating behavior, pagination, or failure modes. For a tool with zero annotation coverage this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler or repetition. However, the brevity is partly under-specification rather than tight editing, which caps it below 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A three-parameter tool with no annotations, no output schema, and no parameter documentation is left almost entirely unexplained. The description would need to cover the meaning of project/project_dir and the shape of the 'evidence' payload to be adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across three parameters. The clause 'for one talk or all talks' loosely gestures at the 'talk' parameter (and its null-default behavior), but 'project' and the required 'project_dir' are completely unexplained in both schema and description, so the guidance needed to supply them is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (cut candidates) and its scope (one talk or all talks), and the implicit verb 'list' is unambiguous given the tool name. It does not differentiate itself from any sibling such as analyze or decide, but an agent can tell what it returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: you call it to see cut candidates, optionally narrowed to a talk. There is no statement of when to prefer this over analyze, plan, or decide, and no prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a time quoted from a rendered video (e.g. "23:30") to source time, or back with to="output". render_dir is a render folder, its cutmap.json, or a render name such as render-4. With a name, pass talk when more than one talk has a render of that name.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | source | |
| talk | No | ||
| time | Yes | ||
| project | No | ||
| render_dir | Yes | ||
| project_dir | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully explains accepted render_dir forms and the talk disambiguation rule, but it does not describe failure modes, permission requirements, output format, or what happens when the time is not present in the cutmap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loads the conversion purpose, and then gives focused usage details for render_dir and talk. There is little wasted text, though the formatting could be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with no annotations, no output schema, and 0% schema description coverage, the description covers the core conversion and render_dir/talk behavior. It remains incomplete because project and project_dir semantics are omitted and return behavior is not described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% with 6 parameters, so the description must compensate. It adds meaning for time, to, render_dir, and talk, including an example time format and the multiple-talks condition, but it does not explain project or project_dir, leaving key parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: converting a time from rendered video time to source time, or back when to="output". It is clear enough for an agent to know what the tool does, but it does not differentiate itself from any sibling tool, which is why it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the two conversion directions via to="output" and gives conditions for render_dir and talk, which implies usage. However, it does not explicitly say when to choose this tool over alternatives or what preconditions must hold beyond the render_dir/talk note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every cut per talk with reason, level, decision and the expected output length. Never renders.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | ||
| project_dir | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose two useful traits: the plan's per-cut content (reason, level, decision, expected output length) and that it performs no rendering. It does not say whether a plan file is written to disk, whether runs are idempotent, or what preconditions (analyze first?) exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is short and the distinguishing constraint ('Never renders') is placed where it will be read. But the telegraphic, verbless phrasing reads as truncated rather than economical—sentences were cut for length, not for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No annotations, no output schema, and 0% parameter coverage leave the description as the only information source, yet it omits the input semantics, the pipeline ordering relative to analyze/decide/render, and whether output is persisted. For a tool in a multi-stage pipeline with 10 siblings, that is a substantial shortfall.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for both parameters, and the description never mentions 'project' or 'project_dir' or how they differ. With 2 undocumented params and zero compensating description text, an agent cannot tell what project_dir points at or whether project is required alongside it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a noun-phrase fragment ('Every cut per talk with reason, level, decision and the expected output length') that conveys what the plan contains rather than stating a verb+resource. A reader can infer this produces a per-talk cut plan, and 'Never renders' does separate it from the render sibling, but the core action is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only guidance is the negative boundary 'Never renders,' which excludes one sibling but says nothing about when to call plan versus analyze, decide, or list_cuts. There are no prerequisites, ordering hints, or exclusions beyond that single phrase.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render the reviewed cut list with ffmpeg. Long-running: returns a job id. Set confirmed=true only after the user explicitly said to render; without it, rostrum refuses to render a talk whose cuts nobody has reviewed yet.
| Name | Required | Description | Default |
|---|---|---|---|
| talk | No | ||
| project | No | ||
| confirmed | No | ||
| project_dir | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does reasonably well: it discloses that the operation is long-running, that it returns a job id (async), and that it enforces a confirmed-review gate. It does not describe what artifact is produced (output file/path) or where the rendered result lands, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the action and the async contract, then the gating condition. No filler; the wording earns its place, though the confirmation rule could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an async job tool with no annotations or output schema, the definition covers the action and gating but not the follow-through: it never tells the agent to poll job_status for results, and with 0% schema coverage the three undocumented parameters remain unexplained. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% across 4 parameters, so the description must compensate. It explains only 'confirmed' meaningfully (the review gate), while talk, project, and the required project_dir are never described, leaving the required-path parameter completely opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb (render) plus the resource (the reviewed cut list), and even names the implementation (ffmpeg), which makes it distinguishable from siblings like analyze, plan, and verify. It stops short of explicitly contrasting itself with any named sibling, but the action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a concrete precondition: set confirmed=true only after the user explicitly said to render, and explains the consequence of omitting it (rostrum refuses unreviewed cuts). That is clear gating guidance, though it does not point to a sibling workflow (e.g., list_cuts or decide) that must precede rendering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summary of every talk in the project: stage, cut counts, expected output length.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | ||
| project_dir | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Summary' implies a read-only operation, but it never states that explicitly, nor does it mention cost, permissions, or whether it mutates or caches anything.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that lists the returned fields with no filler. It is appropriately sized, though it is concise at the expense of the guidance the tool needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does useful work by naming the return fields, but it leaves both parameters undocumented and does not distinguish this tool from 'job_status'. For a tool whose name is generic and whose sibling is near-identical, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for both parameters, and the description explains neither. It says nothing about what 'project_dir' expects or how the optional 'project' differs from the required 'project_dir', which is precisely the confusion the description should resolve.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete resource (every talk in the project) and enumerates the content returned: stage, cut counts, expected output length. That is clear enough to distinguish it from most siblings, but it offers no differentiation from the similarly named 'job_status' sibling, which is exactly the ambiguity an agent would need resolved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no preconditions, and no mention of alternatives. With 'job_status' in the sibling list, the agent is left to guess which status tool applies to which situation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a render: duration, frames, audio continuity, decode, A/V sync at joins. Without render_dir, checks the newest render of the talk. mode is "fast" or "full". Long-running: returns a job id.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | fast | |
| talk | No | ||
| project | No | ||
| render_dir | No | ||
| project_dir | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose some behavior: it is long-running, returns a job id (so it is async and pairs with job_status), and falls back to the newest render when render_dir is omitted. It does not say whether it mutates state, what permissions it needs, or how long 'long-running' is, so the disclosure is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the purpose and the list of checks, then adds scope and mode constraints. No filler sentences, though the multi-clause layout is slightly terse rather than seamlessly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No annotations and no output schema, with 5 params at 0% coverage, so the description must do more. It covers purpose, async behavior, and the key render_dir/mode semantics, but omits project/project_dir meaning and never tells the agent to follow up via job_status, leaving gaps for a long-running 5-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds real meaning for render_dir (absence selects the newest render) and mode (enumerates 'fast'/'full', which the schema does not), and implies which talk is targeted. However project and project_dir are entirely undocumented, so coverage is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Check a render') and enumerates the checks performed (duration, frames, audio continuity, decode, A/V sync at joins). An agent can distinguish it from render or analyze from the facet list, but the description never explicitly contrasts it with the closest-looking siblings (doctor, analyze, status).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a conditional behavior ('Without render_dir, checks the newest render of the talk') and names the two modes, which implies when to pick fast vs full, but it never says when to use verify over alternatives like doctor or analyze, nor states any prerequisites or exclusions. Usage must be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0analyzedecidedoctorimport_decisionsjob_statuslist_cutsmap_timeplanrenderstatusverifyScored across 11 tools
Most tools map to distinct pipeline stages: analyze, decide, render, verify, and map_time are clearly separate. The main ambiguity is between job_status and status, and to a lesser extent plan/list_cuts, though their descriptions clarify the intended use.
Names are readable and all use snake_case, but they mix bare verbs (analyze, plan, decide, render, verify), verb_noun patterns (list_cuts, import_decisions, map_time), and noun-style names (job_status, status, doctor). This is a mixed convention rather than a predictable pattern.
Eleven tools is well within a reasonable range for a video-analysis and rendering workflow. Each tool corresponds to a meaningful pipeline step rather than feeling redundant or padded.
The surface covers the core lifecycle: analysis, project status, cut inspection, decisions, rendering, verification, time mapping, and environment diagnostics. Minor gaps exist around project/talk management, such as listing or deleting projects, but core workflows are covered.
Orccut: a real timeline video editor for AI agents - journaled edits, FFmpeg/MLT rendering
Transcript-based audio editing: transcribe audio, edit by word ID, export edited audio.
FFmpeg as a service for AI agents: typed video editing tools, async jobs, downloadable outputs.
AI video editor for agents and humans: timeline, captions, color, audio and generation as MCP tools.
