Skip to main content
Glama

Search videos

search_videos
Read-only

Search for videos matching a query on YouTube (default), TikTok, or Instagram. Returns titles, ids, durations, and URLs that get_transcript accepts directly. On YouTube, upload_date, duration, sort and captions narrow the results; search_channels finds channels or playlists instead. To read what the videos say rather than only their titles, set transcripts to N: the caption transcripts of the first N rows (at most 5) come back in the same call.

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": {
      "query": "<query>"
    },
    "name": "search_videos"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortNoYouTube only. relevance (default) or views (most viewed first). YouTube search no longer sorts by date; for recent videos use upload_date.relevance
limitNoMax results to return (1–50). Defaults to 5.
queryYesSearch keywords.
captionsNoYouTube only. true keeps only videos with subtitles or closed captions.
durationNoYouTube only. short is under 4 minutes, medium 4 to 20 minutes, long over 20 minutes.
platformNoWhere to search. Defaults to youtube.youtube
transcriptsNoAlso return the caption transcripts of the first N videos (1-5), each cut at 12,000 characters. Captions only: a video without captions (most Instagram reels) comes back with outcome no_transcript, and get_transcript transcribes its audio. 1 credit per caption transcript delivered, on top of the listing's; failures are free.
upload_dateNoYouTube only. Uploaded within the last hour, today, this week, this month, or this year.

Output Schema

NameRequiredDescriptionDefault
countNoNumber of videos returned.
noticeNoWhy a list is empty or may be incomplete, when the source says: e.g. "This channel has no Live tab."
videosNoMatching videos with ids, titles, and URLs.
balanceNoRemaining credit balance after this call, when known.
creditsSpentNoCredits charged for this call (0 on failure or for admins).
creditsNoticeNoCredits words for the user, with the link that acts on them: why the call was refused for credits, or a note once the balance runs low. Pass it on to the user.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / transcripts / description
      Previous value: -"Also return the caption transcripts of the first N videos (1-5), each cut at 12,000 characters. Captions only: a video without captions (most Instagram reels) comes back with outcome no_transcript, and get_transcript transcribes its audio. 1 credit per transcript delivered, on top of the listing's; failures are free."New value: +"Also return the caption transcripts of the first N videos (1-5), each cut at 12,000 characters. Captions only: a video without captions (most Instagram reels) comes back with outcome no_transcript, and get_transcript transcribes its audio. 1 credit per caption transcript delivered, on top of the listing's; failures are free."
  2. First observed

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already establish read-only, open-world, non-idempotent, and non-destructive behavior, so the bar is lower. The description adds useful context about returned fields and that get_transcript accepts the returned URLs directly, plus that caption transcripts can be included in the same call. It does not explain credit consumption, no-transcript outcomes, or non-idempotence, though much of that is covered by the schema.

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

Conciseness4/5

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

The description is front-loaded and generally efficient, moving from purpose to output to filters to the transcript option. Some sentences repeat details already provided by the input and output schemas, but there is little wasted wording.

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?

Given the 8 parameters, rich schema, annotations, and output schema, the description covers the essential selection context: platforms, alternatives, YouTube filters, and the transcript option. It leaves credit cost and caption-failure behavior to the schema, which is acceptable, though mentioning them briefly would improve completeness.

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 100%, so the baseline is 3. The description names upload_date, duration, sort, captions, and transcripts, but adds no syntax or meaning beyond what the schema already documents, including the maximum of 5 transcripts.

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 states a specific verb and resource: search for videos matching a query across YouTube, TikTok, or Instagram. It also explicitly distinguishes itself from search_channels and get_transcript, so an agent can identify its role without opening the schema.

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?

It gives explicit routing guidance: use search_channels for channels or playlists, and use the transcripts parameter when the goal is to read video captions rather than only titles. It also explains that YouTube filters narrow results. The alternatives and conditions are clear.

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.