video-sense

Overview Schema Source Related Servers Discussions Admin

video_sheet

Read-only

Reads one saved storyboard by zero-based index, returning images and timestamp metadata for frame inspection before describing contents. Re-reading does not advance a cursor.

Instructions

Read one saved storyboard and timestamp metadata, with zero-based index. View each image before describing its contents; frames in a sheet are numbered 1..n. Re-read safely; this does not advance a cursor. 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>",
      "index": "<index>"
    },
    "name": "video_sheet"
  }
}

Input Schema

Name	Required	Description	Default
`id`	Yes
`index`	Yes
`format`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.9.0Nov 5, 2026

TDQS

A3.9/5.0

Behavior5/5

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

Beyond the supplied read-only annotations, the description discloses format defaults and quality tradeoffs, cancellable encoding limits, queue and execution deadlines, an 8MiB response cap, retention behavior, pending-batch semantics, replay behavior, and acknowledgement meaning. This is unusually rich behavioral context for safe invocation.

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 first sentence is front-loaded, but the remainder is a sprawling policy paragraph mixing tool behavior, workflow rules, evidence-depth guidance, and unrelated admonitions. Many sentences do not help an agent decide how to invoke this specific tool, and the lack of structure makes the important details 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?

The tool is complex and has no output schema, and the description covers the batch/ack workflow, return contents, size limits, format behavior, and recovery paths. It is largely complete for correct invocation, though the unexplained id parameter and ambiguous index numbering leave minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning. It adds useful details: index is zero-based, format defaults to jpeg, and png preserves original detail. But the id parameter is never explained, and the phrase 'frames in a sheet are numbered 1..n' risks confusing users about whether index is zero-based or one-based.

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 first sentence states a specific verb and resource: read one saved storyboard plus timestamp metadata by index. It is clear what the tool does, but it does not name nearby alternatives such as video_frame or video_read, so sibling differentiation is only implicit.

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?

The description gives substantial usage context: host-chosen visual scope, plan/ack/finish workflow through video_review, and audio-only alternatives via audio_start/audio_url_start. However, it does not explicitly say when to use this rather than video_frame or video_read, so the guidance is clear but not fully comparative.

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

Deploy Server