video-sense

Overview Schema Source Related Servers Discussions Admin

video_next

Read-only

Waits for the next ordered saved frame from a local or network video job, letting you inspect early images while decoding continues instead of blocking until full completion.

Instructions

Wait for the NEXT ordered saved image of a local or network video job, not for full completion. after is the last viewed image index (-1 before any image). waitSeconds=20 is an upper bound; returns immediately when available. Inspect and comment on early images while decoding continues. Images are retained and never skipped; use video_sheet to re-read. newImage=false with a terminal status means no remaining image. overview coverage excludes unsampled gaps. Images default to format=jpeg (FFmpeg q:v4, 4:4:4); request format=png for original PNG detail. Encoding is cancellable with 2 active conversions per MCP process, at most 24 queued, a 30s queue deadline and a 10s execution deadline. Every image response is limited to 8MiB encoded bytes. Saved storyboard PNGs are retained. Acknowledge the pending batch before switching formats; replay preserves its original format and bytes.

The HOST chooses evidence depth from the user request and actual subtitle/ASR quality and coverage: text alone, selected storyboards, all storyboards, or targeted higher-quality follow-up. Subtitles, ASR and images are independently optional; choose any combination. For text-only media use audio_start/audio_url_start (audio-bearing video files/pages are accepted) without a visual job. No mandatory image retrieval, all-images rule, fixed answer format or mandatory ASR. Use video_review action=plan to record visual=none|selected|all; revise as evidence changes. Missing subtitles do NOT block usable images, and a video-only stream does not prove missing source audio. Each image response has a pending batch. Return images AND timestamp metadata to the model, inspect the chosen images, then call video_review action=ack with batchId and explicit viewedIndices (empty [] releases uninspected images without credit). ONLY THEN fetch another batch. Never accumulate many video_read calls inside one code/exec result: return control to the model after each bounded batch. Transport errors leave the batch pending: video_review replay retries it; status/reviewId support resume. Acknowledgement is a caller assertion, not proof of comprehension. Keep any semantic working notes in the Agent workspace, not in MCP evidence. Before finishing, video_review finish checks only the HOST-CHOSEN visual scope and pending image receipts, not text reading completion. The host must still judge if that scope answers the user, and state relevant gaps. Honest incomplete-work disclaimers do not justify abandoning feasible work. session_stop cleanup cancels processing but does not complete reading; user_cancelled is only for an explicit user cancellation. Audio-only workflows remain independent.

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": {
      "id": "<id>"
    },
    "name": "video_next"
  }
}

Input Schema

Name	Required	Description	Default
`id`	Yes
`after`	No
`format`	No
`waitSeconds`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.9.0Nov 5, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Goes well beyond the readOnly/non-destructive annotations: queue limits (2 active, 24 queued), 30s queue and 10s execution deadlines, 8MiB response cap, jpeg default at FFmpeg q:v4 4:4:4 vs png original detail, cancellation via session_stop, and the pending-batch/ack obligation. The 'newImage=false with a terminal status' rule and format-replay behavior are exactly the non-obvious traits an agent needs.

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

Conciseness2/5

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

The tool-specific content is front-loaded and clear, but the second half drifts into host orchestration policy — evidence depth selection, honesty disclaimers, session_stop vs user_cancelled, audio-only independence — that is not about invoking video_next. Roughly half the text does not earn its place in this tool's definition.

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?

With no output schema, the description does supply return semantics (images plus timestamp metadata, batchId, newImage, terminal status meaning no remaining image) plus error recovery, which is substantial for a streaming-style tool. It still leaves the exact response field shapes to be discovered at call time, but nothing needed to call it correctly 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 0%, so the description has to carry the load, and it largely does: 'after' is the last viewed image index with -1 before any image, 'waitSeconds=20 is an upper bound' that returns immediately when available, and 'format' default/quality tradeoffs are spelled out. The required 'id' job identifier is never described, which is the only meaningful gap.

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 a specific verb and resource — 'Wait for the NEXT ordered saved image of a local or network video job' — and immediately scopes it ('not for full completion'), which distinguishes it from a blocking completion wait and from re-readers like video_sheet. An agent can identify what this returns without opening the schema.

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

Usage Guidelines4/5

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

Guidance is explicit and actionable: call video_sheet to re-read retained images, call video_review action=ack before fetching another batch, use video_review replay after transport errors, and never loop many calls inside one exec block. It names alternatives and prerequisites, but the contrast with siblings like video_read and video_frame is only implied by context rather than stated directly.

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

Deploy Server