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 <noreply@crhq.ai>

Author: therohitdas

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.
 

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

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.
 

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`