Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
This server has fundamental quality gaps across naming, descriptions, schemas, and error handling. All 7 tools are explicitly registered via @mcp.tool decorators in main.py with visible implementations. However, tool descriptions are generic (10-30 chars, well below the 50-200 char baseline for A+ tools), parameter descriptions are missing entirely, and output schemas are completely undocumented. Error handling is minimal (catch-all try-except blocks that return error strings). Parameters lack type constraints (enums, ranges). Responses are unstructured strings rather than typed objects. No parameter documentation means LLMs cannot understand constraints or valid ranges. The lack of documented output schemas prevents downstream tool composition. This is a C-grade server with significant gaps in definition quality.
Tool descriptions are extremely brief (10-30 characters) and lack context for LLM selection. Baseline for A+ tools is 50-200 chars. Examples: 'Search reddit posts', 'Get hot posts from subreddit'. These do not explain WHEN to use the tool, WHAT it returns, or dependencies.
Parameters completely lack descriptions. The 'query' param in search_reddit has description 'search query' (12 chars), 'subreddit' has 'subreddit name' (14 chars). Baseline: 100% of A+ tools have descriptions for ALL params averaging 72 chars. LLMs cannot infer format, range, or constraints.
Expand every tool description to 100-200 characters explaining WHAT it does, WHEN to use it, and what it returns. Example: 'Search Reddit for posts matching a query. Returns up to 25 results with title, URL, subreddit, and post_id. Use this to find relevant discussions on a topic.'
Add detailed descriptions to all parameters. For 'subreddit', write: 'Name of the subreddit to query (lowercase, alphanumeric + underscores only, e.g. "python", "r_programming"). Case-insensitive.' For 'query' in search_reddit, write: 'Search keywords or phrase. Supports Reddit syntax (site:, author:, etc.). Results are ranked by relevance.'
Document all output schemas as structured objects, not strings. Example for search_reddit: Return array of {post_id: string, title: string, url: string, subreddit: string, author: string}. For get_user_profile: Return {username: string, total_karma: number, created_utc: ISO8601 date, account_age_days: number}.
Improve error handling with categorization. Instead of 'Error: ...' catch specific exceptions (requests.HTTPError, requests.Timeout, ValueError) and return: For 404 Not Found: 'Subreddit or user not found. Check the spelling and try again.' For timeout: 'Reddit API timeout. Retry in 5 seconds.' For invalid input: 'Invalid subreddit name. Use alphanumeric characters and underscores only (e.g. python, r_programming).'
Add result pagination. Add 'limit' (default 25, max 100) and 'offset' (default 0) parameters to search_reddit, get_hot_posts, get_new_posts, get_top_posts. Document in tool description: 'Returns up to <limit> results. Use offset for pagination.' Return {results: [...], total: number, next_offset: number|null}.
Error handling is minimal and non-actionable. All tools use generic try-except that returns 'Error: {str(e)}'. No guidance on what the LLM should do next (retry? call alternative tool? ask user?). Baseline: errors should categorize as retryable/user-fixable/fatal and suggest next steps.
No input validation or constraints. Parameters like 'subreddit' and 'username' accept any string. No enum validation, length limits, or format constraints are documented or enforced. LLMs can pass invalid values (e.g. 'subreddit123!!!') without guidance.
No result pagination or limits. Tools like search_reddit and get_hot_posts return all results from the API without limiting result count or documenting how many items are returned. Baseline: large result sets should be capped (20-50) and offer pagination parameters.
No tool composition support. Tools return only title and URL, omitting post_id, subreddit, or other IDs needed for downstream operations (e.g. to get comments on a post). Responses do not contain references required for chaining calls.
Overlapping tool responsibilities reduce clarity. Three tools (get_hot_posts, get_new_posts, get_top_posts) are nearly identical except for sorting. Their names are similar enough that LLMs may conflate them. Consider a single 'list_subreddit_posts' tool with a 'sort' parameter (hot|new|top) instead.
get_hot_postsget_new_postsget_top_posts
Include IDs and structured data in responses. For search_reddit, return post_id, subreddit, and author. For get_hot_posts, return post_id, created_utc, score. This enables downstream tool calls without requiring separate lookups.
Consolidate similar tools. Merge get_hot_posts, get_new_posts, get_top_posts into a single 'list_subreddit_posts' with parameter 'sort_by: enum(hot|new|top|controversial|rising)'. Reduces LLM confusion and improves composability.
Add examples in parameter descriptions showing valid input formats. E.g., for 'subreddit': 'Subreddit name without r/ prefix (valid examples: python, learnprogramming, AskReddit).'
Document rate limits and API constraints. E.g., 'Reddit API limits searches to 30 per minute. Large result sets may timeout.'
Add dry-run or confirmation for any future write operations (if the server is extended to support posting, commenting, etc.). Irreversible operations should support confirmation patterns.