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

The live /channel/videos (and the list_channel_videos MCP tool) gained an
opt-in sort=latest|popular|oldest and an additive members_only on every item.
All four places this plugin enumerates that surface now carry it: README tool
8, the SKILL.md routing table + credit-hygiene notes, references/mcp-tools.md
and references/rest-api.md.

Each one leads with the sharp edge: omitting sort is NOT the same as
sort=latest, because the two read different YouTube feeds (uploads playlist
~100/page with Shorts mixed in and members-only excluded, vs the Videos tab
~30/page long-form only with members-only included). Different sets, and
~3.3x the credits to crawl.

Per-tab field presence is stated honestly, verified live on @ted / @nasa /
@natgeo: tab=streams carries lengthText + publishedTimeText, tab=shorts
returns null for both, and the channel-tab feeds null out
channelId/channelTitle/channelHandle/index.

Docs only — no version bump applied.

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

Author: therohitdas

README.md

@@ -382,14 +382,31 @@ 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                     |
 
+**Sorting is opt-in, and omitting `sort` is not the same as `sort: "latest"`** — the two read different YouTube feeds:
+
+| | `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 crawling 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 — 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,12 @@ 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`). It is opt-in,
+  and omitting it is **not** the same as `sort: "latest"`: 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`).
+  Different sets, not one list in two orders, and ~3.3x the credits to crawl — so omit `sort` for
+  newest-first, and reach for it only when the user wants most-viewed or oldest-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,31 @@ 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 |
 
+**Sorting is opt-in, and omitting `sort` is not the same as `sort: "latest"`** — the two read different YouTube feeds:
+
+| | `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 crawling 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 — 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,43 @@ 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`.
 
+**`sort` is opt-in, and omitting it is not the same as `sort=latest`** — the two read different
+YouTube feeds:
+
+| | `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` |
+
+Different *sets*, not one list in two orders — and a sorted crawl costs ~3.3x the pages and
+credits, so omit `sort` for the cheapest newest-first crawl. `tab=shorts` / `tab=streams` read
+the same feed either way; there `sort` only reorders.
+
+Every item carries `members_only` (`true` only on YouTube's "Members only" badge; 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 +306,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