video-sense

Overview Schema Source Related Servers Discussions Admin

video_evidence

Read-only

Retrieve image frames and intersecting source text for a specified video time range, with pagination controls for sheets and text tracks.

Instructions

Read evidence for finite source-second interval [start,end): actual image content blocks plus frame references and intersecting source text. imageLimit 0..12 (default2); afterSheet is the next zero-based saved-sheet offset, nextSheet continues pagination. textLimit 1..500 applies per text track; use transcript_read for remaining text pages. A returned sheet can include other frames; frames lists only those in the requested interval. Time intersections are mechanical, never semantic/cause judgments. Frame times use output sampling-grid estimates, NOT exact original PTS. Visual overview gaps remain gaps even when text covers them. Use image tools to actually inspect pictures. 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>",
      "start": "<start>",
      "end": "<end>"
    },
    "name": "video_evidence"
  }
}

Input Schema

Name	Required	Description	Default
`id`	Yes
`end`	Yes
`start`	Yes
`format`	No
`textLimit`	No
`afterSheet`	No
`imageLimit`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.9.0Nov 5, 2026

TDQS

A4/5.0

Behavior5/5

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

The description goes well beyond the readOnly/destructive/idempotent annotations, disclosing encoding concurrency (2 active conversions, at most 24 queued), a 30s queue deadline and 10s execution deadline, an 8MiB cap per image response, cancellation behavior, and storyboard PNG retention. It also flags non-obvious semantics: frame times are sampling-grid estimates rather than exact PTS, time intersections are mechanical, and visual gaps remain gaps even when text covers them.

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 text is a dense wall that front-loads parameter trivia and workflow policy while burying the essential invocation contract. Many sentences belong to the video_review or session lifecycle descriptions (batch acknowledgement, finish checks, host scope decisions, session_stop cleanup) and are long, compound, and repetitive ('Acknowledge the pending batch before switching formats' recurs in spirit several times). It is informative but poorly structured and hard to scan.

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 7-parameter, no-output-schema, read-only-evidence tool, the description is unusually complete: it explains what comes back (image blocks, frame references, intersecting text, saved sheets, pending batchId), how pagination works, and how acknowledgement interlocks with the next fetch. The remaining gap is the unexplained 'id' parameter and the slightly tangled relationship between afterSheet/nextSheet pagination and the batch-ack cycle.

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 description coverage is 0%, so the description carries the full burden and mostly meets it: imageLimit 0..12 default 2, textLimit 1..500 per text track, afterSheet as the next zero-based saved-sheet offset with nextSheet continuing pagination, and format defaulting to jpeg with png for original detail. The uuid 'id' parameter is never explained, and start/end are only implied by the '[start,end)' notation, leaving one gap in an otherwise strong compensation for the missing schema docs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a concrete verb and resource: 'Read evidence for finite source-second interval [start,end): actual image content blocks plus frame references and intersecting source text.' That is specific enough to distinguish the tool's core job. However, it never explicitly frames the boundary against siblings like video_read, video_frame, video_sheet or video_next, which occupy adjacent space, so an agent must infer the split.

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?

There is substantial usage guidance: 'use transcript_read for remaining text pages', 'Use image tools to actually inspect pictures', 'For text-only media use audio_start/audio_url_start ... without a visual job', and the plan/ack/finish workflow via video_review. What is missing is a crisp statement of when to pick video_evidence over video_read or video_sheet; the alternates appear only incidentally inside operational warnings rather than as a selection rule.

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

Deploy Server