mcp-subtitle has 2 tools with reasonable naming but critical gaps in schema documentation, parameter descriptions, and error handling. Both tools have input parameters but the schema is not explicitly visible in the source code, only inferred from parameter names. Descriptions are present but brief (70-80 chars). The 'cancel_subtitles' tool has questionable semantics (marked READ_ONLY but suggests state mutation). No output schema documented. Error handling is entirely absent from the tool definitions. The implementation includes complex logic (Whisper transcription, yt-dlp integration, caching) but none of this is surfaced in tool descriptions to guide LLM selection or understand prerequisites.

• Define explicit JSON Schema for both tools. For 'language', use an enum: ['auto', 'en', 'zh', 'ja', 'es', ...] instead of free-form string. For 'url', constrain to a valid URL pattern. Example: { url: { type: 'string', pattern: '^https?://(www\.)?youtube\.com/.*', description: '...' }, language: { type: 'string', enum: ['auto', 'en', 'zh', ...], description: '...' } }
• Document output schema explicitly. For get_subtitles, return a structured object: { 'subtitles': string, 'language_detected': string, 'source': 'manual|auto|transcribed', 'duration_seconds': number }. This lets agents know what fields to expect and plan downstream steps.
• Expand tool descriptions to 150 - 250 characters. Include: (1) what it does, (2) when to use it vs alternatives, (3) operational notes (time, cost, prerequisites). Example: 'Extract subtitles from a YouTube video. Fetches existing subtitles if available (instant); otherwise transcribes audio with Whisper ML (5 - 10 min for 1hr video). Use when manual subtitles unavailable or need specific language. Returns subtitle text and metadata.'
• Fix 'cancel_subtitles' risk annotation. Change from READ_ONLY to a custom destructiveHint or state-mutation marker. Or reconsider if this tool is needed, cancellation may be better handled via timeout than explicit cancellation.
• Add error recovery guidance to descriptions. Example: 'If transcription fails due to unsupported language, try language="en". If download fails, check that the YouTube URL is public and video is not age-restricted. Call get_subtitles again with a different language if the first attempt times out.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry