From f3ef2e2e64fb7639e305ff134d99e285ec19829a Mon Sep 17 00:00:00 2001 From: therohitdas <43847374+therohitdas@users.noreply.github.com> Date: Mon, 21 Sep 2026 11:41:18 +0000 Subject: [PATCH] docs: capability-first Sorting copy (founder approved) Replaces the defensive Sorting copy with the founder's approved wording across all four places this repo enumerates the endpoint: README tool 8, the SKILL.md bullet (short form, tight surface), references/mcp-tools.md and references/rest-api.md. The members_only and tab=streams / tab=shorts field paragraphs are untouched. Docs only, no version bump. Co-Authored-By: CRHQ --- README.md | 14 ++------------ skills/youtube/SKILL.md | 5 +---- skills/youtube/references/mcp-tools.md | 14 ++------------ skills/youtube/references/rest-api.md | 12 ++---------- 4 files changed, 7 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 28c27d7..07736c0 100644 --- a/README.md +++ b/README.md @@ -391,19 +391,9 @@ List a channel's feed, paginated. Use `tab` to choose the uploads feed (default, | `sort` | string | `null` | `latest`, `popular`, or `oldest`. Omit for the uploads feed. Repeat the same value when paginating. | | `continuation` | string | `null` | Pagination token | -Existing calls are untouched: omitting sort returns the uploads feed exactly as before. sort=latest is a different view (YouTube's Videos tab, Shorts excluded), not a re-ordering of it. +**Sorting.** Add sort=latest, popular, or oldest to channel/videos to get a channel's videos in the order you want, for example its most-popular uploads first. A sorted page returns about 30 videos (an unsorted page returns about 100), and every page costs the same 1 credit. -| | `tab: "videos"`, no `sort` | `tab: "videos"` + any `sort` | -| --- | --- | --- | -| Source | uploads playlist | channel Videos tab | -| Page size | ~100 | ~30 | -| `playlist_info` | populated | `null` | -| Shorts | mixed in | excluded (use `tab: "shorts"`) | -| Members-only videos | excluded | included, flagged `members_only: true` | - -Sort reads ~3.3x more pages (~30/page vs ~100), so it costs ~3.3x credits. Use it when you need ordering; most integrations don't. - -`tab: "shorts"` and `tab: "streams"` read the same feed either way, so there `sort` only reorders. +When paging, send the same sort on each request. Every item carries **`members_only`**: `true` only when YouTube badges the video "Members only", and those items have no `viewCountText`. It is always `false` on the uploads feed, on `tab: "shorts"`, and on playlists. diff --git a/skills/youtube/SKILL.md b/skills/youtube/SKILL.md index 641368d..0a5bde0 100644 --- a/skills/youtube/SKILL.md +++ b/skills/youtube/SKILL.md @@ -95,10 +95,7 @@ Successful calls cost 1 credit unless a tool states otherwise below. Failed and - **`get_channel_latest_videos` is free.** Reach for it first for anything about recent uploads. Use `list_channel_videos` only when the user genuinely wants the whole catalogue. -- `list_channel_videos` takes an optional `sort` (`latest` / `popular` / `oldest`). Existing calls are untouched: omitting sort returns the uploads feed exactly as before. sort=latest is a different view (YouTube's Videos tab, Shorts excluded), not a re-ordering of it. - Omitted reads the uploads playlist (~100/page, Shorts mixed in, members-only videos excluded); - any value reads the channel Videos tab (~30/page, long-form only, members-only videos included - and flagged `members_only`). They are different sets, not one list in two orders. A sorted page holds ~30 items instead of ~100, so paging a whole catalogue with `sort` set costs roughly 3.3x the pages and 3.3x the credits. Omit `sort` when you just want newest-first. +- Sort a channel's videos by latest, popular, or oldest, for example most-popular first. Sorted pages return about 30 videos (unsorted about 100); each page costs 1 credit. When paging, send the same sort on each request. - **Search, then transcribe selectively.** Transcribing a whole page of search results is the single most common way to waste credits. Pick the best 2-3 hits and pull those. - **Search inside a channel** with `search_channel_videos` rather than listing every video and diff --git a/skills/youtube/references/mcp-tools.md b/skills/youtube/references/mcp-tools.md index a51ebd4..4ea6afb 100644 --- a/skills/youtube/references/mcp-tools.md +++ b/skills/youtube/references/mcp-tools.md @@ -168,19 +168,9 @@ or live streams (~48/page), and the optional `sort` to order the Videos tab. | `sort` | string | `null` | `latest`, `popular`, or `oldest`. Omit for the uploads feed. Repeat the same value when paginating. | | `continuation` | string | `null` | Pagination token | -Existing calls are untouched: omitting sort returns the uploads feed exactly as before. sort=latest is a different view (YouTube's Videos tab, Shorts excluded), not a re-ordering of it. +**Sorting.** Add sort=latest, popular, or oldest to channel/videos to get a channel's videos in the order you want, for example its most-popular uploads first. A sorted page returns about 30 videos (an unsorted page returns about 100), and every page costs the same 1 credit. -| | `tab: "videos"`, no `sort` | `tab: "videos"` + any `sort` | -| --- | --- | --- | -| Source | uploads playlist | channel Videos tab | -| Page size | ~100 | ~30 | -| `playlist_info` | populated | `null` | -| Shorts | mixed in | excluded (use `tab: "shorts"`) | -| Members-only videos | excluded | included, flagged `members_only: true` | - -They are different sets, not one list in two orders. A sorted page holds ~30 items instead of ~100, so paging a whole catalogue with `sort` set costs roughly 3.3x the pages and 3.3x the credits. Omit `sort` when you just want newest-first. - -`tab: "shorts"` and `tab: "streams"` read the same feed either way, so there `sort` only reorders. +When paging, send the same sort on each request. Every item carries **`members_only`**: `true` only when YouTube badges the video "Members only", and those items have no `viewCountText`. It is always `false` on the uploads feed, on `tab: "shorts"`, and on playlists. diff --git a/skills/youtube/references/rest-api.md b/skills/youtube/references/rest-api.md index aeb22d4..cd13ca1 100644 --- a/skills/youtube/references/rest-api.md +++ b/skills/youtube/references/rest-api.md @@ -195,17 +195,9 @@ GET /youtube/channel/videos?continuation=TOKEN&sort=popular # repeat tab AND s Provide **exactly one** of `channel` or `continuation`. The response carries `continuation_token` and `has_more`. -Existing calls are untouched: omitting sort returns the uploads feed exactly as before. sort=latest is a different view (YouTube's Videos tab, Shorts excluded), not a re-ordering of it. +**Sorting.** Add sort=latest, popular, or oldest to channel/videos to get a channel's videos in the order you want, for example its most-popular uploads first. A sorted page returns about 30 videos (an unsorted page returns about 100), and every page costs the same 1 credit. -| | `tab=videos`, no `sort` | `tab=videos` + any `sort` | -| --- | --- | --- | -| Source | uploads playlist | channel Videos tab | -| Page size | ~100 | ~30 | -| `playlist_info` | populated | `null` | -| Shorts | mixed in | excluded (use `tab=shorts`) | -| Members-only videos | excluded | included, flagged `members_only: true` | - -They are different sets, not one list in two orders. A sorted page holds ~30 items instead of ~100, so paging a whole catalogue with `sort` set costs roughly 3.3x the pages and 3.3x the credits. Omit `sort` when you just want newest-first. `tab=shorts` / `tab=streams` read the same feed either way; there `sort` only reorders. +When paging, send the same sort on each request. Every item carries `members_only`, `true` only when YouTube badges it "Members only", and those items have no `viewCountText`. `tab=streams` items carry `lengthText` and `publishedTimeText`