Skip to content

docs: capability-first Sorting copy (founder approved) #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
therohitdas merged 1 commit into from
Sep 21, 2026
Merged

docs: capability-first Sorting copy (founder approved) #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 2 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
5 changes: 1 addition & 4 deletions skills/youtube/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 2 additions & 12 deletions skills/youtube/references/mcp-tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
12 changes: 2 additions & 10 deletions skills/youtube/references/rest-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
Loading