This FastMCP server exposes 9 tools for blog interaction. Most tools have descriptions and basic parameter definitions. However, there are significant gaps in schema completeness, parameter descriptions are often minimal or missing, and no output schemas are documented. Error handling exists but lacks guidance for recovery. Tool naming is generally verb-noun compliant. The server is well-structured with environment config and caching, but the tool definitions themselves fall short of production-grade baselines.

• Document output schema for every tool. Include example responses and required/optional fields. E.g., blog_search should declare it returns [{title, url, date, excerpt}, ...] with pagination metadata.
• Expand parameter descriptions to include format, constraints, and valid values. E.g., 'repo: Name of the GitHub repository (string). Valid values: idvorkin.github.io, idvorkin.io-old, or call list_repos to see all. Defaults to idvorkin.github.io if omitted.'
• Add error handling patterns. Catch common failures (repo not found, API rate limit, malformed URL) and return actionable messages: 'Repository "abc" not found. Available repos: [list]. Did you mean one of these?'
• Declare pagination for list-returning tools. Add limit (default 20, max 100) and offset/cursor parameters. Return total_count and has_more in response so LLM knows when to fetch next page.
• Consolidate overlapping tools. Consider merging random_blog and random_blog_url into one tool with an optional output_format parameter (full_post vs url_only). This reduces LLM confusion.
• Add tool selection guidance in descriptions. E.g., random_blog: 'Use this to get a random full blog post for discovery. Use random_blog_url if you only need the URL. Use blog_search for targeted queries.'
• Implement idempotency guarantees. Ensure that calling get_recent_changes twice with the same repo returns the same result (or clearly document that responses are time-dependent).
• Add input validation with clear error messages. If 'url' param in read_blog_post is malformed, return 'Invalid URL: must start with https://. Got: "xyz". Example: https://idvork.in/hello-world'

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

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