moreel

Overview Schema Source Related Servers Score Discussions Admin

Get Video Map

get_video_map

Read-onlyIdempotent

Resolve ambiguous spoken references like 'this one' by mapping speech to visible entities, interactions, and actions with evidence and confidence ratings. Requires a prior video analysis ID.

Instructions

Returns the Video Map: the semantic layer connecting what was SAID to what was VISIBLE and what the person DID — entities (people/products/objects that recur across the video), interactions (points_at, shows, holds, etc.), and references (what "this"/"that one" actually meant).

This is what resolves "speech → reference → visual target" — a transcript alone cannot tell you what "this one" refers to; this can, when the visual evidence was strong enough. Every interaction/reference has an "evidence_level" (observed/inferred/uncertain) and a "confidence" — absent "target_entity_id" means the evidence was too weak to confidently resolve a target, which is the CORRECT and expected answer in that case, not a failure.

Requires a "video_id" from a prior understand_video call with visual analysis enabled. Returns empty arrays (not an error) when the Video Map feature wasn't enabled or found nothing — use search_video/find_moment for the underlying speech/visual search either way.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`video_id`	Yes	A video id previously returned by understand_video or transcribe_video.

Output Schema

TableJSON Schema

Name	Required	Description
`scenes`	Yes
`entities`	Yes	Every distinct person/product/object the analysis identified, with a stable id reusable across interactions and references.
`video_id`	Yes
`references`	Yes	Linguistic references ("this", "that one") resolved to a specific entity, when evidence was sufficient.
`interactions`	Yes	Things the person visibly did — pointing, showing, holding, etc.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 10, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds critical behavioral detail: evidence_level ('observed/inferred/uncertain'), the meaning of absent target_entity_id (expected, not failure), and the empty-array vs error contract. These go far beyond the structured annotations and reduce deployment surprises.

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

Conciseness5/5

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

The description is packed with purpose, usage, semantics, and edge cases, and every sentence earns its place. It front-loads what the tool does, then gives context and fallback guidance, ending with the clearest routing alternative. No fluff or redundancy.

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?

For a read-only look-up tool with a single parameter and a deep output schema, the description covers the only input prerequisite, the meaning of key output fields, the edge case for un-resolved references, and the fallback behavior when data is absent. Nothing an agent needs to safely invoke and interpret this tool 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?

The input schema already describes video_id ('A video id previously returned by understand_video or transcribe_video'), providing full coverage of the single parameter. The description adds one valuable nuance: 'with visual mapping enabled', which is not in the schema and is essential for determining when the tool will return meaningful results.

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 description uses a specific verb ('Returns') and names a concrete resource ('the Video Map: the semantic layer') and explains what it connects (speech, visible entities, interactions, references). It clearly distinguishes itself from siblings like search_video or find_moment by stating it resolves speech-to-reference mappings, not raw search.

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?

The description gives explicit preconditions ('Requires a video_id from a prior understand_video call with visual analysis enabled'), explicit fallback behavior ('Returns empty arrays when the feature wasn't enabled or found nothing'), and explicit alternatives ('use search_video/find_moment for the underlying speech/visual search either way').

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

Install Server