YouTube Research MCP demonstrates solid definition quality with 14 well-named tools, comprehensive parameter schemas, and detailed descriptions. All tools follow verb-noun naming conventions (search-, get-, research-, compare-). Schemas are properly typed with JSON Schema format including enums, descriptions, and defaults. However, output schemas are entirely undocumented, the server provides no structured definition of what each tool returns, forcing LLMs to infer response structure. Error handling guidance is minimal. Tool descriptions average ~150 chars and are adequate but could be more LLM-optimized per the 50-200 char baseline. Parameter descriptions are present on all params (100% coverage), a strong point. Security is handled correctly: API keys are server-side injected via environment variables, not exposed as parameters.

• Document output schema for every tool. Add a 'Returns' section in the tool description (or a structured returns field) listing all top-level fields, types, and sample values. Example: 'Returns object with fields: videoId (string), title (string), views (number), transcript (array of {timestamp: string, text: string})'.
• Add error recovery guidance to tool descriptions. For tools that depend on external data (transcripts, captions), include: 'If transcript is unavailable, the tool will fail with code 'transcript_unavailable'. Try get-captions-available to verify caption tracks exist, then retry with a supported language.'
• Enforce and document result limits. Update search-videos, get-video-comments, search-transcript descriptions to state: 'Results are capped at 50 items per request. Use pagination (pageToken, offset) to retrieve additional results.'
• Clarify tool selection guidance. Expand descriptions of overlapping tools (research-video vs get-key-moments vs get-transcript-summary) with explicit guidance: 'Use research-video for searching specific terms. Use get-key-moments for automatic highlight extraction. Use get-transcript-summary for a natural-language overview.'
• Document parameter relationships. For research-video, state: 'The query parameter applies to the transcript segment within startSeconds and endSeconds. Both time filters are optional; if omitted, the entire transcript is searched.'
• Add dry-run or preview mode for multi-video operations (research-videos, compare-transcripts) to prevent runaway API consumption. E.g., 'Set previewOnly=true to see estimated scope without fetching full transcripts.'

Inferred effective spec: 2025-06-18+.

• Relies on Stateful initialize / Mcp-Session-Id (removed; protocol is stateless) - make each request self-contained