YouTube Studio MCP

Overview Schema Source Related Servers Discussions Admin

List videos

list_videos

Read-onlyIdempotent

Lists a channel's uploads, including private, unlisted, and scheduled videos, with public views, likes, comments, engagement, duration, and format stats for channel performance review.

Instructions

List the channel's uploads (including private/unlisted/scheduled, newest first) with public lifetime stats: views, likes, comments, engagement rate, duration, format guess. Costs ~1 quota unit per 50 videos. For period-specific performance use get_top_videos.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_videos"
  }
}

Input Schema

Name	Required	Description	Default
`limit`	No	Maximum videos to return.
`save_to`	No	Optional file to also save the rows to (.csv or .json). A bare filename goes in the output directory; absolute paths are allowed.
`sort_by`	No	Order of the returned videos (sorting happens over the scanned uploads).	newest
`playlist_id`	No	List this playlist instead of the channel's uploads.
`content_format`	No	Filter by format using public metadata: 'short' = up to 3 minutes (likely Shorts), 'video' = longer uploads, 'live' = live streams/premieres.
`title_contains`	No	Case-insensitive title filter.
`published_after`	No	Only videos published on/after YYYY-MM-DD.
`published_before`	No	Only videos published on/before YYYY-MM-DD.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 11, 2026

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so safety is covered; the description adds genuinely new behavior: quota economics (~1 unit per 50 videos), the fact that sorting happens over scanned uploads, and that private/unlisted/scheduled items are included. It does not state whether private items require authorization or how far back the scan reaches, which would have pushed this higher.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with scope and payload, then cost, then the alternative. Dense but no sentence is wasted; the payload enumeration is slightly list-heavy but earns its space by telling the agent what stats come back.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 8 optional parameters, full schema coverage, an output schema, and rich annotations, the description covers scope, cost, and tool selection. The only meaningful gaps are authorization requirements for private content and any scan-depth/latency limits, both minor against the structured data already supplied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and every parameter (limit, save_to, sort_by, playlist_id, content_format, title_contains, published_after/before) is documented at the field level. The description mentions only the default 'newest first' ordering, adding nothing beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (list the channel's uploads), the privacy scope (private/unlisted/scheduled), the ordering default, and the returned payload (views, likes, comments, engagement rate, duration, format guess). It also names the sibling it is not, get_top_videos, so the agent can separate the two without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes period-specific performance questions to get_top_videos, which is clear positive guidance. It does not say when this tool is a poor choice in other cases, such as when deep per-video detail is needed (get_videos_details) or when only totals are wanted, so the exclusion set is partial.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.