Which integrations are available for this server?

Provides tools for YouTube channel intelligence, video analysis, niche discovery, and content strategy, enabling AI agents to audit channels, analyze videos, rank niche opportunities, and score titles using the YouTube Data API v3.

How do I use YouTube MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@YouTube MCP Server audit @mkbhd's channel" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

YouTube MCP Server

by CodingWithShahzaib

Overview Schema Related Servers Score Discussions

TypeScript

Local

YouTube MCP Server

A Model Context Protocol (MCP) server that exposes YouTube channel intelligence, video analysis, niche discovery, and content strategy tools to AI assistants such as Cursor, Claude Desktop, and other MCP-compatible clients.

Built for creator workflows: audit channels, benchmark videos, discover niches, score titles, and analyze transcripts — all through structured, agent-friendly JSON responses.

Version: 0.1.0 · Node.js: >= 20 · Transport: stdio

Related MCP server: mcp-server-youtube

Why This Exists

YouTube creator research usually means juggling the Data API, spreadsheets, and ad-hoc scripts. This server wraps that work into a consistent MCP tool surface so an AI agent can:

Resolve messy inputs (@handle, video URLs, channel IDs) into canonical records
Fetch channel and video metadata with quota-aware caching
Run opinionated analysis (channel audits, niche scoring, title packaging)
Return predictable JSON envelopes that agents can reason over reliably

Every tool response includes data, summary, sources, and warnings so downstream workflows stay auditable.

Features

Category	Capabilities
Operations	Health checks, auth status, quota tracking, cache statistics
Channels	Resolve identifiers, fetch profiles, list recent uploads
Videos	Details, batch lookup, search, performance snapshots, thumbnails
Strategy	Full channel audits, niche opportunity ranking
Content	Transcript analysis (user-provided text), title scoring

v0.1 Tool Inventory (17 tools)

Tool	Description
`youtube.healthcheck`	Server readiness, API reachability, schema version
`youtube.auth.status`	API key and OAuth configuration status
`youtube.quota.status`	Daily quota usage by endpoint
`youtube.cache.status`	Cache size, hit rate, stale entries

Tool	Description
`youtube.channel.resolve`	Resolve URL, handle, ID, or video URL → channel
`youtube.channel.get_profile`	Title, stats, thumbnails, branding metadata
`youtube.channel.get_uploads`	Recent upload IDs via uploads playlist
`youtube.video.get_details`	Metadata, stats, duration, thumbnails
`youtube.video.batch_get_details`	Batch lookup (up to 50 videos)
`youtube.video.search`	Keyword search with filters
`youtube.video.performance_snapshot`	Views/day, engagement rate, packaging metrics
`youtube.thumbnail.get`	All thumbnail variants and dimensions

Tool	Description
`youtube.strategy.channel_audit`	Upload cadence, outliers, title patterns
`youtube.niche.find`	Rank niche opportunities from seed topics
`youtube.transcript.get`	Transcript retrieval (provided text mode)
`youtube.transcript.analyze`	Hook, structure, CTA, repurpose signals
`youtube.packaging.analyze_title`	Title clarity, curiosity, length scoring

Architecture

flowchart TB
    subgraph Client["MCP Client"]
        Cursor["Cursor / Claude / Inspector"]
    end

    subgraph Server["youtube-mcp-server"]
        MCP["MCP Server (stdio)"]
        Registry["Tool Registry"]
        Analyzer["Channel Analyzer"]
        MCP --> Registry
        Registry --> Analyzer
    end

    subgraph Services["YouTube Layer"]
        ChannelSvc["Channel Service"]
        VideoSvc["Video Service"]
        Client_YT["YouTube Client"]
        Registry --> ChannelSvc
        Registry --> VideoSvc
        ChannelSvc --> Client_YT
        VideoSvc --> Client_YT
        Analyzer --> ChannelSvc
        Analyzer --> VideoSvc
    end

    subgraph Storage["Persistence"]
        Cache["SQLite API Cache"]
        Quota["SQLite Quota Tracker"]
        Client_YT --> Cache
        Client_YT --> Quota
    end

    subgraph External["External"]
        API["YouTube Data API v3"]
        Client_YT --> API
    end

    Cursor <-->|stdio| MCP

Design principles

Stdio transport — runs as a subprocess; no HTTP server to deploy
Zod validation — strict input schemas on every tool call
SQLite persistence — response cache and quota ledger share one database file
Quota guardrails — pre-flight checks before each API call; configurable daily budget
Structured envelopes — uniform { data, summary, sources, warnings } responses

Prerequisites

Node.js 20+ — nodejs.org
YouTube Data API v3 key — from Google Cloud Console

Obtaining a YouTube API Key

Create or select a Google Cloud project
Enable YouTube Data API v3 under APIs & Services → Library
Go to APIs & Services → Credentials → Create Credentials → API Key
Restrict the key to YouTube Data API v3 (recommended for production)
Copy the key into your environment (see Configuration)

Note: Default Google Cloud quota is 10,000 units/day. This server defaults to a 9,000 unit soft limit to leave headroom.

Quick Start

# Clone and install
git clone <your-repo-url> youtube-mcp-server
cd youtube-mcp-server
npm install

# Configure credentials
cp .env.example .env
# Edit .env and set YOUTUBE_API_KEY=your-key-here

# Build and verify
npm run build
npm test

Verify the server with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Then invoke youtube.healthcheck and youtube.channel.resolve with:

