Reddit MCP has 2 tools with explicit schema registration visible in src/index.ts. Both tools have descriptions and input schemas, but there are significant gaps in schema completeness, parameter descriptions, and error handling. Tool names follow verb_noun convention but lack clarity on when to use one over the other. Schemas are present but parameter descriptions are minimal and lack format/constraint guidance. No output schema documentation. No error handling guidance for LLM recovery. Average tool quality lands at C/D boundary (52).
Parameter descriptions lack actionable constraints and format guidance. 'The search keyword' (query param) does not explain length limits, required format, or handling of special characters. 'Main search terms' (keywords) does not specify expected array size, string length, or how duplicates are handled.
No output schema documented. Tool returns JSON objects with fields (title, text, url, author, subreddit, upvotes, createdAt, matchedKeywords, type) but LLM has no formal specification of return structure. LLM must infer field types and availability from code comments.
No error handling guidance for LLM recovery. Code throws 'APIFY_API_TOKEN is not set' error but does not guide agent on what to do next. Tool callouts to external Apify service have no timeout handling, rate-limit recovery, or partial failure fallback documented.
reddit_fast_searchreddit_lead_monitor
Recommendations
Add explicit output schema documentation: 'Returns an array of objects with fields: title (string), text (string, max 500 chars), url (string), author (string), subreddit (string), upvotes (integer), createdAt (ISO 8601 date string), matchedKeywords (array, lead_monitor only), type (string: post|comment, lead_monitor only).'
Constrain numeric parameters: update limit description to 'Max number of results (1-100, default 10)' and hours_back to 'How far back to search in hours (1-720, default 24).'
Enhance parameter descriptions with actionable constraints: query → 'Search keyword or phrase (1-256 characters, supports Reddit search syntax like subreddit:name, author:name)'; keywords → 'Array of search terms (1-10 terms, each 1-100 characters); negative_keywords → 'Terms to exclude from results (e.g., ["crypto", "hiring"]); target_subreddits → 'Limit results to these communities (e.g., ["marketing", "SaaS"]); sort in reddit_fast_search → 'Sort order: relevance=by match quality, hot=trending now, top=most upvoted, new=most recent. Not all sorts work with all search types.'
Add error guidance: 'If APIFY_API_TOKEN is missing, tool will fail. Ensure environment variable is set. If Apify service times out (>30s), retry with smaller limit or narrower subreddits. If no results found, try broader keywords or remove negative_keywords.'
Clarify tool selection in descriptions: reddit_fast_search → 'For broad searches across Reddit to gather context, discover communities, or find general information. Returns posts with metadata.'; reddit_lead_monitor → 'For finding discussions matching business keywords while filtering noise. Use when searching for customer problems, feature requests, or brand mentions. Returns both posts and comments with matched keywords highlighted.'
Tool descriptions do not differentiate use cases clearly. Both tools search Reddit, but distinction between 'fast search' (general) and 'lead monitor' (high-intent) is vague. Descriptions lack explicit guidance on when to select one over the other, forcing LLM to guess.
Numeric parameters lack bounds. 'limit' parameter has default 10 but no min/max constraint documented. 'hours_back' defaults to 24 with no upper bound, LLM could pass 10000 hours without validation. Unbounded numbers risk API overload or timeout.
Parameter 'sort' enum in reddit_fast_search accepts ["relevance", "hot", "top", "new"] but description does not explain what each option means or when to use it. 'relevance' may not work for all search types, no guidance provided.
No pagination support documented. Tool accepts 'limit' parameter but no cursor, offset, or 'has_more' field in response. Large result sets may exceed context windows. No guidance on how to retrieve additional results.
Tool names are not sufficiently disambiguating. 'reddit_fast_search' and 'reddit_lead_monitor' both search; naming convention does not follow consistent verb_noun pattern. 'monitor' suggests continuous operation, but tool is actually a one-off search.
reddit_lead_monitor
Document response structure and when fields are populated: 'matchedKeywords and type fields only present in reddit_lead_monitor results. urls point to Reddit post/comment pages. Truncated text at 500 chars to preserve context window.'
Add idempotency note: 'Tool is read-only and idempotent. Identical calls return identical results (subject to Reddit's real-time feed dynamics). Safe to retry on timeout.'
Consider renaming reddit_lead_monitor to search_reddit_leads or find_reddit_mentions for clearer intent alignment with verb_noun pattern.
Add pagination guidance: 'To get more results, increase limit parameter (max 100). No cursor support; implement pagination client-side by adjusting hours_back or keywords.'
Add rate-limit warning: 'Apify service enforces rate limits. Avoid calling with limit >100 or in rapid succession. If rate-limited, wait 60s and retry with smaller batch.'