Fetch YouTube video information and transcript.

Tip: You can pass either a raw video id (11 chars) or a full YouTube URL.

Resolve a YouTube channel reference into a concrete channelId.

What this tool does: - Converts a user-facing channel identifier into a YouTube channelId. - Optionally returns the channel's uploadsPlaylistId, which enables listing all uploaded videos via playlistItems.list.

Supported input formats (examples): - Handle: @GoogleDevelopers - Handle URL: https://www.youtube.com/@GoogleDevelopers - Channel ID URL: https://www.youtube.com/channel/UC... - Legacy username URL: https://www.youtube.com/user/SomeUsername

Parameters: channel_ref: Channel identifier in one of the supported formats. resolution_mode: - strict (default): ambiguous inputs are rejected with an explainable error. This prevents "silent wrong channel" bugs. - best_effort: ambiguous inputs return a short list of candidate channels. (This mode may use the Search API and can be expensive.) include_uploads_playlist: If true, attempts to include uploadsPlaylistId in the output.

Returns (structured JSON): - channelId: string | null - title: string | null - handle: string | null - uploadsPlaylistId: string | null - warnings: string[] - candidates: {channelId,title,handle}[]

Failure modes: - Missing API key: raises error "YOUTUBE_API_KEY not configured". - Ambiguous/unsupported input (strict): raises ValueError with guidance.

Safety notes: - Does not perform destructive actions. - Does not access private channel data.

List videos for a channel (public data), with safe defaults.

Default behavior (safe + complete): - Uses the channel's uploads playlist (uploadsPlaylistId) to paginate through all uploaded videos.

Parameters: channel_ref: Same formats as resolve_youtube_channel. max_videos: Hard limit per tool call. The tool may return fewer items and set truncated=true. page_token: Token for pagination (from previous response nextPageToken). Alias: you may also pass next_page_token (some agents prefer it). include_shorts: Default false. If true, includes Shorts (best-effort classification). include_live: Default false. If true, includes live/upcoming videos (best-effort). parts_level: - basic (default): snippet + statistics + contentDetails - full: also requests status/liveStreamingDetails (heavier payload) order_strategy: - uploads_playlist (default): low quota, paginated. - local_sort: fetches a bounded subset then sorts locally. (Not paginated; page_token must be null.) - search_api: uses YouTube Search API ordering (expensive, capped). Explicit opt-in only. order_by: - date (default) - viewCount, likeCount, commentCount, duration Note: search_api supports only date and viewCount.

Returns (structured JSON): - items: video[] (YouTube API video resources) - nextPageToken: string | null - next_page_token: string | null (alias of nextPageToken for agent friendliness) - quotaEstimate: {estimatedUnits,strategy,notes[]} - truncated: bool - appliedMaxVideos: int - appliedOrder: {strategy, by}

Quota/performance notes: - Search API calls are expensive (quota ~100/unit per call) and may be capped for channels. - local_sort is bounded by max_videos and max_pages.

Safety notes: - Public data only; no private playlists/videos. - No file/network access except YouTube Data API endpoints.

List public playlists for a channel.

Parameters: channel_ref: Same formats as resolve_youtube_channel. page_token: Token for pagination.

Returns: - items: playlist[] (YouTube API playlist resources) - nextPageToken: string | null - quotaEstimate: {estimatedUnits,strategy,notes[]}

Notes: - Public playlists only. - This tool does not list "private" playlists.

List videos in a playlist (public data).

Parameters: playlist_id: YouTube playlist ID (e.g. PL...). page_token: Token for pagination. max_items: Max number of items to include from this page. include_shorts/include_live: Default false; best-effort classification. parts_level: basic/full (same meaning as channel videos).

Returns: - items: video[] - nextPageToken: string | null - quotaEstimate: {estimatedUnits,strategy,notes[]}

Notes: - Playlist ordering is YouTube's playlist ordering.

Search for videos within a channel by keyword (public data).

When to use: Use this tool when you want to find videos by keyword without enumerating the full uploads playlist.

Important: - This tool uses the YouTube Search API (search.list). - Search is quota-expensive (about 100 units per page). - Results may be capped by YouTube API behavior for channel searches.

Pagination: - Read nextPageToken (or next_page_token) from the response. - Pass it back as page_token (or next_page_token) to fetch the next page.

Returns: - items: hydrated video resources (videos.list) - nextPageToken / next_page_token - quotaEstimate

List comment threads for a YouTube video (public comments).

Notes: - Uses commentThreads.list (quota cost ~1 per page). - max_threads is capped to 100 by the API.

Pagination: - Response returns nextPageToken and next_page_token. - Pass it back as page_token (or next_page_token) to fetch the next page.

Returns: - items: commentThread[] (includes top-level comment; replies optional) - nextPageToken / next_page_token - quotaEstimate

Common failure: - If comments are disabled, YouTube may return 403 (commentsDisabled).