{ "input": "@mkbhd" }

MCP Client Setup

The server communicates over stdio. Point your MCP client at the built entry point (dist/index.js) or the dev runner (tsx src/index.ts).

Cursor

Add to ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json):

Production (compiled)

{
  "mcpServers": {
    "youtube": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-mcp-server/dist/index.js"],
      "env": {
        "YOUTUBE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Development (hot reload via tsx)

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/youtube-mcp-server/src/index.ts"],
      "env": {
        "YOUTUBE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent path on your OS:

{
  "mcpServers": {
    "youtube": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-mcp-server/dist/index.js"],
      "env": {
        "YOUTUBE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using a `.env` file

The server auto-loads .env from the project root when present. If your MCP config launches the server from the project directory, you can omit inline env keys and rely on the file instead:

YOUTUBE_API_KEY=your-api-key-here
CACHE_DB_PATH=./data/cache.db

Environment variables set in the MCP client config take precedence over .env values already in process.env; unset keys fall through to .env.

Configuration

Variable	Required	Default	Description
`YOUTUBE_API_KEY`	Yes	—	YouTube Data API v3 key
`CACHE_DB_PATH`	No	`./data/cache.db`	SQLite database for cache + quota
`MAX_DAILY_QUOTA_UNITS`	No	`9000`	Soft daily quota budget
`CACHE_TTL_CHANNEL_HOURS`	No	`24`	TTL for channel/profile cache
`CACHE_TTL_VIDEO_HOURS`	No	`12`	TTL for video detail cache
`CACHE_TTL_SEARCH_HOURS`	No	`6`	TTL for search result cache
`TRANSCRIPT_MODE`	No	`provided_text`	Comma-separated transcript modes
`PUBLIC_TRANSCRIPT_ADAPTER_ENABLED`	No	`false`	Enable public transcript adapter
`GOOGLE_CLIENT_ID`	No	—	OAuth client ID (future caption support)
`GOOGLE_CLIENT_SECRET`	No	—	OAuth client secret
`GOOGLE_REDIRECT_URI`	No	—	OAuth redirect URI

Copy .env.example as a starting point:

cp .env.example .env

Tool Reference

All tools accept JSON arguments and return a structured response. Use forceRefresh: true to bypass cache when you need live data (consumes quota).

Operational

// youtube.healthcheck
{}

// youtube.quota.status
{}

Channel resolution & profiles

// youtube.channel.resolve
{ "input": "@mkbhd" }
{ "input": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }

// youtube.channel.get_profile
{ "channel": "@mkbhd", "forceRefresh": false }

// youtube.channel.get_uploads
{ "channel": "UC...", "maxResults": 25, "pageToken": null }

Accepted channel identifiers: @handle, channel URL, UC... channel ID, custom URL, or a video URL (resolved to its channel).

Video lookup & search

// youtube.video.get_details
{ "video": "dQw4w9WgXcQ", "includeTags": true }

// youtube.video.batch_get_details
{ "videos": ["id1", "id2", "https://youtu.be/id3"], "includeTags": false }

// youtube.video.search
{
  "query": "home gym setup",
  "maxResults": 10,
  "order": "viewCount",
  "type": "video",
  "regionCode": "US",
  "videoDuration": "medium",
  "recency": "pastMonth"
}

// youtube.video.performance_snapshot
{ "video": "dQw4w9WgXcQ" }

// youtube.thumbnail.get
{ "video": "dQw4w9WgXcQ" }

Search order values: relevance, date, viewCount, rating

Search recency values: any, pastHour, pastDay, pastWeek, pastMonth, pastQuarter, pastYear

Strategy & content analysis

// youtube.strategy.channel_audit
{ "channel": "@mkbhd", "maxVideos": 25 }

// youtube.niche.find
{
  "seedTopics": ["minimalist desk setup", "standing desk review"],
  "regionCode": "US",
  "maxResults": 10
}

// youtube.transcript.get (provided text)
{
  "mode": "provided_text",
  "transcriptText": "Welcome back to the channel...",
  "language": "en"
}

// youtube.transcript.analyze
{
  "transcriptText": "In this video we cover...",
  "analysisTypes": ["hook", "structure", "cta", "repurpose"]
}

// youtube.packaging.analyze_title
{ "title": "I Tried Every Standing Desk Under $300" }

Channel audit output highlights

youtube.strategy.channel_audit returns:

Upload cadence — videos/week, consistency score, average gap between uploads
Performance — median views, average views/day, engagement rate, outlier count
Top videos — highest-performing uploads with engagement metrics
Outlier videos — uploads exceeding 2× channel median views
Title patterns — average length, common words, detected formulas
Thumbnail availability — coverage across analyzed uploads

Niche scoring

youtube.niche.find searches each seed topic, samples top results, and scores opportunities using demand and competition proxies. Results are ranked by overallScore.

Response Format

Successful tool calls return JSON text with this envelope:

{
  "data": { },
  "summary": "Human-readable one-liner for the agent",
  "sources": [
    {
      "type": "youtube_api",
      "endpoint": "channels.list",
      "url": "https://www.youtube.com/@mkbhd",
      "timestamp": "2026-07-07T12:00:00.000Z"
    }
  ],
  "warnings": []
}

Errors return a separate JSON object with isError: true:

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Daily quota limit reached (9000/9000 units used)",
    "retryable": true
  }
}

Error codes

Code	Retryable	Meaning
`QUOTA_EXCEEDED`	Yes	Daily soft limit or Google quota hit
`TRANSCRIPT_UNAVAILABLE`	No	Requested transcript mode not available
`UNKNOWN_TOOL`	No	Tool name not registered
`INTERNAL_ERROR`	No	Unexpected server error

Quota & Caching

Quota costs (estimated units per call)

Endpoint	Cost
`channels.list`	1
`videos.list`	1
`playlistItems.list`	1
`playlists.list`	1
`search.list`	100
`captions.list`	50
`commentThreads.list`	1

The quota tracker records usage in SQLite and enforces MAX_DAILY_QUOTA_UNITS before each request. Check status anytime:

// youtube.quota.status →
{
  "dailyLimit": 9000,
  "usedToday": 342,
  "remaining": 8658,
  "byEndpoint": { "search.list": 300, "videos.list": 42 },
  "date": "2026-07-07"
}

Caching behavior

Responses are keyed by endpoint + normalized request parameters (SHA-256 hash)
TTLs are configurable per resource type (channel, video, search)
Stale entries are returned as cache misses and refreshed on next call
forceRefresh: true skips cache reads (still records quota on API hit)

Tips for quota efficiency

Prefer youtube.video.batch_get_details over repeated get_details calls
Use youtube.channel.get_profile before re-fetching the same channel
Treat youtube.video.search as expensive (~100 units each)
Run youtube.niche.find with fewer seed topics during development
Monitor with youtube.quota.status and youtube.cache.status

Transcript Modes

Official YouTube caption download requires OAuth and (for most captions) video owner permissions. v0.1 supports:

Mode	Status	Description
`provided_text`	Supported	User pastes transcript text for analysis
`owner_oauth`	Planned	OAuth-based owner caption access
`public_adapter`	Disabled	Third-party public transcript adapter
`speech_to_text`	Planned	Audio → text pipeline

Configure enabled modes via TRANSCRIPT_MODE (comma-separated). Every transcript response includes provenance metadata.

Example workflow

Copy transcript text manually (or from your own pipeline)
Call youtube.transcript.get with mode: "provided_text"
Pass the text to youtube.transcript.analyze for hook/structure/CTA insights

Development

# Run server directly (stdio — intended for MCP clients)
npm run dev

# Type-check
npm run typecheck

# Build for production
npm run build
npm start

NPM scripts

Script	Description
`npm run dev`	Start via `tsx` (no build step)
`npm run build`	Compile TypeScript → `dist/`
`npm start`	Run compiled `dist/index.js`
`npm test`	Run Vitest unit tests
`npm run typecheck`	`tsc --noEmit`

Tech stack

Runtime: Node.js 20+, ESM ("type": "module")
MCP SDK: @modelcontextprotocol/sdk
Validation: Zod
Storage: better-sqlite3
Testing: Vitest

Testing

npm test

Unit tests cover identifier parsing (@handle, URLs, channel IDs), duration/engagement utilities, title scoring, and transcript analysis heuristics.

Troubleshooting

Symptom	Likely cause	Fix
`YOUTUBE_API_KEY is required`	Missing API key	Set in `.env` or MCP `env` block
`QUOTA_EXCEEDED`	Daily limit hit	Wait for reset (midnight Pacific) or raise `MAX_DAILY_QUOTA_UNITS`
`YouTube API error (403)`	API not enabled or key restricted	Enable YouTube Data API v3; check key restrictions
Server starts but tools fail	Wrong working directory	Use absolute paths in MCP config `args`
Empty search results	Overly narrow filters	Relax `recency`, `videoDuration`, or `regionCode`
`TRANSCRIPT_UNAVAILABLE`	Unsupported mode	Use `provided_text` with `transcriptText`
Cache shows stale entries	Normal TTL expiry	Stale entries refresh on next miss; or use `forceRefresh`

Debug with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Inspect raw tool inputs/outputs, list registered tools, and verify API connectivity without an IDE.

Project Structure

youtube-mcp-server/
├── src/
│   ├── index.ts              # Entry point, .env loader
│   ├── server/
│   │   ├── mcpServer.ts      # MCP server + stdio transport
│   │   ├── toolRegistry.ts   # Tool handlers + definitions
│   │   └── schemas.ts        # Zod input schemas
│   ├── youtube/
│   │   ├── youtubeClient.ts  # API client, cache, quota integration
│   │   ├── channelService.ts # Channel resolve, profile, uploads
│   │   ├── videoService.ts   # Video details, search, snapshots
│   │   └── quotaTracker.ts   # Daily quota ledger
│   ├── analysis/
│   │   └── channelAnalyzer.ts # Audits, niche scoring, title/transcript analysis
│   ├── storage/
│   │   └── cache.ts          # SQLite response cache
│   ├── config/
│   │   ├── env.ts            # Environment validation
│   │   └── defaults.ts       # Quota costs, schema version
│   ├── utils/
│   │   ├── ids.ts            # URL/ID parsing
│   │   ├── duration.ts       # ISO duration, engagement math
│   │   └── response.ts       # Response envelope helpers
│   └── tests/
│       └── unit/             # Vitest unit tests
├── .env.example
├── package.json
├── tsconfig.json
└── vitest.config.ts

Roadmap

v0.1 ships 17 tools. A broader roadmap (53+ tools) is documented separately, including:

OAuth-based owner caption download
Thumbnail vision analysis
Competitor comparison reports
Export and reporting utilities

See the parent YouTube MCP Server Build Plan for the full phased rollout.

Security

Never commit .env, API keys, or *.db files — they are gitignored
Restrict your API key to YouTube Data API v3 and (optionally) specific IPs
Prefer MCP env injection or OS-level secrets over hardcoding keys in config files shared via git
Quota limits are enforced server-side, but Google Cloud quotas are the ultimate ceiling
OAuth credentials (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET) are optional and only needed for future caption features

Available Tools

17 tools

youtube.auth.statusA

Show whether API key and OAuth are configured

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.5/5.0

Behavior2/5

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

No annotations provided, so description carries full burden. It only states what the tool shows, with no disclosure of behavioral traits like network calls, authentication requirements, or side effects.

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

Conciseness5/5

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

Single sentence with no wasted words. Structure is appropriately front-loaded and efficient.

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

Completeness3/5

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

For a simple status tool with no parameters or output schema, the description is adequate but lacks specification of output format or additional context (e.g., what API key and OAuth status values look like).

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

Parameters4/5

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

Tool has zero parameters, so schema coverage is 100%. Description adds no parameter information, but baseline for no parameters is appropriate.

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?

Description clearly states the tool shows whether API key and OAuth are configured. Verb 'Show' and specific resource make purpose unambiguous, distinguishing it from sibling status tools like cache, quota, healthcheck.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. Among siblings, there are other status tools, but the description provides no context for selection.

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

youtube.cache.statusA

Show cache size, freshness, hit rate, and stale records

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.6/5.0

Behavior2/5

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

No annotations are provided, and the description only lists the metrics shown. It does not disclose behavioral traits such as whether the tool is read-only, permissions required, or any side effects. With no annotation support, the description should provide more context.

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

Conciseness5/5

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

Description is a single, well-structured sentence that lists the key metrics without unnecessary words. It is front-loaded and efficient.

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 the tool has no parameters, no output schema, and is a simple status check, the description is fairly complete. It covers the main aspects, though it could specify units or format of the metrics for full completeness.

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

Parameters4/5

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

There are zero parameters, so the description does not need to add parameter details. Baseline score of 4 is appropriate as it neither adds nor detracts from the schema.

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?

Description clearly states the tool shows cache metrics (size, freshness, hit rate, stale records). It uses a specific verb (Show) and resource (cache status), effectively distinguishing it from sibling status tools like youtube.auth.status and youtube.quota.status.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives or prerequisites. The description does not explain context or exclusions for usage.

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

youtube.channel.get_profileB

Fetch channel title, description, statistics, thumbnails, and branding metadata

ParametersJSON Schema

Name	Required	Description	Default
`channel`	Yes
`forceRefresh`	No

TDQS

B3.1/5.0

Behavior2/5

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

No annotations present; description lacks details on behavior such as authentication requirements, rate limits, or effects of forceRefresh parameter.

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

Conciseness5/5

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

Single sentence with clear front-loading of verb and resource; no extraneous words.

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

Completeness2/5

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

For a tool with 2 undocumented parameters and no output schema, the description is insufficient; it omits input format details and refresh semantics.

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

Parameters1/5

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

Schema has zero description coverage and the tool description does not explain what the 'channel' parameter expects (ID vs handle) or the purpose of 'forceRefresh'.

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?

The description uses a specific verb ('Fetch') and resource ('channel title, description, statistics, thumbnails, and branding metadata'), clearly differentiating from sibling tools like get_uploads.

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

Usage Guidelines3/5

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

Implicitly indicates fetching profile data, but no explicit when-to-use or comparison with alternative channel tools.

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

youtube.channel.get_uploadsC

Fetch recent uploads through the channel uploads playlist

ParametersJSON Schema

Name	Required	Description	Default
`channel`	Yes
`pageToken`	No
`maxResults`	No
`forceRefresh`	No

TDQS

C2.8/5.0

Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It merely states the action but omits details like pagination, that it uses a specific playlist, or that results may be limited.

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?

Single sentence is concise and front-loaded, but could be structured to include more critical information without increasing length significantly.

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

Completeness2/5

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

For a tool with 4 params, no output schema, and no annotations, the description is too brief. It lacks explanation of return format, pagination, and behavior of 'forceRefresh'.

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

Parameters1/5

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

Schema coverage is 0% (no parameter descriptions in schema) and the description adds no meaning to parameters. It fails to explain 'channel', 'pageToken', 'maxResults', or 'forceRefresh'.

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?

The description uses specific verb 'Fetch' and resource 'recent uploads through channel uploads playlist', clearly distinguishing it from sibling tools like 'get_profile' and 'resolve'.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like 'video.search' or 'get_details'. No context on prerequisites or exclusions.

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

youtube.channel.resolveA

Resolve channel URL, handle, custom URL, channel ID, or video URL to canonical channel ID

ParametersJSON Schema

Name	Required	Description	Default
`input`	Yes	Channel URL, @handle, channel ID, or video URL

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses that the tool resolves to a canonical channel ID, which is a read-only transformation. No side effects or limitations are mentioned, but the behavior is straightforward.

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

Conciseness5/5

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

The description is a single, concise sentence with no superfluous words. It efficiently communicates the tool's function.

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?

The tool has only one parameter and a simple resolution function. However, with no output schema, the description does not specify the return format, which would be helpful. Overall, it is mostly complete for the task.

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 coverage is 100% with a single parameter described as 'Channel URL, @handle, channel ID, or video URL'. The description reinforces this but does not add new meaning beyond the schema, so baseline 3 is appropriate.

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?

The description clearly states the verb 'resolve' and the resource 'channel URL, handle, custom URL, channel ID, or video URL to canonical channel ID'. It distinguishes from sibling tools like get_profile which require an already-resolved channel ID.

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?

The description implicitly indicates that this tool is used when you have a non-canonical identifier and need a channel ID. It does not explicitly state when not to use it or mention alternatives, but the context is clear given sibling tool names.

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

youtube.healthcheckC

Server readiness, dependency status, API reachability, and schema version

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations, the description must disclose all behavioral traits. It lists the checks performed but fails to state that the tool is read-only, whether it requires authentication, or if any side effects occur. The description is insufficient for an agent to understand the tool's safety profile.

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

Conciseness3/5

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

The description is a single sentence listing items without any structure or emphasis. While it is concise, it could be better organized (e.g., using bullet points) for clarity and scanability.

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

Completeness2/5

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

Given the lack of output schema and annotations, the description should provide more context about the return format or typical output. It omits any mention of what the tool returns (e.g., a status object), making it incomplete for an agent to use effectively.

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

Parameters4/5

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

The tool has no parameters, and the schema coverage is 100% (empty). The description does not need to add parameter details. The baseline for zero parameters is 4, and this is met.

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

Purpose4/5

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

The description explicitly lists the four aspects checked: server readiness, dependency status, API reachability, and schema version. It clearly states the tool's purpose as a health check, distinguishing it from more specific sibling tools like youtube.auth.status or youtube.quota.status.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus its siblings. It does not explain that it offers a consolidated status view compared to individual status tools, nor does it mention any prerequisites or conditions.

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

youtube.niche.findC

Rank niche opportunities from seed topics using search demand and competition proxies

ParametersJSON Schema

Name	Required	Default
`maxResults`	No
`regionCode`	No	US
`seedTopics`	Yes

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, so the description must fully disclose behavior. It mentions using 'search demand and competition proxies' but does not explain what these mean, how ranking works, or any side effects, authentication needs, or rate limits. The description lacks behavioral depth.

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?

The description is a concise single sentence with no unnecessary words. It is efficiently structured but could benefit from additional sentences to cover key details without becoming verbose.

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

Completeness2/5

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

Given no output schema and three parameters, the description is incomplete. It does not describe the output format, ranking criteria, or how to interpret results. The tool's complexity is moderate, and the description leaves many unknowns for the AI agent.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must add meaning beyond the schema. It implies the 'seedTopics' parameter but does not explain 'maxResults' or 'regionCode'. No parameter descriptions are given, leaving the agent to infer usage from names alone.

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?

The description clearly states the verb 'rank' and resource 'niche opportunities', and specifies inputs as 'seed topics' and method 'using search demand and competition proxies'. It distinguishes itself from sibling tools like youtube.video.search or youtube.channel.get_profile by focusing on niche opportunity ranking.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. Does not specify prerequisites, when not to use, or mention sibling tools for similar tasks. The description only states what it does.

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

youtube.packaging.analyze_titleC

Score a title by clarity, curiosity, specificity, length, and detected formula

ParametersJSON Schema

Name	Required	Description	Default
`title`	Yes

TDQS

C2.8/5.0

Behavior2/5

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

No annotations exist, so the description must carry the full burden. It lists scoring criteria but does not disclose whether the tool is safe (read-only), destructive, or has side effects. It also omits any description of the output format or behavioral traits.

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?

The description is a single concise sentence. However, it could be slightly improved by front-loading the output type or adding a brief example.

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

Completeness2/5

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

Given the tool has no output schema and no annotations, the description is incomplete. It fails to explain what the score looks like (e.g., number, object), when to use it, or any prerequisites.

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

Parameters1/5

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

Schema description coverage is 0%. The description adds no meaning beyond the schema for the single parameter 'title'. It does not explain format, constraints, or examples.

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?

The description clearly states the verb 'Score' and the resource 'title', with specific criteria (clarity, curiosity, specificity, length, detected formula). It is unique among sibling tools, which include auth, channel, video tools, none of which perform title scoring.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. The description implies it is for evaluating titles, but no explicit when-to-use or when-not-to-use context is provided.

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

youtube.quota.statusA

Show estimated YouTube API quota usage by endpoint and day

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.6/5.0

Behavior2/5

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

No annotations are provided, so the description fully bears the responsibility. It only says 'show', implying read-only behavior, but fails to disclose whether the tool itself consumes quota, how often data updates, or authentication requirements.

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

Conciseness5/5

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

A single sentence that front-loads the action and output format with no extraneous information.

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

Completeness2/5

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

No output schema is provided, and the description does not describe the return format (e.g., JSON structure, table) or any additional details about the data, leaving the agent uncertain about what to expect.

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

Parameters4/5

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

With zero parameters, the schema fully covers them. The description adds context by mentioning 'by endpoint and day', which helps understand the output grouping. Baseline 4 is appropriate.

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?

The description clearly states the tool shows estimated YouTube API quota usage, specifying grouping by endpoint and day. This clearly distinguishes it from sibling tools like youtube.auth.status or youtube.video.search.

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

Usage Guidelines3/5

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

The description implies the tool is for checking quota usage, but does not explicitly state when to use it versus alternatives, nor does it provide context on prerequisites or limitations.

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

youtube.strategy.channel_auditB

Channel audit with upload cadence, top videos, outliers, title patterns, and thumbnail availability

ParametersJSON Schema

Name	Required	Description	Default
`channel`	Yes
`maxVideos`	No
`forceRefresh`	No

TDQS

B3.2/5.0

Behavior2/5

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

No annotations are provided, so the description must carry the behavioral disclosure burden. It lists output components but omits side effects (e.g., API quota usage, caching behavior despite a forceRefresh parameter, or any destructive actions). The description does not contradict any annotations as none exist.

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?

The description is a single concise sentence that front-loads key terms. While it could be more structured (e.g., bullet points), it is efficient and contains no unnecessary words.

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

Completeness2/5

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

Given the lack of an output schema, the description should explain the return format or structure of the audit results. It lists what aspects are covered but does not describe the output shape (e.g., a report object, list of videos, or data fields). This is incomplete for a complex analysis tool.

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

Parameters2/5

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

Schema description coverage is 0%, so parameter descriptions are missing entirely. The tool description adds no information about parameters (channel, maxVideos, forceRefresh) beyond their names, which are partially self-explanatory but insufficient for precise usage.

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?

The description clearly states the tool performs a 'channel audit' and lists specific areas covered (upload cadence, top videos, outliers, title patterns, thumbnail availability). This distinguishes it from sibling tools like youtube.channel.get_profile or youtube.channel.get_uploads, which focus on narrower aspects.

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

Usage Guidelines3/5

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

The description implies the tool is for comprehensive channel analysis but does not explicitly state when to use it vs. more specific siblings. No usage exclusions or alternative recommendations are provided.

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

youtube.thumbnail.getB

Return all available thumbnail URLs and dimensions for a video

ParametersJSON Schema

Name	Required	Description	Default
`video`	Yes

TDQS

B3.2/5.0

Behavior3/5

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

With no annotations, the description indicates a simple read operation but lacks details on authentication, error handling, or what happens for missing videos. The behavior is implied but not fully explicit.

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

Conciseness5/5

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

Single sentence, perfectly concise with no redundant information.

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

Completeness3/5

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

Adequate for a simple tool, but missing parameter details and output structure (no output schema). Could specify return format or example.

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

Parameters1/5

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

The description does not clarify the format or expected value of the 'video' parameter (e.g., video ID, URL). Schema coverage is 0%, and the description adds no semantic guidance.

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?

The description clearly states the tool returns all available thumbnail URLs and dimensions for a video, distinguishing it from sibling tools that focus on other aspects like video details or transcripts.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives (e.g., youtube.video.get_details which might also include thumbnails), nor any prerequisites or exclusions.

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

youtube.transcript.analyzeC

Analyze user-provided transcript for hook, structure, CTAs, and retention signals

ParametersJSON Schema

Name	Required	Description	Default
`analysisTypes`	No
`transcriptText`	Yes

TDQS

C2.8/5.0

Behavior2/5

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

With no annotations, the description must fully disclose behavioral traits. It does not state whether the tool is read-only, requires authentication, has rate limits, or what side effects occur. The lack of output schema further obscures what the agent should expect. The description only hints at the analysis dimensions.

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

Conciseness5/5

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

The description is a single, focused sentence that conveys the core functionality without any extraneous words. It is appropriately sized and front-loaded.

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

Completeness2/5

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

Given the lack of output schema and annotations, the description is insufficient for an agent to fully understand the tool's behavior and output. It does not cover return value format, error conditions, or any constraints beyond the input schema details. More context is needed for reliable usage.

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

Parameters2/5

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

Schema description coverage is 0%, so the description should compensate for parameter meaning. It mentions 'hook, structure, CTAs, and retention signals' which partially correspond to the 'analysisTypes' enum (hook, structure, cta, repurpose), but 'retention signals' is not in the enum, causing potential confusion. 'transcriptText' is not described at all.

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

Purpose4/5

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

The description clearly states the tool's purpose: analyzing a transcript for hook, structure, CTAs, and retention signals. The verb 'analyze' and resource 'transcript' are specific, and the focus areas are listed. However, it doesn't explicitly differentiate from sibling tools like 'youtube.transcript.get', which retrieves transcripts, but the distinction is implicit.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a transcript from 'youtube.transcript.get'), nor does it specify when not to use it. The agent is left without context on tool selection.

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

youtube.transcript.getC

Retrieve transcript using approved modes (provided_text supported; OAuth captions planned)

ParametersJSON Schema

Name	Required	Default
`mode`	Yes
`video`	No
`language`	No	en
`transcriptText`	No

TDQS

C2.3/5.0

Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It only states 'Retrieve transcript using approved modes' but lacks information about side effects, permission requirements, error behavior, or output format. The modes are listed in the schema but not explained.

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

Conciseness2/5

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

The description is very short (one sentence), which is concise, but it lacks necessary substance. It front-loads the action but does not provide enough information to be useful. Under-specification is not a virtue.

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

Completeness1/5

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

With 4 parameters, no output schema, and no annotations, the description fails to provide a complete picture. It does not explain how to use the tool, what the transcript output looks like, or how the different modes work. The context is severely lacking.

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

Parameters1/5

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

Schema description coverage is 0%, yet the description does not explain any parameters. It only mentions 'approved modes' without elaborating on the 'mode' enum values or other parameters like 'video', 'language', or 'transcriptText'. The meaning of these parameters is entirely missing.

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

Purpose4/5

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

The description states 'Retrieve transcript', which clearly indicates the verb and resource. However, it does not distinguish from sibling tool 'youtube.transcript.analyze', which likely analyzes a transcript. The mention of 'approved modes' adds some specificity but is vague.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives. The description mentions 'provided_text supported; OAuth captions planned' but does not explain how to choose a mode or when to prefer this tool over sibling tools.

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

youtube.video.batch_get_detailsB

Batch video lookup by IDs or URLs with cache-aware quota handling

ParametersJSON Schema

Name	Required	Description	Default
`videos`	Yes
`includeTags`	No
`forceRefresh`	No

TDQS

B3.3/5.0

Behavior2/5

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

No annotations are provided, so the description must carry the full burden. It mentions 'cache-aware quota handling', which hints at caching and quota concerns, but does not explain mechanisms or implications. Missing behavioral details like error handling, rate limits, idempotency, or response structure.

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

Conciseness5/5

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

Single sentence with no redundancy. Information is front-loaded: purpose and key traits (batch, cache-aware). Efficient use of space.

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

Completeness2/5

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

Given the tool has 3 parameters, no output schema, and no annotations, the description is insufficient. It does not explain parameter details, return value, quota implications, or caching behavior. Leaves the agent with significant gaps for effective use.

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

Parameters2/5

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

Schema description coverage is 0%, and the description only adds minimal context for the 'videos' parameter ('by IDs or URLs'), not explaining accepted formats or mixed usage. The boolean parameters 'includeTags' and 'forceRefresh' are not described at all, leaving their semantics unclear.

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?

Clearly states 'Batch video lookup by IDs or URLs', specifying verb (lookup), resource (video), and mode (batch). Distinguishes from sibling youtube.video.get_details by the batch aspect. Also mentions cache-aware quota handling, adding specific nuance.

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

Usage Guidelines3/5

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

The description implies usage for batch operations, but does not explicitly state when to use this tool over alternatives like youtube.video.get_details. No guidance on prerequisites, quotas, or cache behavior. Usage context is inferred rather than explicit.

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

youtube.video.get_detailsC

Fetch video metadata, statistics, duration, and thumbnails

ParametersJSON Schema

Name	Required	Description	Default
`video`	Yes
`includeTags`	No
`forceRefresh`	No

TDQS

C2.8/5.0

Behavior2/5

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

No annotations are provided, and the description does not disclose any behavioral traits (e.g., authorization needs, error behavior, caching, or side effects). The description only lists what data is fetched, leaving the agent unaware of important runtime aspects.

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?

The description is a single sentence that is front-loaded with the action and output. It is concise, though it could include more detail without becoming overly long. Every word adds value.

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

Completeness2/5

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

Given the tool has 3 parameters and no output schema or annotations, the description is inadequate. It fails to explain parameter roles, output format, or usage context, leaving significant gaps for an AI agent.

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

Parameters1/5

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

Schema description coverage is 0%, meaning the parameters are not documented in the schema or description. The description does not explain the meaning of 'video', 'includeTags', or 'forceRefresh', leaving the agent unable to correctly populate them.

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?

The description clearly states 'Fetch video metadata, statistics, duration, and thumbnails', which is a specific verb and resource. It distinguishes this tool from siblings like 'youtube.video.batch_get_details' and 'youtube.video.performance_snapshot' by focusing on a single video's full details.

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

Usage Guidelines2/5

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

No guidance on when to use this tool over alternatives such as 'youtube.video.batch_get_details' or 'youtube.video.performance_snapshot'. There are no exclusions or context provided.

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

youtube.video.performance_snapshotC

Return views, engagement rate, views per day, and packaging metrics for a video

ParametersJSON Schema

Name	Required	Description	Default
`video`	Yes

TDQS

C2.7/5.0

Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure. It lists the returned metrics but does not state whether the tool is read-only, idempotent, requires auth, has rate limits, or any side effects. This is a significant gap for a tool without annotations.

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

Conciseness5/5

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

The description is a single sentence that lists the output metrics efficiently. Every word contributes to understanding the tool's purpose. No unnecessary information.

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

Completeness2/5

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

Given no output schema, the description should clarify the nature of 'packaging metrics' and the output format. The tool is simple with one parameter, but the description lacks enough detail to fully understand what is returned, especially for packaging metrics.

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

Parameters1/5

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

Schema description coverage is 0%, so the description must compensate. It only mentions 'video' without explaining the expected format (e.g., ID, URL). No additional meaning beyond the parameter name is provided.

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

Purpose4/5

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

The description clearly states the tool returns views, engagement rate, views per day, and packaging metrics for a video. It uses a specific verb 'return' and identifies the resource 'video'. However, it does not explicitly differentiate from siblings like 'get_details' or 'batch_get_details', which also return video metrics.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus siblings. It does not specify prerequisites, ideal conditions, or when not to use it. The agent must infer from the description that it's for a performance snapshot, but no exclusions or alternatives are mentioned.

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

youtube.video.searchC

Search YouTube by keyword with filters for region, duration, recency, and order

ParametersJSON Schema

Name	Required	Description	Default
`type`	No
`order`	No
`query`	Yes
`recency`	No
`channelId`	No
`maxResults`	No
`regionCode`	No
`forceRefresh`	No
`videoDuration`	No

TDQS

C2.7/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden for behavioral traits. It does not disclose authentication requirements, rate limits, pagination behavior (e.g., next page token), caching (forceRefresh param exists but not explained), or what results contain. The description is too sparse to guide an AI agent on how the tool behaves beyond a basic search.

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?

The description is a single sentence of 9 words, front-loading the action and key filters. It is concise but could include a second sentence to cover missing param info without being verbose. However, for its length, it is efficient.

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

Completeness2/5

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

Given the tool has 9 parameters (4 with enums), no output schema, and no annotations, the description is inadequate. It does not explain the meaning of all parameters, the structure of results, or any constraints. Sibling tools indicate various retrieval and analysis options, but this description does not position the tool within that ecosystem. A more complete description would discuss pagination, result fields, and optional filtering nuances.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate. It mentions region, duration, recency, and order, which correspond to regionCode, videoDuration, recency, and order parameters. However, it omits important parameters: type (video/channel), channelId, maxResults, forceRefresh. These are not explained, leaving the agent with only the schema's enum/type info, which lacks context. A score of 2 reflects the significant gap.

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

Purpose4/5

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

Description clearly states verb 'Search' and resource 'YouTube' with filters. However, it does not mention that the tool can search both videos and channels, which is revealed in the schema via the 'type' parameter. This could cause confusion with sibling tools like youtube.channel.get_profile. Still, the name 'youtube.video.search' implies video search, and the filters are listed.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. Siblings include direct video retrieval tools (get_details, batch_get_details) and channel tools, but the description does not differentiate. It does not specify context for use, such as discovery vs. known ID retrieval.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

17 tool updatesv0.1.0Jul 7, 2026
- First observedyoutube.auth.status
- First observedyoutube.cache.status
- First observedyoutube.channel.get_profile
- First observedyoutube.channel.get_uploads
- First observedyoutube.channel.resolve
- First observedyoutube.healthcheck
- First observedyoutube.niche.find
- First observedyoutube.packaging.analyze_title
- First observedyoutube.quota.status
- First observedyoutube.strategy.channel_audit
- First observedyoutube.thumbnail.get
- First observedyoutube.transcript.analyze
- First observedyoutube.transcript.get
- First observedyoutube.video.batch_get_details
- First observedyoutube.video.get_details
- First observedyoutube.video.performance_snapshot
- First observedyoutube.video.search

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose, organized by category prefixes (e.g., youtube.channel, youtube.video). No two tools overlap in functionality; an agent can easily differentiate them.

Naming Consistency5/5

All tool names follow a consistent pattern: lowercase with dot-separated categories and underscores (e.g., youtube.channel.get_profile, youtube.video.get_details). No mixing of conventions.

Tool Count5/5

17 tools cover a comprehensive range of YouTube data and analysis operations (channels, videos, transcripts, niche analysis, etc.) without being excessive. The count is well-scoped for the server's purpose.

Completeness5/5

The tool set covers core YouTube information retrieval and analysis needs: channel details, video details, transcripts, thumbnails, search, niche analysis, and channel audit. Missing CRUD operations are outside the server's analytical scope.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

YouTube Transcript & Search MCP Server A
com.transcriptout
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
Entertainment & Media Search
141
BulkTranscripts YouTube AOAuth
co.bulktranscripts
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents. No signup.
Entertainment & Media Search
71
kirbah-mcp-youtube
ai.smithery
Provide token-optimized, structured YouTube data to enhance your LLM applications. Access efficien…
Search Entertainment & Media Web Scraping
229
SocialDataX YouTube MCP A
com.52choujiang
YouTube public video, comment, reply, channel, search, and speech-to-text transcript tools.
Social Media Entertainment & Media
101

Related MCP Servers

YouTube MCP Server
Entertainment & Media Search Content Management Systems
sfiorini
A
license
A
quality
C
maintenance
Enables AI models to interact with YouTube content including video details, transcripts, channel information, playlists, and search functionality through the YouTube Data API.
Updated 9 months ago (2025-11-22 04:51 UTC)
7
22
10
MIT
mcp-server-youtube
Entertainment & Media Search
vaporif
A
license
Not graded
quality
C
maintenance
Enables AI assistants to search videos, read channels, browse playlists, fetch comments, and get transcripts from YouTube using the YouTube Data API v3 and InnerTube API for captions.
Updated 6 months ago (2026-03-21 09:44 UTC)
2
GPL 3.0
youtube-mcp
Entertainment & Media Search
gimslab
A
license
A
quality
D
maintenance
Enables AI tools to access YouTube content, including transcript extraction, video/channel info, and search.
Updated 8 months ago (2026-01-05 14:47 UTC)
4
27
MIT
YouTube MCP Server
felipefontoura
A
license
B
quality
C
maintenance
Provides comprehensive access to YouTube Data, Analytics, and Reporting APIs, enabling AI assistants to manage videos, analyze performance, handle comments, and extract transcripts.
Updated a month ago (2026-07-22 15:30 UTC)
40
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/CodingWithShahzaib/youtube-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

YouTube MCP Server

Table of Contents

Why This Exists

Features

v0.1 Tool Inventory (17 tools)

Architecture

Prerequisites

Obtaining a YouTube API Key

Quick Start

MCP Client Setup

Cursor

Claude Desktop

Using a .env file

Configuration

Tool Reference

Operational

Channel resolution & profiles

Video lookup & search

Strategy & content analysis

Channel audit output highlights

Niche scoring

Response Format

Quota & Caching

Quota costs (estimated units per call)

Caching behavior

Transcript Modes

Development

NPM scripts

Tech stack

Testing

Troubleshooting

Project Structure

Roadmap

Security

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

Using a `.env` file