Skip to main content
Glama

Find in videos

find_in_videos
Read-only

Search several videos for the same keywords in one call and get back only the matching passages, grouped by video, plus which videos never mention them. Use it to check a set of search results or a channel's latest uploads for a topic without reading them all. Up to 5 videos per call, or 25 on the Ultra plan; each video counts as one request.

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": {
      "videos": "<videos>",
      "keywords": "<keywords>"
    },
    "name": "find_in_videos"
  }
}

Input Schema

NameRequiredDescriptionDefault
langNoOptional BCP-47 caption language code applied to every video.
videosYesYouTube URLs or 11-character video IDs.
contextNoParagraphs (about 30 seconds each) before and after each match. Default 1.
keywordsYesWords or short phrases to look for (up to 8). Try synonyms and likely mis-hearings.
max_hits_eachNoPassages to return per video. Default 3.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), so the description's real contribution is quota behavior: 'Up to 5 videos per call, or 25 on the Ultra plan; each video counts as one request'. It also discloses the return shape, including the unusual negative result — which videos never mention the keywords. It doesn't say how per-video failures (transcripts disabled, region blocks) surface, which would complete the picture.

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?

Three sentences, front-loaded with what the tool does, then when to use it, then the quota constraint. Every sentence carries distinct information and none is padding.

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?

There is no output schema, and the description compensates by explaining that results are grouped by video and that non-matching videos are reported separately — enough to interpret the response. Plan limits and request accounting are covered. The only gap is error/partial-failure behavior for a batch call, which matters more here than for a single-video tool.

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 100%, so the baseline is 3, but the description adds real meaning the schema cannot: the practical per-call video limit is 5 (not the schema's maxItems of 25) except on Ultra, and each video consumes a request. That reframes the 'videos' array from a plain list into a metered batch. Keyword and context semantics are left entirely to the schema.

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 gives a specific verb and resource — searching several videos for the same keywords in a single call — and immediately names the distinguishing scope: batched across videos rather than one, results grouped by video. That scope statement alone separates it from single-transcript siblings like find_in_transcript without needing to name them.

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?

It supplies two concrete usage scenarios: vetting a set of search results, or scanning a channel's latest uploads for a topic 'without reading them all'. That is clear when-to-use guidance. It stops short of stating when NOT to use it (e.g., for a single known video or for locating one exact quote), so it does not reach the top band.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.