YouTube MCP Server

Youtube Search Videos

youtube_search_videos

Discover YouTube videos by topic with keyword search; returns video IDs, titles, channels, publish times, and page tokens. Calls draw from a 100-per-day quota.

Instructions

Search YouTube for videos by keyword. Uses a scarce quota bucket: 100 calls/day.

Returns video IDs with titles, descriptions, channels and publish times, plus next_page_token for the following page.

Prefer other tools first. search.list has its own bucket of only 100 calls per day, separate from everything else, and it cannot be extended. To list a channel's videos use youtube_list_channel_videos (2 calls from the large shared pool), and to answer a question about a video use youtube_search_in_transcript. Use this when you genuinely need to discover videos by topic.

Each page — including one fetched with page_token — costs another call, so ask for what you need in one go rather than paging blindly. Results carry no statistics; call youtube_get_video_stats (its own 10,000/day bucket) for view/like counts.

order: relevance (default), date, viewCount, rating, title, videoCount — non-relevance orders can return a smaller, incomplete set. published_after / published_before are RFC 3339 timestamps and must be timezone-aware; naive values are interpreted as UTC. safe_search: moderate (default), strict, none. region_code is ISO 3166-1 alpha-2, video_category_id comes from youtube_list_categories. Like counts are available on videos; dislike counts are not (YouTube made them private in 2021).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`order`	No
`query`	Yes
`page_token`	No
`max_results`	No
`region_code`	No
`safe_search`	No
`published_after`	No
`published_before`	No
`video_category_id`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`items`	No
`next_page_token`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 4, 2026

TDQS

A4.8/5.0

Behavior5/5

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

No annotations are provided, so the description carries the full burden and does so: it discloses the scarce 100-calls/day quota bucket, that each page including page_token fetches costs another call, that results carry no statistics (and points to youtube_get_video_stats with its own 10,000/day bucket), and that dislike counts are unavailable since 2021. This is exactly the operational context an agent needs to avoid burning quota.

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?

Front-loaded with purpose and the quota warning, then structured into scannable segments for ordering, date filters, and safe_search. It is long, and a few sentences (e.g. restating the page-cost point) could be tightened, but nearly every line earns its place given the 9 undocumented parameters.

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 9-parameter search tool with 0% schema coverage, no annotations, and an output schema, the description supplies quota economics, safer alternatives, enumerations, timestamp format constraints, and the discovery that only like counts (not dislikes) are retrievable. Nothing essential to correct invocation 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?

Schema coverage is 0%, so the description must compensate, and it does for most parameters: order enum values plus the caveat about incomplete result sets, published_after/before as timezone-aware RFC 3339, safe_search enum and default, region_code ISO format, and video_category_id sourcing. It does not explain max_results or query semantics, so it falls short of fully covering all 9 parameters, but the coverage is well above baseline.

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?

States a specific verb+resource ('Search YouTube for videos by keyword') and immediately distinguishes itself from siblings by naming how it differs from youtube_list_channel_videos and youtube_search_in_transcript. An agent can identify the tool's 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?

Explicitly tells the agent to prefer other tools first, explains why (scarce 100/day quota), and routes to concrete alternatives with their cost profiles: youtube_list_channel_videos for channel listings and youtube_search_in_transcript for questions about a video. Names the precise condition ('when you genuinely need to discover videos by topic') that should select this tool.

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

Deploy Server