video-research-mcp

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

Beyond the annotations (which indicate idempotent, non-destructive, open-world behavior), the description adds valuable implementation context: it discloses the Gemini backend, 'structured output for reliable JSON responses,' and details the strict_contract pipeline including 'parallel strategy/concept-map generation, artifact rendering, and quality gates.' It also warns about performance implications ('takes longer').

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 well-structured with clear Purpose → Constraints → Behavioral Details → Args → Returns sections. While the Args section partially duplicates the schema, this repetition is justified by the incomplete schema coverage. The strict_contract explanation is appropriately detailed. Minor redundancy exists between schema descriptions and Args descriptions.

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 complex tool with 7 parameters, multiple operational modes (default vs strict_contract), and custom output schema support, the description provides comprehensive coverage. It explains input constraints, backend technology, return value shapes (VideoResult vs custom vs strict contract output), and caching behavior. It appropriately relies on the existing output schema without redundant explanation.

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?

With 57% schema description coverage, the Args section compensates effectively by documenting all 7 parameters, including thinking_level ('Gemini thinking depth') which lacks schema description. The description adds clarifying examples for the instruction parameter ('e.g. summarize key points') and explains the strict_contract behavior beyond the schema's basic 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 clearly states the tool 'Analyze[s] a video (YouTube URL or local file) with any instruction,' specifying the exact resource (video), supported sources (YouTube or local), and flexible analysis capability. While it implies single-video scope through the parameter structure, it does not explicitly differentiate from siblings like video_batch_analyze or video_metadata.

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 provides internal usage constraints ('Provide exactly one of url or file_path') and explains the strict_contract tradeoff ('Returns richer output but takes longer'). However, it lacks explicit guidance on when to use this tool versus siblings like video_batch_analyze (batch processing) or content_analyze (non-video content).

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