Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
YouTube Search MCP demonstrates solid tool definition fundamentals with complete schema coverage across 8 tools, consistent naming conventions, and comprehensive error handling. However, several quality gaps prevent a higher score: (1) descriptions lack strategic context about WHEN to use each tool vs alternatives, (2) many parameter descriptions are minimal or generic, (3) output schemas are undocumented (tools return JSON strings without field documentation), and (4) no tool annotations (readOnlyHint/destructiveHint/idempotentHint). The server registers tools cleanly via FastMCP with proper async handling and validates inputs (e.g., video_id format validation), but the LLM-facing definitions need enrichment to meet production baseline. Average tool score: 62/100.
Tools (8)
download_audiowritesource verified80/100
Download audio only from a YouTube video.
download_videowritesource verified80/100
Download a YouTube video with configurable quality.
get_playlist_inforead onlysource verified78/100
Get detailed information about a specific YouTube playlist.
get_playlist_videosread onlysource verified77/100
Get list of videos from a YouTube playlist.
get_video_inforead onlysource verified78/100
Get detailed information about a specific YouTube video.
Output schemas are documented textually in docstrings but not formally defined. LLMs cannot parse text descriptions of JSON structure; they need explicit field types, formats, and whether fields are always present or conditional.
String parameters that accept a fixed set of values (quality, format, output_format) are not declared as enums. This invites LLM hallucination (e.g., passing 'ultra' instead of 'best' for quality, or 'xml' instead of 'json' for output_format). Free-form strings require the LLM to infer valid options from descriptions, which is error-prone.
Define formal output schemas for all tools. Use JSON Schema to specify the structure of returned objects, including field types, nullability, and constraints. For example, download_video should return: { success: boolean, file_path?: string, file_size_bytes?: number, duration_seconds?: number, quality: string, error?: string }. Document this in the tool's schema property or in comments for FastMCP registration.
Convert string parameters with fixed options (quality, format, output_format) to enums in the JSON Schema. Example: quality enum: ['best', 'high', 'medium', 'low'] for download_video. This prevents LLM hallucination and makes the tool self-documenting.
Add min/max bounds to numeric parameters. search_videos and search_playlists should specify: max_results with minimum=1, maximum=50 (or whatever the backend supports). Include a note in the description: 'Results beyond 50 require pagination via next_cursor.'
Enhance tool descriptions with strategic context and typical workflows. Example for search_videos: 'Search YouTube for individual videos. Returns a list of video IDs, titles, and metadata. Call this when the user asks for specific content (e.g., "Find tutorials on Python"). For playlists of curated content, use search_playlists instead. Results are limited to max_results; use next_cursor to fetch more.'
Implement pagination properly. Add next_cursor or page parameters to search_* and get_playlist_videos. Include a total_count or has_more flag in the response. Document in the tool description: 'Results are paginated. To fetch the next page, pass the next_cursor returned by the previous call.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
First recorded score · v2 rubric
65/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-23
C
65
<=2025-11-25
v2
read only
source verified
78/100
Validate that the YouTube search provider is working correctly.
Numeric bounds are missing or inconsistent. max_results on search_* tools lack min/max guidance; get_playlist_videos max_results description uses confusing language ('None for all videos, default: None') that mixes Python semantics with JSON Schema constraints.
Tool descriptions lack strategic context: WHEN to use each tool vs alternatives, what the typical workflow is, and what data the LLM should expect next. For example, search_videos vs search_playlists, under what circumstance should an LLM choose one over the other? This forces the LLM to reason by elimination rather than explicit guidance.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are present. This omits critical metadata: which tools are safe to retry? Which are read-only (and thus safe for all users)? Which are destructive (and require confirmation)? download_video and download_audio are destructive (write to disk) and should carry destructiveHint.
Pagination support is unclear or missing. search_* tools accept max_results but do not document whether there is a next_cursor, offset, or page parameter to fetch additional results. This breaks tool-chaining: an agent cannot easily iterate through large result sets.
Error responses return hardcoded messages and error codes (e.g., 'video_not_found', 'download_failed') without recovery guidance. For example, if download_audio fails with 'ffmpeg_not_found', the response should suggest 'Install FFmpeg and reconfigure' or 'Use download_video instead.' Currently, the LLM receives only the error code and must infer what to do next.
download_videodownload_audio
Add tool annotations. Register download_video and download_audio with destructiveHint=true. Register all read-only tools (search_*, get_*) with readOnlyHint=true. This helps clients decide whether to request confirmation before execution.
Improve error recovery guidance. When download_video fails with 'ffmpeg_not_found', return: { success: false, error: 'ffmpeg_not_found', message: 'FFmpeg is not installed. Install it via your system package manager and reconfigure the server, or use download_audio with a streaming format like opus instead.' }. This gives the LLM concrete next steps.
Document field names for common lookups. If search_videos returns video_id, ensure get_video_info expects the same parameter name (video_id, not vid or id). This enables smooth tool-chaining without the LLM needing to reason about field mapping.
Add examples or presets to descriptions for qualitative parameters. Instead of 'Quality preset - "best", "high" (1080p), "medium" (720p), "low" (480p)', provide a table or clear guidance: 'quality determines video resolution: best=highest available (up to 4K), high=1080p, medium=720p, low=480p. Choose based on user preference and network speed.'
Validate and document output_format parameter as an enum: ['json', 'markdown']. Ensure descriptions and schemas reflect this constraint.