The Medium Scraper MCP server has significant definition quality issues. While tool names follow verb_noun conventions (medium_scrape, medium_search, medium_batch), descriptions are inconsistent in depth and quality. Most critically, input parameter schemas are partially visible but lack complete JSON Schema type definitions in the provided code. The sample code excerpt cuts off mid-response for resources, making full assessment difficult. Of the 7 tools visible: medium_scrape, medium_batch, and medium_search have reasonably detailed descriptions (100-150 chars) with multiple parameters described; medium_fresh and medium_export are more sparsely documented; medium_cast and medium_synthesize mention external APIs but lack error handling guidance for API failures. Output schemas are largely undocumented in the visible code, we see a resource hint ('medium://trending') but no structured output documentation for tool responses. Error handling is minimal, no guidance on what happens when URLs fail, APIs timeout, or paywalls are hit (though handle_paywall() function exists, it's not integrated into tool descriptions).

• Document output schema for each tool. Specify the exact structure (e.g., medium_scrape returns {url, markdownContent, htmlContent, title, author, publishedDate, wordCount, isLocked, _paywall_warning}). Include types for every field.
• Convert parameter constraints to formal JSON Schema: add 'enum' arrays for sort/model/format; add 'minimum'/'maximum' for concurrency limits; add 'maxLength'/'minLength' for strings.
• Add recovery guidance in tool descriptions for external API failures. E.g., 'medium_cast: If ElevenLabs API times out, retry with voice_id fallback or use edge-tts model.' Same for medium_synthesize (Gemini/OpenAI fallback).
• Clarify when to use each discovery tool. Add to medium_search: 'Use for broad keyword search across all articles.' Add to medium_fresh: 'Use to discover trending articles within a specific topic (tag), faster than searching if topic is known.'
• Formalize the list of valid voice_id values for medium_cast. Either document them in description or expose a separate 'list_voices' tool (e.g., via the elevenlabs_voices import visible in code).
• Document per-item error handling for medium_batch. Specify whether the tool returns {success_count, failed_count, results: [{url, status, content_or_error}]} or fails entirely on first error.
• Add default behavior to tool descriptions where non-obvious. E.g., 'medium_scrape output_format defaults to "both" (returns both markdown and HTML)' helps LLMs avoid passing explicit defaults.
• Specify character/word limits for medium_cast in tool description (truncate_for_model exists in code). E.g., 'Articles longer than 10,000 characters will be truncated for audio quality.'