YouTube Transcript AI

Search YouTube videos

search_youtube_videos

Read-only

Search YouTube and return matching videos with channel, view count and duration. Use it first when researching a topic: run several differently-worded queries (and in more than one language), then read the best hits with get_youtube_transcript, find_in_transcript or get_transcripts_batch. Optional filters on views and length.

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_youtube_videos"
  }
}

Input Schema

Name	Required	Description
`sort`	No	relevance (default) or date (newest first).
`limit`	No	How many videos to return. Default 15.
`query`	Yes	Search words, e.g. "how I improved my English speaking"
`min_views`	No	Drop videos with fewer views than this.
`max_minutes`	No	Drop videos longer than this many minutes.
`min_minutes`	No	Drop videos shorter than this many minutes.

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 28, 2026

TDQS

A4.5/5.0

Behavior4/5

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

The annotations already declare readOnly, openWorld and non-destructive, so the baseline is met by structured data. On top of that the description discloses the result payload shape and that filtering by views and length is optional, which the annotations do not say. It does not discuss ranking behavior, result caps across queries, or cost of running many queries, so it falls short of a 5.

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 short sentences, front-loaded with the action and the return shape, then the workflow advice, then the filters. Every sentence carries information the agent could act on, with no restatement of the title or schema.

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?

With no output schema, the description compensates by naming the fields returned (channel, view count, duration), and with 100% schema coverage on six parameters it does not need to re-explain inputs. The addition of the multi-query research workflow covers the main ambiguity for a discovery tool with many retrieval siblings.

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%, and every parameter already carries its own description plus a default and bounds, so the schema does the heavy lifting. The description only adds a loose summary ('Optional filters on views and length') that neither covers sort, limit, or the min/max minute pair specifically. Baseline 3 applies.

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 ('Search YouTube and return matching videos') and states what comes back with each hit (channel, view count, duration). It is immediately distinguishable from retrieval siblings such as get_youtube_transcript because it names them as downstream steps rather than competing searches.

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 states exactly when to reach for this tool ('Use it first when researching a topic') and prescribes a query strategy of several differently-worded and multi-language searches. It also names three concrete follow-up tools for reading the results, so an agent knows both the entry point and the next step.

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

All YouTube Transcript AI tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.