Provides tools for searching videos, watching and summarizing, browsing channels and playlists, fetching transcripts, downloading video/audio, cutting clips, and building highlight reels from YouTube.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@YouTube for AI Agents find me the best video on meditation techniques"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ask "what's the best video on…?" and Claude finds it, watches it, and reports back. Drop a long podcast in chat — get the highlights in seconds. Cut clips, build reels, pull transcripts — all without opening a YouTube tab.
Quick Start · Try it · Discord · Demo
Click the image to watch the 1-minute walkthrough.
Related MCP server: youtube-mcp
1. Install the plugin — inside Claude Code, run:
/plugin marketplace add JCodesMore/jcodesmore-plugins
/plugin install youtube@jcodesmore-pluginsThen fully restart Claude Code (quit the app and reopen).
2. That's it. No API key, no signup. Just start asking.
Optional: run
/youtube:setupto sign in with your own YouTube cookies for personalized search and recommendations.
Talk to Claude like a friend:
"Watch this video and give me the recipe — I don't want to scroll the comments."
"Find me five highly-rated videos on Roman history."
"What are this channel's best uploads? Watch the top three and summarize."
"Pull the actionable takeaways from this 90-minute interview."
"Cut a 30-second clip starting at 2:15 from this video."
"Combine these three cooking videos into a single highlight reel."
The agent searches, watches, and reports back — no scrubbing, no scrolling.
Nine smart tools wrapped in two skills and one agent — search, watch, clip, and reel without leaving the chat.
Capability | Try saying |
Search videos, channels, playlists | "find me the top videos on…" |
Watch and summarize | "watch this and tell me what matters" |
Browse a channel or playlist | "what's worth watching from this YouTuber?" |
Pull a transcript | "grab the transcript around the 5-minute mark" |
Download video or audio | "save the audio of this video" |
Cut a clip | "clip 2:15 to 2:45 from this video" |
Build a highlight reel | "combine these clips into one reel" |
Discord — chat, help, show-and-tell · Issues — bugs & feature requests · Contribute · More plugins
By default, search runs anonymously — no login required. If you want personalized recommendations and search results, run /youtube:setup and follow the cookie-extraction wizard. Cookies stay on your machine in the plugin data directory; nothing is uploaded anywhere.
The MCP server is portable. Per-platform setup guides:
Clone and build it yourself:
git clone https://github.com/JCodesMore/youtube-for-ai-agents.git
cd youtube-for-ai-agents
npm install
npm run buildOr wire the published npm package directly into any MCP-compatible client:
{
"mcpServers": {
"youtube": {
"command": "npx",
"args": ["-y", "@jcodesmore/youtube-for-ai-agents"]
}
}
}Requirements: Node.js ≥ 18.
Model Context Protocol SDK — tool exposure to Claude
youtubei.js — YouTube InnerTube client (no API key needed)
youtube-transcript-plus — transcript fetching
ytdlp-nodejs — video and audio downloads
Zod — schema validation
Apache License 2.0 — © 2026 JCodesMore
Uses youtubei.js, an unofficial YouTube client. Not affiliated with, endorsed by, or associated with YouTube or Google.
Part of jcodesmore-plugins.
Extract one or more clips from a YouTube video by timestamp. Downloads the source video once at 720p, then cuts each clip. Each clip needs startTime and endTime (seconds, MM:SS, or HH:MM:SS) and an optional label for the filename. Uses fast keyframe-aligned cuts by default — do NOT set accurate: true unless the user explicitly asks for frame-perfect precision (it re-encodes and is much slower). Keep clips tight — 5-10 seconds each, capturing one key moment per clip. When 2+ clips are provided, automatically produces a per-video highlight reel alongside individual clips.
| Name | Required | Description | Default |
|---|---|---|---|
| clips | Yes | One or more clip definitions with start/end timestamps | |
| force | No | Bypass the duration guard for long videos | |
| quality | No | Video quality for the source download (default: best) | |
| videoId | Yes | YouTube video ID | |
| accurate | No | Frame-accurate cuts via re-encoding — MUCH slower. Only use when the user explicitly needs frame-perfect precision. Default fast keyframe cuts are fine for nearly all use cases (default: false) | |
| outputDir | No | Output directory for clip files (defaults to current directory) | |
| highlightReel | No | Combine all clips into a single highlight-reel video (default: true). Set to false for individual clips only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds valuable context beyond annotations, such as the 720p default, keyframe-aligned cuts, re-encoding behavior of accurate:true, and the automatic highlight reel generation for 2+ clips. Annotations are sparse, so this additional detail is important.
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?
Well-structured and front-loaded: starts with the core action, then explains mechanics, parameter formats, and defaults. No wasted sentences, each clause adds useful information.
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?
Complete for a tool with this complexity and no output schema. It covers mechanics, parameter formats, defaults, and important behavioral traits, leaving little ambiguity for an agent.
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?
Describes clip parameters (startTime, endTime, label) and their formats, and explains accurate and highlightReel semantics. Schema coverage is 100%, so this adds some value but mostly repackages schema details with a bit more context.
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?
States a specific verb (Extract clips) and resource (YouTube video by timestamp), and the mechanism is clear: download once at 720p, cut each clip.
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?
Gives explicit guidance on when to use accurate:true vs default and advises keeping clips tight at 5-10s. Does not compare against sibling tools like youtube_download or youtube_highlight_reel, but the internal usage guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a YouTube video or audio track to a local file. Defaults to 720p quality. Supports quality selection (720p/1080p/best/etc.), download type (video+audio/audio/video), and format. Videos over 30 minutes trigger a confirmation prompt — use force: true to bypass. For video+audio, automatically downloads and muxes separate streams.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Download type — "video+audio" (default), "audio" (audio only), or "video" (no audio) | |
| force | No | Bypass the duration guard for long videos | |
| format | No | Container format (default: mp4) | |
| quality | No | Video quality (default: best) | |
| videoId | Yes | YouTube video ID | |
| outputPath | No | Output file path (defaults to <title>.<format> in current directory) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it is a non-read-only, open-world, non-destructive operation. The description adds real behavioral detail beyond that: the >30 minute confirmation gate, the force bypass, and the automatic stream download-and-mux for video+audio. It omits what the tool returns and where confirmation appears.
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?
Four tight sentences, front-loaded with the core action and defaults, then escalating to selection options and the guard behavior. No filler sentences.
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?
With no output schema and 100% schema coverage, the description covers the important unknowns (defaults, guard, muxing). The main remaining gap is the return value and the quality-default inconsistency, but for a file-download tool this is largely complete.
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?
Schema coverage is 100%, so the baseline is 3 and the schema already documents every parameter. The description adds normalization of the force parameter's purpose, but it also states 'Defaults to 720p quality' while the schema declares quality default 'best', a minor inconsistency that undercuts its added value.
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?
States a specific verb and resource (download a YouTube video or audio track to a local file) plus the supported scope (quality, type, format). This clearly separates it from read-only siblings like youtube_get_video_info and youtube_search.
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?
Explains defaults, quality/type/format selection, and precisely when the long-video confirmation fires and how force bypasses it. It does not explicitly steer the agent away from sibling download-like tools such as youtube_clip, but the context is otherwise clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metadata for a YouTube channel — name, handle, description, subscriber count, country, and more. Accepts @handle, full URL, or channel ID.
| Name | Required | Description | Default |
|---|---|---|---|
| channelId | Yes | @handle, full YouTube URL, or channel ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds no further behavioral context such as quota costs, auth requirements, or behavior on a non-existent channel, so it sits at the baseline.
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?
Two tight sentences with no filler: the purpose and returned fields come first, and the accepted input formats follow. Every clause earns its place.
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 one-parameter read tool with full annotation coverage and no output schema, the description compensates well by naming the fields returned. An agent has everything needed to select and invoke it correctly.
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?
Schema coverage is 100% and the single parameter's accepted formats ('@handle, full YouTube URL, or channel ID') are already documented in the schema. The description restates that same information without adding resolution or error-handling semantics, so baseline 3 applies.
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?
States a specific verb and resource ('Get metadata for a YouTube channel') and enumerates returned fields (name, handle, description, subscriber count, country), which separates it from channel-video siblings. It does not explicitly name an alternative tool, but the resource boundary is unambiguous.
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?
Usage is implied by the resource itself — an agent can infer it should call this when it needs channel-level metadata rather than videos or transcripts. However, there is no explicit when-to-use/when-not guidance or reference to a sibling tool for related needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List videos from a YouTube channel. Accepts @handle, full URL, or channel ID. Returns videos sorted by newest, popular, or oldest.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort order (default: newest) | |
| limit | No | Max videos to return (default: 30, max: 500) | |
| channelUrl | Yes | @handle, full YouTube URL, or channel ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a safe, non-destructive, open-world read, so the safety profile is covered. The description adds no behavior beyond that: nothing about pagination, continuation tokens, rate limits, or whether the limit truncates silently. With annotations carrying the safety burden, this is only baseline value-add.
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?
Three short sentences, front-loaded with the core action, with no filler. It loses a point only because the second and third sentences largely repeat schema content (accepted formats and sort values) rather than adding new information.
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 three-parameter list tool with full schema coverage and annotations covering the safety profile, the description covers intent, input formats, and sort options. It omits any note on pagination or how the maximum limit interacts with result retrieval, a minor gap given no output schema exists.
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?
Schema description coverage is 100%, so every parameter is already documented in the schema. The description restates the accepted identifier forms (@handle, URL, ID) and sort orders, adding no syntax or format detail beyond what the schema provides. Baseline 3 is appropriate.
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?
States a specific verb and resource ('List videos from a YouTube channel'), which is clearly distinct from youtube_get_channel_info, youtube_search, and youtube_get_playlist. It does not explicitly name those siblings, so sibling differentiation relies on the agent's own inference.
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?
Usage is implied by the verb and resource, but there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as youtube_search for keyword-based discovery or youtube_get_channel_info for metadata. Adequate but leaves selection entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a YouTube playlist's metadata and its videos. Returns title, description, channel, video count, and the list of videos with their positions.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max videos to return (default: 30, max: 200) | |
| playlistId | Yes | YouTube playlist ID (e.g. PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the content of the response (title, description, channel, count, videos with positions), which is useful but overlaps with the purpose statement rather than disclosing new behavior like pagination or quota costs.
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?
Two tight sentences with the core action front-loaded and the return contents following. Nothing is wasted, though the second sentence largely restates what a 'get playlist' would return.
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?
No output schema exists, so the description appropriately enumerates the returned fields. For a read-only, two-parameter tool with full schema coverage this is nearly enough; only the absent usage/prerequisite context keeps it short of complete.
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?
Schema description coverage is 100%: playlistId has a format example and limit has default and max documented in the schema itself. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.
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?
States a specific verb ('Get') and resource ('YouTube playlist') plus the scope of the return (metadata and its videos). It clearly distinguishes itself from single-video lookups like youtube_get_video_info, though it never explicitly names a sibling to route against.
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?
No when-to-use guidance, no prerequisites (e.g. playlist must be public), and no mention of alternatives such as youtube_search or youtube_get_channel_videos. Usage is only implied by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the transcript of a YouTube video. Control output size with: "format" — "text" (fullText only, smallest), "segments" (timestamps only), or "both" (default). Use "startTime"/"endTime" (seconds) to grab a specific section (pairs well with chapter timestamps from youtube_get_video_info). Use "maxSegments" to cap output for previewing long videos.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Response format — "text" (fullText only, smallest response), "segments" (timestamped array only), or "both" (default). Use "text" to cut response size roughly in half. | |
| endTime | No | Only return segments before this time (seconds). | |
| videoId | Yes | YouTube video ID | |
| language | No | Language code (default: "en") | |
| startTime | No | Only return segments at or after this time (seconds). Pairs well with chapter timestamps from youtube_get_video_info. | |
| maxSegments | No | Max segments to return (capped at 5000). Good for previewing long videos without blowing up context. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered by structured data. The description adds useful output-shaping behavior (default is 'both', 'text' roughly halves response size, intervals are half-open) but says nothing about failure modes such as missing captions or language fallback, nor about rate limits.
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?
Three tight sentences with the core purpose front-loaded and parameter guidance grouped afterwards. Some of the format enumeration duplicates the schema wording, but nothing is padded and the size is proportionate.
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?
With no output schema, the description carries the burden of explaining return shape, and it only implies it through the format options (fullText, timestamped segments). It is complete enough on output sizing but leaves the actual response fields, pagination/truncation signaling above 5000 segments, and transcript-unavailable behavior unexplained.
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?
Schema description coverage is 100%, so every parameter including videoId, language, startTime/endTime, format, and maxSegments is already documented in the schema. The description largely restates those same semantics (format options, seconds-based ranges, maxSegments cap) without adding format details the schema lacks.
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?
States a specific verb and resource ('Get the transcript of a YouTube video') and immediately scopes it with concrete output controls. It is clearly distinguishable from siblings like youtube_get_video_info, youtube_search, or youtube_download.
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?
Gives practical guidance on choosing a format, grabbing a section with startTime/endTime, and capping output with maxSegments, and explicitly notes that time ranges 'pair well with chapter timestamps from youtube_get_video_info'. It stops short of stating when to prefer this tool over siblings for content retrieval generally.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metadata for a YouTube video. Use "detail" to control response size: "brief" (key stats only — title, channel, views, likes, duration), "standard" (default — most fields, truncated description, chapter count), or "full" (everything including full description, chapters, tags, thumbnail).
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | Detail level — "brief" (key metadata only), "standard" (most fields, truncated description, no chapters), or "full" (everything). Default: standard | |
| videoId | Yes | YouTube video ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful operational context beyond that: it enumerates what each detail level returns (stats vs truncated description vs full description, chapters, tags, thumbnail), letting the agent anticipate response payload cost.
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?
Two sentences, purpose front-loaded, followed immediately by actionable detail-level semantics. No filler, no repetition of the tool name, and every clause carries information.
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 two-parameter read tool with annotations and no output schema, the description covers everything needed: what it returns, how to size the response, and the default. Return values are effectively described, so the absence of an output schema is not a gap.
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 100% schema coverage the baseline is 3, but the description adds field-level meaning the schema lacks — e.g. 'brief' explicitly lists title, channel, views, likes, duration. However, it conflicts with the schema on 'standard': the description claims 'chapter count' is included while the schema says 'no chapters', which is a real inconsistency the agent must resolve.
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?
States a specific verb and resource ('Get metadata for a YouTube video') that an agent can immediately distinguish from sibling resources in the list (transcripts, channel videos, downloads, search). The scope is narrow and concrete rather than tautological.
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?
Usage guidance exists but only for the `detail` parameter (how to control response size), not for when to pick this tool over siblings such as youtube_get_transcript or youtube_search. No exclusions or prerequisites are stated; the usage is implied by the description rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Combine existing clip files into a single highlight reel. Pass file paths from previous youtube_clip results in your desired playback order. Use this after clipping multiple videos to create one combined reel across all sources. The order of the clips array determines playback order — arrange clips for narrative flow before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| clips | Yes | File paths to existing clip/video files, in your desired playback order | |
| label | No | Name for the reel file — produces "{label}.mp4" (default: "highlight-reel") | |
| outputDir | No | Output directory for the highlight reel (defaults to current directory) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=false, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description adds the behavioral detail that playback order follows array order across all sources, which is genuinely useful, but says nothing about what happens to source files or failure behavior on missing/invalid paths. Adequate with annotations doing much of the work.
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?
Front-loaded with the core action and efficient overall, but the ordering point is made twice ('in your desired playback order' and 'The order of the clips array determines playback order'), which is mild redundancy in an otherwise tight description.
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 three-parameter combination tool with no output schema, the description covers the action, prerequisite, ordering semantics and input source well enough to call correctly. It stops short of explaining output naming/path behavior, though the schema's label and outputDir descriptions partly cover that.
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?
Schema coverage is 100%, so all three parameters (clips, label, outputDir) are already documented in the schema. The description restates the ordering meaning of 'clips' but adds no syntax or format detail beyond what the schema provides; baseline 3 applies.
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?
States a specific verb and resource ('Combine existing clip files into a single highlight reel') and clearly distinguishes itself from the sibling youtube_clip, which produces the inputs rather than combining them. An agent can tell what this does 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the prerequisite ('Use this after clipping multiple videos') and the source of its inputs ('Pass file paths from previous youtube_clip results'), routing the agent to the sibling that must run first. It also states the ordering requirement before calling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search YouTube for videos, channels, or playlists. Supports filtering by upload date (today/week/month/year), duration (short/medium/long), and sorting (relevance/date/views/rating). Returns results with metadata including title, channel, views, duration, and whether results are personalized.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by type (default: video) | |
| limit | No | Number of results (default: 20, max: 50) | |
| query | Yes | Search query | |
| sortBy | No | Sort results — "relevance", "date" (newest first), "views" (most viewed), "rating", or default relevance | |
| duration | No | Filter by duration — "short" (<4 min), "medium" (4-20 min), "long" (>20 min), or "all" (default: all) | |
| uploadDate | No | Filter by upload date — "today", "week", "month", "year", or "all" (default: all) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: the supported filter axes and the shape of the returned metadata, including the note about whether results are personalized.
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?
Three tight sentences: what it searches, what filters exist, and what it returns. It is front-loaded with the core purpose and wastes no words, though the filter enumeration slightly overlaps the schema.
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?
With no output schema, the description usefully summarizes the return payload (title, channel, views, duration, personalization). Combined with annotations covering the safety profile and a 100%-covered input schema, an agent has enough to invoke it correctly.
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?
Schema description coverage is 100% and all six parameters (including the enum values and defaults) are fully documented in the schema. The description's mention of upload date, duration, and sorting merely restates what the schema already encodes, so it adds no meaning beyond it — baseline 3.
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 names a specific verb ('Search') and resource ('YouTube') and enumerates what is searchable (videos, channels, playlists), which is clear enough for an agent. It does not, however, explicitly distinguish itself from siblings like youtube_get_playlist or youtube_get_channel_info that also touch channels and playlists.
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 explains what the tool does but never says when to reach for it versus the many get_* siblings (youtube_get_video_info, youtube_get_channel_videos, etc.). There is no when-to-use, when-not-to-use, or alternative-routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0youtube_clipyoutube_downloadyoutube_get_channel_infoyoutube_get_channel_videosyoutube_get_playlistyoutube_get_transcriptyoutube_get_video_infoyoutube_highlight_reelyoutube_searchScored across 9 tools
Each tool targets a distinct resource and action: search, channel/video/playlist metadata retrieval, transcript extraction, video download, clip extraction, and highlight reel assembly. The only potential overlap is between youtube_clip and youtube_download, but clip is explicitly for extracting short segments while download fetches the full source. Descriptions make boundaries clear.
All tools use the youtube_ prefix and follow a predictable verb_noun pattern (get_channel_videos, get_video_info, get_transcript, search, download, clip). The only minor deviation is youtube_highlight_reel, which is a noun phrase, but it clearly implies a create action and fits the overall schema.
Nine tools are well-scoped for an agent consuming YouTube content, with no redundant or trivial entries. Each tool earns its place by covering a distinct step in the research, retrieval, or editing workflow.
The surface covers search, metadata, transcripts, downloads, clipping, highlight reels, playlists, and channels—core workflows for AI agents. Minor gaps exist, such as no direct tool to list all playlists for a channel or to retrieve comments/live stream info, but agents can work around these for most tasks.
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents. No signup.
YouTube transcripts, search, channel browsing, and playlists for AI agents via MCP.
💯 The fastest YouTube transcript + YouTube search MCP for AI agents. Try for free.
