docs: channel/videos sort + members_only across the plugin's API surface

All four places this repo enumerates the endpoint now carry it: README tool 8,
the SKILL.md routing table plus credit-hygiene notes, references/mcp-tools.md
and references/rest-api.md.

Each leads with the same framing: existing calls are untouched, and sort=latest
is a different view (the Videos tab, Shorts excluded) rather than a re-ordering
of the uploads feed. Verified empirically on three channels: 0 of the Shorts a
channel publishes appear in any sorted feed, while 43/48 (@ted), 12/40 (@nasa)
and 30/48 (@natgeo) appear in the unsorted uploads feed.

Per-tab field presence recorded honestly: tab=streams carries lengthText and
publishedTimeText, tab=shorts returns null for both, and the channel-tab feeds
null out channelId/channelTitle/channelHandle/index.

Docs only, no version bump.

Co-Authored-By: CRHQ <noreply@crhq.ai>

Author: therohitdas

README.md

@@ -382,14 +382,33 @@ Search inside one specific channel for videos matching a query.
 
 ### 8. `list_channel_videos`
 
-List a channel's feed, paginated. Use `tab` to choose the uploads feed (default, ~100/page), Shorts, or live streams (~48/page). Ideal for building databases or bulk transcript extraction.
+List a channel's feed, paginated. Use `tab` to choose the uploads feed (default, ~100/page), Shorts, or live streams (~48/page), and the optional `sort` to order the Videos tab by latest, popular, or oldest. Ideal for building databases or bulk transcript extraction.
 
 | Parameter      | Type   | Default      | Description                          |
 | -------------- | ------ | ------------ | ------------------------------------ |
 | `channel`      | string | **required** (first call) | `@handle`, channel URL, or `UC…` ID |
 | `tab`          | string | `"videos"`   | `videos` (uploads), `shorts`, or `streams`. Repeat the same `tab` when paginating. |
+| `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.
+
+| | `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.
+
+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.
+
+Items from `tab: "streams"` carry `lengthText` and `publishedTimeText` (for example `Streamed 2 years ago`, or `LIVE` and a watching count while live). `tab: "shorts"` returns `null` for both, because YouTube's Shorts grid publishes neither. On the channel-tab feeds, `channelId`, `channelTitle`, `channelHandle` and `index` are `null`.
+
 **Cost:** 1 credit per page.
 
 ### 9. `list_channel_playlists`

skills/youtube/SKILL.md

@@ -59,6 +59,7 @@ credits, no card.
 | What a creator posted recently | `get_channel_latest_videos` | `GET /youtube/channel/latest` | **free** |
 | Find something inside one channel | `search_channel_videos` | `GET /youtube/channel/search` | 1 / page |
 | A channel's entire upload history, Shorts, or live streams | `list_channel_videos` | `GET /youtube/channel/videos` | 1 / page |
+| A channel's back catalogue ranked by views, or walked oldest-first | `list_channel_videos` + `sort` | `GET /youtube/channel/videos?sort=` | 1 / page |
 | The playlists on a channel | `list_channel_playlists` | `GET /youtube/channel/playlists` | 1 / page |
 | A channel's community posts | `list_channel_posts` | `GET /youtube/channel/posts` | 1 / page |
 | A channel's curated Home/podcasts/releases shelves | `get_channel_sections` | `GET /youtube/channel/sections` | 1 |
@@ -94,6 +95,10 @@ 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.
 - **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

@@ -159,14 +159,33 @@ Always better than listing a whole channel and filtering client-side.
 ## `list_channel_videos`: 1 credit per page
 
 A channel's feed, paginated. Use `tab` to choose the uploads feed (default, ~100/page), Shorts,
-or live streams (~48/page).
+or live streams (~48/page), and the optional `sort` to order the Videos tab.
 
 | Parameter | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `channel` | string | **required** (first call) | `@handle`, channel URL, or `UC…` ID |
 | `tab` | string | `"videos"` | `videos` (uploads), `shorts`, or `streams`. Repeat the same `tab` when paginating. |
+| `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.
+
+| | `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.
+
+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.
+
+Items from `tab: "streams"` carry `lengthText` and `publishedTimeText` (for example `Streamed 2 years ago`, or `LIVE` and a watching count while live). `tab: "shorts"` returns `null` for both, because YouTube's Shorts grid publishes neither. On the channel-tab feeds, `channelId`, `channelTitle`, `channelHandle` and `index` are `null`.
+
 Only when the user genuinely wants the whole catalogue. For recent uploads use
 `get_channel_latest_videos` (free); to find something specific use `search_channel_videos`.
 

skills/youtube/references/rest-api.md

@@ -179,20 +179,40 @@ Returns exact `viewCount` and ISO `published` timestamps.
 ### Channel videos (paginated): 1 credit per page
 
 ```http
-GET /youtube/channel/videos?channel=@NASA          # first page, ~100 videos
+GET /youtube/channel/videos?channel=@NASA               # first page, ~100 videos
 GET /youtube/channel/videos?channel=@NASA&tab=shorts
-GET /youtube/channel/videos?continuation=TOKEN     # subsequent pages
+GET /youtube/channel/videos?channel=@NASA&sort=popular  # Videos tab, most-viewed first, ~30
+GET /youtube/channel/videos?continuation=TOKEN&sort=popular   # repeat tab AND sort
 ```
 
 | Param | Required | Default | Values |
 | --- | --- | --- | --- |
 | `channel` | conditional | - | first page only |
 | `tab` | no | `videos` | `videos` (uploads), `shorts`, `streams`. Repeat the same `tab` when paginating. |
+| `sort` | no | - | `latest`, `popular`, `oldest`. Omit for the uploads feed. Repeat the same value when paginating. |
 | `continuation` | conditional | - | subsequent pages |
 
 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.
+
+| | `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.
+
+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`
+(for example `Streamed 2 years ago`); `tab=shorts` returns `null` for both, because YouTube's
+Shorts grid publishes neither. On the channel-tab feeds, `channelId`, `channelTitle`,
+`channelHandle` and `index` are `null`.
+
 ### Search within a channel: 1 credit per page
 
 ```http
@@ -283,6 +303,7 @@ Free endpoints still require an active plan with at least one credit available.
 | `q` | 1-200 characters |
 | `type` (search) | `video`, `channel`, `playlist`, `movie` |
 | `tab` (channel/videos) | `videos`, `shorts`, `streams` |
+| `sort` (channel/videos) | `latest`, `popular`, `oldest` (omit for the uploads feed) |
 | `tab` (channel/sections) | `featured`, `podcasts`, `releases` |
 
 ## Worked example: research workflow