Leverages Google Gemini API (Gemini 2.5 Pro) for conversational video analysis and visual understanding.
Provides tools for analyzing YouTube videos, including full video visual and audio understanding via direct URL processing.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@youtube-gemini-mcp Analyze and summarize https://youtube.com/watch?v=abc123"
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.
A Model Context Protocol (MCP) server that provides conversational YouTube video analysis capabilities using Gemini 2.5 Pro. Analyze videos through multi-turn conversations with advanced visual understanding.
❌ Transcript-only limitations - Missing visual context and scene understanding
❌ No conversation memory - Each analysis starts from scratch
❌ Manual workflows - Complex download/upload processes
✅ Full video analysis - Visual, audio, and contextual understanding
✅ Session memory - Builds on previous analysis automatically
✅ Integrated workflows - YouTube URL to analysis in one step
Related MCP server: yt-analysis-mcp
Create persistent sessions for multi-turn video analysis:
# Create session
create_video_session(
description="Analyze machine learning lecture",
video_source="https://youtube.com/watch?v=abc123",
source_type="youtube_url"
)
# Continue conversation
analyze_video_in_session(session_id="uuid", prompt="What are the key concepts?")
analyze_video_in_session(session_id="uuid", prompt="Explain the neural networks part")No downloads required - process YouTube videos directly:
analyze_youtube_video(
youtube_url="https://youtube.com/watch?v=abc123",
prompt="Summarize this video's main points"
)Upload and analyze local video files (48-hour retention):
analyze_local_video(
video_path="/path/to/video.mp4",
prompt="What happens in this video?"
)Python 3.10+
Google AI API key
Poetry (recommended) or pip
# Clone repository
git clone https://github.com/aigentive/youtube-gemini-mcp
cd youtube-gemini-mcp
# Install with Poetry
poetry install
# Or with pip
pip install -e .
# Set environment variable
export GOOGLE_API_KEY="your_google_api_key_here"Get Google AI API Key: Visit Google AI Studio to get your free API key
Add to Claude Desktop: Copy the configuration below to your Claude Desktop settings
Add to your Claude Desktop MCP configuration (claude_desktop_config.json):
{
"mcpServers": {
"youtube-gemini-mcp": {
"command": "youtube-gemini-mcp",
"env": {
"GOOGLE_API_KEY": "your_google_api_key_here"
}
}
}
}For development work, use the Poetry configuration:
{
"mcpServers": {
"youtube-gemini-mcp-dev": {
"command": "poetry",
"args": ["run", "python", "-m", "youtube_gemini_mcp.server"],
"cwd": "/absolute/path/to/youtube-gemini-mcp",
"env": {
"GOOGLE_API_KEY": "your_google_api_key_here",
"LOG_LEVEL": "DEBUG"
}
}
}
}We provide ready-to-use configuration files:
Development: mcp-config.poetry.json - For local development
Production: mcp-config.private.json.example - Copy and customize
Tool | Description |
| Create new conversational analysis session |
| Analyze video within session context |
| Single-shot YouTube video analysis |
| Single-shot local video analysis |
| Get session information and history |
| List all active sessions |
| Close session and cleanup resources |
| Validate and normalize YouTube URLs |
| Comprehensive documentation |
| Server health and statistics |
Analyze lectures, tutorials, and educational videos with follow-up questions.
Research documentaries, interviews, and informational content systematically.
Extract key insights and create summaries from long-form content.
Analyze existing training videos to extract learning objectives and key points.
# Direct analysis - perfect for quick insights
analyze_youtube_video(
youtube_url="https://youtube.com/watch?v=dQw4w9WgXcQ",
prompt="What is this video about? Provide a comprehensive summary."
)# Create persistent session for multi-turn conversation
session = create_video_session(
description="Learning about machine learning fundamentals",
video_source="https://youtube.com/watch?v=abc123",
session_name="ML Fundamentals Study"
)
# Build understanding through conversation
analyze_video_in_session(
session_id=session["session_id"],
prompt="What are the main topics covered in this lecture?"
)
analyze_video_in_session(
session_id=session["session_id"],
prompt="Focus on the neural networks section - how are they explained?"
)
analyze_video_in_session(
session_id=session["session_id"],
prompt="What practical examples or demonstrations are shown?"
)
analyze_video_in_session(
session_id=session["session_id"],
prompt="Based on our discussion, what are the key takeaways for beginners?"
)# Upload and analyze private content
analyze_local_video(
video_path="/path/to/your/presentation.mp4",
prompt="Extract the key business metrics and recommendations from this quarterly review"
)# Focus on specific video segments
analyze_video_in_session(
session_id="your-session-id",
prompt="Analyze the demonstration shown in this segment",
timestamp_range="5:30-8:45"
)Required:
GOOGLE_API_KEY - Get your free API key from Google AI Studio
Optional Configuration:
MCP_MAX_SESSIONS=50 # Maximum concurrent sessions
MCP_SESSION_TIMEOUT=7200 # Session timeout in seconds (2 hours)
GEMINI_MODEL_DEFAULT="gemini-2.5-pro-preview-05-06" # Default Gemini model
MAX_VIDEO_DURATION=7200 # Max video length in seconds
AUTO_CLEANUP_FILES=true # Auto-cleanup uploaded files
LOG_LEVEL=INFO # Logging level (DEBUG, INFO, WARNING, ERROR)Python: 3.10+ (3.11+ recommended)
Memory: 4GB RAM minimum for video processing
Storage: 500MB for session data and temporary files
Network: High-speed internet for video processing
✅ No file size limits - Direct URL processing
✅ Unlimited session duration - No 48-hour restriction
⚠️ 2-hour video limit - Recommended maximum for optimal performance
⚠️ Public videos only - Private/unlisted may not be accessible
⚠️ 2GB file size limit - Google Files API restriction
⚠️ 48-hour auto-deletion - Files automatically deleted after 48 hours
⚠️ 20GB project limit - Total storage quota per Google project
❌ No retention extension - Cannot extend file lifespan beyond 48 hours
Concurrent sessions: Default maximum 50 active sessions
Session timeout: 2 hours of inactivity before cleanup
Memory usage: ~100MB per active session
Response time: 10-30 seconds for typical analysis requests
# Run tests
poetry run pytest
# With coverage
poetry run pytest --cov=youtube_gemini_mcp
# Type checking
poetry run mypy src/This project is licensed under the MIT License - see the LICENSE file for details.
LLM.md - Comprehensive usage guide for AI systems
DEVELOPMENT.md - Development setup and architecture
CONTRIBUTING.md - How to contribute to the project
PRD.md - Complete product requirements document
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Fork the repository
Set up development environment: poetry install
Run tests: poetry run pytest
Make your changes and add tests
Submit a pull request
🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Issues
💬 Discussions: GitHub Discussions
📖 Documentation: Check our comprehensive docs above
Check Documentation: Start with LLM.md for usage questions
Search Issues: Look for existing solutions in GitHub Issues
Create Issue: Provide clear details and reproduction steps
Community: Join discussions for general questions and ideas
Single-shot or session-integrated local video analysis using Files API.
Args: video_path: Local video file path prompt: Analysis instruction model: Gemini model to use session_id: Optional session for context
| Name | Required | Description | Default |
|---|---|---|---|
| video_path | Yes | ||
| prompt | Yes | ||
| model | No | gemini-2.5-flash | |
| session_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose all behavioral traits. It only mentions using the Files API without explaining side effects, file handling, or lifecycle (e.g., whether videos are cached or deleted). This is insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short with a clear one-line summary followed by a parameter list. It is well-structured and avoids redundancy, though the docstring format is slightly less natural than prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the tool is relatively simple (4 params, no nested objects), the description covers the core functionality and usage modes. It could mention error handling or file size limits but remains sufficient for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds brief meanings (e.g., 'Local video file path', 'Analysis instruction', 'Gemini model to use') but provides no format constraints, examples, or additional context beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it analyzes local video files using the Files API, and the phrase 'local video' distinguishes it from siblings like analyze_youtube_video. The verb 'analyze' with 'local video' specifies the resource and action unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Single-shot or session-integrated', indicating when to use session_id vs standalone. It does not explicitly contrast with analyze_video_in_session, but the context is clear enough for an agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze video within session context.
Args: session_id: UUID of existing session prompt: Analysis question/instruction timestamp_range: Optional "MM:SS-MM:SS" for segment analysis
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | ||
| prompt | Yes | ||
| timestamp_range | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only lists parameters without disclosing behavioral traits such as return format, destructiveness, side effects, or rate limits. For an analysis tool, information about processing time or data usage would be valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with purpose, and uses a clean parameter list format. Every sentence serves a clear function with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 annotations, and an output schema, the description adequately covers parameter meanings but is incomplete in behavioral and usage context. It does not mention what the analysis returns (though output schema exists) or any prerequisites beyond having a session.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It does so by clarifying 'session_id' as UUID of existing session, 'prompt' as analysis question/instruction, and 'timestamp_range' as optional 'MM:SS-MM:SS' format for segment analysis. This adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Analyze' and resource 'video within session context'. It is not a tautology and implies a specific scope (existing session). However, it does not differentiate from sibling tools like analyze_local_video or analyze_youtube_video, which might share similar analysis capabilities but on different sources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies via parameter 'session_id' that this tool operates on an existing session, hinting it should be used after a session is created. But it lacks explicit guidance on when to use this tool versus siblings, no when-not 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.
Single-shot or session-integrated YouTube video analysis using direct URL method.
Args: youtube_url: YouTube video URL or ID prompt: Analysis instruction model: Gemini model to use session_id: Optional session for context
| Name | Required | Description | Default |
|---|---|---|---|
| youtube_url | Yes | ||
| prompt | Yes | ||
| model | No | gemini-2.5-flash | |
| session_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the burden of behavioral disclosure. It only lists parameters and does not describe important traits such as whether the video is downloaded, processing time, supported video lengths, or any rate limits. The presence of an output schema is not utilized for transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with a brief introductory sentence and a structured parameter list. No wasted words; each sentence serves a purpose. The key purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters and an output schema, the description covers parameter semantics but lacks behavioral context and return value explanation. It provides a minimum viable description but does not fully equip an agent to understand side effects or expected outcomes beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the input schema has no descriptions. The tool description provides brief but meaningful parameter descriptions (e.g., 'YouTube video URL or ID', 'Analysis instruction', 'Gemini model to use', 'Optional session for context'), which add value beyond the bare property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Single-shot or session-integrated YouTube video analysis using direct URL method.' It explicitly mentions YouTube video analysis by URL, distinguishing it from siblings like analyze_local_video and analyze_video_in_session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for YouTube URLs and mentions optional session integration via session_id. However, it does not explicitly state when to use this tool over siblings (e.g., analyze_local_video for local files, analyze_video_in_session for existing sessions) or provide when-not scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close session and cleanup resources.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It mentions 'cleanup resources' but does not detail what is destroyed or if the action is reversible. Lacks specificity on 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (4 words), which is concise but lacks necessary detail. It could benefit from a few more words to add context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not explain when to close a session, prerequisites (e.g., session must exist), or the impact of cleanup. Given the number of sibling tools, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter 'session_id' has no description in either the schema or the tool description. The schema coverage is 0%, and the description adds no meaning beyond the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (close session) and the scope (cleanup resources). It distinguishes from siblings like create_video_session and list_active_sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 get_session_status. Implicit that it's for ending a session, but no explicit when or when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create new conversational video analysis session.
Args: description: Session context/purpose video_source: YouTube URL or local video file path model: Gemini model to use session_name: Optional friendly name source_type: "youtube_url" (default) or "local_file"
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | ||
| video_source | Yes | ||
| model | No | gemini-2.5-flash | |
| session_name | No | ||
| source_type | No | youtube_url |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden for behavioral disclosure. It only lists parameters and does not mention side effects, failure modes, or operational constraints (e.g., whether creating a session is idempotent or what happens with invalid inputs).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description starts with a clear purpose statement and uses a structured Args format. It is reasonably concise, though the parameter list could be more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and an output schema, the description omits any explanation of the return value or how the created session is used afterward. This leaves the agent without a complete usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description's parameter explanations add some value (e.g., 'YouTube URL or local video file path' for video_source). However, descriptions are terse and lack detail; for example, 'Session context/purpose' is minimally informative.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create new conversational video analysis session', clearly identifying the verb and resource. This distinguishes it from sibling tools like 'analyze_local_video' or 'close_session'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 such as 'analyze_video_in_session' or 'validate_youtube_url'. There is no discussion of prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Server statistics and health monitoring.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It only says 'statistics and health monitoring' without specifying what is returned, whether it's read-only, or any other behavioral traits. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, very concise. Could be slightly more detailed but appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema, the description is adequate but could be enhanced by mentioning that detailed stats are in the output schema. Still, it conveys the core function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. Baseline is 4 as no additional information is needed from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Server statistics and health monitoring', which conveys a specific verb (get) and resource (server stats). It distinguishes itself from sibling tools, which are all video-related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives, but since siblings are unrelated, usage is implied. 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.
Get current session status and history.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks details about behavioral traits. It does not state that this is a read-only operation, nor does it clarify what 'status' and 'history' entail. Since annotations are absent, the description should disclose side effects or permissions, but it does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one phrase), which makes it concise, but it is too brief to be helpful. It lacks any structure or additional sentences that could provide value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is incomplete. It fails to explain what 'session status' means (e.g., active, idle, closed) or what 'history' refers to. The tool's purpose is not fully conveyed for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'session_id' parameter at all. The agent gets no guidance on what the session_id is, its format, or how to obtain it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get current session status and history' clearly states the verb 'Get' and the resource 'session status and history'. It distinguishes from sibling tools like 'list_active_sessions' and 'close_session' which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 over alternatives. For example, it does not explain how it differs from 'list_active_sessions' or when to use 'get_session_status' after creating a session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Comprehensive tool documentation and examples.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It implies a read-only operation returning documentation, but does not disclose details such as whether it requires authentication or caching behavior. The description is minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence. It is concise without being a tautology. Could be improved by adding more structure or examples, but for a simple tool it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no parameters and an output schema exists, the description minimally explains purpose. However, for a documentation tool, more detail about the content or format would be valuable. It covers the basics but lacks depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the input schema is empty (100% coverage). The description does not need to add parameter info. However, it could elaborate on the return value structure, which is left to the output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Comprehensive tool documentation and examples,' clearly indicating a verb+resource pair (get usage guide). It distinguishes from sibling tools focused on video analysis and sessions. However, it does not specify which tool's documentation, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 lacks explicit context about prerequisites or scenarios, which is a significant gap given that sibling tools exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all active video analysis sessions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as authentication requirements, rate limits, or side effects. The description is too minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant information. 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.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple and has an output schema, the description does not elaborate on what 'active' means, the scope of listing, or any filtering criteria. Some additional context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is high (100%). The description adds no extra meaning beyond the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'active video analysis sessions', making the tool's purpose unambiguous. It distinguishes well from siblings like 'close_session' or 'create_video_session'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 like 'get_session_status'. There are no context cues or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate and normalize YouTube URLs/IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 only states validation and normalization but does not explain what normalization entails, whether the tool is read-only, error handling, or any 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action verbs, no wasted words. Slightly terse but efficient for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema, the description does not need to detail returns, but it lacks guidance on typical usage patterns like pre-validation for other tools. Incomplete for a validation tool that would benefit from explaining what the normalized output looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description adds that the input can be a YouTube URL or ID, which is not explicit in the schema (only parameter name 'url'). However, it does not specify expected formats or constraints, so it only marginally compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates and normalizes YouTube URLs/IDs, with a specific verb and resource. It differentiates from sibling tools like analyze_youtube_video, which focuses on analysis rather than validation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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, such as before calling analyze_youtube_video. No context on prerequisites or scenarios where validation is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1analyze_local_videoanalyze_video_in_sessionanalyze_youtube_videoclose_sessioncreate_video_sessionget_server_statsget_session_statusget_usage_guidelist_active_sessionsvalidate_youtube_urlScored across 10 tools
The three analysis tools (analyze_local_video, analyze_video_in_session, analyze_youtube_video) have overlapping purposes, as the first and third can also work with sessions. Although descriptions clarify differences, an agent might struggle to select the correct tool without careful reading.
All tool names follow a consistent verb_noun pattern in snake_case, such as 'analyze_local_video', 'create_video_session', and 'list_active_sessions'. No mixing of conventions or irregular names.
The server has 10 tools, which is well-scoped for its domain of video analysis and session management. Each tool serves a distinct purpose without unnecessary clutter.
The tool set covers core workflows: creating sessions, analyzing videos (local or YouTube), managing sessions, and utilities (validation, stats, guide). Minor gaps like lacking explicit update for sessions are mitigated by session lifecycle tools.
Personal YouTube AI knowledge base powered by RAG. Query your subscribed YouTube channels.
Transcribe YouTube via Whisper. Summaries, chapters, semantic-search across your corpus.
Extract YouTube transcripts, search what was said, and read on-screen frames with cited timestamps.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents. No signup.
