Youtube
youtubeRetrieve video metadata, searchable transcripts with timestamps, channel/playlist uploads, and free-text search results from a single endpoint.
Instructions
Fetch YouTube content via yt-dlp and youtube-transcript-api.
Use this for YouTube lookups when web_fetch_incisive doesn't apply: structured metadata + description for a video, a rendered caption transcript with timing and search, a flat listing of recent uploads for a channel or items for a playlist, or a YouTube-wide search by free-text query.
Actions: video, transcript, channel, playlist, search.
PARAMETER SPLIT: video / transcript / channel / playlist take url=; search takes query=.
Query formats:
video: full YouTube URL (watch?v=, youtu.be/, shorts/, clip/, embed/, or v/)
transcript: same URL formats as video; combine with languages=, timestamps=, search=, windows=, start_seconds=, end_seconds=, order=
channel: /@handle, /channel/UC..., /c/, /user/. The bare channel URL returns the channel's available tabs (Videos, Shorts, Live, etc.). Append /videos, /shorts, /streams, /playlists, or /podcasts to list the actual entries within that tab.
playlist: /playlist?list=...
search: free-text query (passed to yt-dlp's ytsearch{N}: routing).
Transcript actions:
Default (no search/windows/range): full transcript in the requested timestamps= shape.
search="query": BM25 over window text, with optional time-range filter.
start_seconds/end_seconds: half-open time-range filter.
windows=[i, ...]: explicit retrieval by window index. Mutually exclusive with search and time-range filters.
order=score (default) or order=time: BM25 vs chronological ordering.
Transcript timestamps= modes:
compact (default): sparse anchors at ~30s windows plus inline markers for unusually long pauses; each source caption cue on its own line. Hybrid shape that preserves citation precision while keeping token cost low.
absolute: per-line [MM:SS] prefix on every cue.
none: flat text with no timing.
structured: YAML list of {t, d, text} triples for machine consumers.
Auto-generated captions lack punctuation and capitalization; the 'transcript_kind' field in frontmatter signals which to expect. The chunking strategy adapts: punctuated input gets sentence-aware window cuts; unpunctuated input falls back to pause-aware time windows.
Channel, playlist, and search listings use yt-dlp's flat extraction, returning stub entries with id, title, duration, and view count. Set limit= to control how many entries (default 30, max 200). When a bare channel URL is passed, the response surfaces the channel's tab list with a frontmatter hint nudging toward /videos, /shorts, etc. — pick the right tab and resubmit. Search results match what the user would see browsing youtube.com/results?search_query=... since yt-dlp routes through the same Innertube endpoint.
A 'video' call returns the description. Comments live on the dedicated youtube_comments — the video frontmatter surfaces a 'see_also' pointing there when the channel reports a non-zero comment count, so callers can pivot when they want to read the conversation.
Music URLs (music.youtube.com) are out of scope and will be handled by a sibling tool.
No authentication required. May fail with bot-detection or PoTokenRequired errors; residential connections fare best. The fallback workaround when blocked is to set HTTPS_PROXY to a residential proxy endpoint.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | YouTube URL for video / transcript / channel / playlist actions. video / transcript: watch, youtu.be, shorts, clip, embed, v/. channel: /@handle, /channel/UC..., /c/, /user/, optionally with a /videos, /shorts, /streams, /playlists tab suffix. playlist: /playlist?list=... Not used for action='search' (use 'query=' instead). | |
| limit | No | For 'channel' / 'playlist': maximum number of entries to return. Default 30, capped at 200. yt-dlp's flat extraction respects this server-side via playlistend, so large channels don't pull every upload. | |
| order | No | For 'transcript' search: 'score' (default) ranks by BM25 relevance; 'time' sorts by start_seconds ascending. Only meaningful when a query or range is set. | score |
| query | No | For action='search': free-text query string. yt-dlp's ytsearch{N}: routing handles URL encoding. | |
| action | Yes | The operation to perform. video: fetch video metadata + description from a YouTube URL. transcript: fetch the caption transcript for a video URL, with optional BM25 search, time-range filtering, and explicit window retrieval. channel: list a channel's recent uploads. playlist: list a playlist's items. search: search YouTube for videos matching a free-text query. | |
| search | No | For 'transcript': BM25 query over window text. Mutually exclusive with 'windows='. Combine with start_seconds / end_seconds to restrict by time range. | |
| chapter | No | For 'transcript': scope search to a chapter by title. Parsed via the same query syntax as 'search=' so partial matches and phrases work (e.g. chapter='intro' matches 'Introduction'). Composes with search and time-range filters; incompatible with 'windows='. Available chapters are listed in the frontmatter 'chapters:' field of a non-filtered transcript fetch. | |
| windows | No | For 'transcript': retrieve specific window indices (0-based). Mutually exclusive with 'search=' and incompatible with time-range filters. Out-of-range indices are reported in frontmatter rather than erroring. | |
| languages | No | For 'transcript': caption language preference list, tried in order (e.g. ['en', 'en-US']). Defaults to ['en']. | |
| timestamps | No | For 'transcript': output shape. 'compact' (default) emits sparse anchors plus inline markers for unusually long pauses, with each source caption cue on its own line. 'absolute' emits a per-line [MM:SS] prefix on every cue. 'none' returns flat text with no timing. 'structured' returns a YAML list of {t, d, text} triples for machine consumers. | compact |
| end_seconds | No | For 'transcript': upper bound on a time-range filter, in seconds. Half-open: a window starting exactly at end_seconds does not match. | |
| start_seconds | No | For 'transcript': lower bound on a time-range filter, in seconds. Windows whose interval overlaps [start_seconds, end_seconds) match. Combine with 'search=' for a time-restricted query. |