Reddit MCP server has 6 tools with explicit registration and complete JSON schemas. However, definitions have significant gaps that prevent production use. All tools have descriptions (10-50 chars), but these are too brief to guide LLM selection effectively, most lack context about when to use them, prerequisites, or consequences. Parameter descriptions are minimal or missing. No output schemas are documented. Error handling is absent from tool definitions. The server lacks guidance on tool composition (which tools chain together). While schemas are present with types, they lack the depth required for reliable agentic use.
Descriptions are too brief (<50 chars) and lack actionable context. 'Fetch hot posts from a subreddit' does not explain when to use fetchPosts vs searchPosts, what fields are returned, or pagination behavior. LLMs cannot reliably select between similar tools without detailed guidance.
No output schemas documented. Tools return results but LLMs have no visibility into the structure, they cannot plan downstream calls or extract required fields (e.g., post_id from fetchPosts results). This forces agents to guess at response format.
Parameter descriptions are missing or generic. 'post_id' is described as 'Reddit post ID (without t3_ prefix)' but does not explain format constraints, how to obtain one from fetchPosts, or what happens if invalid. 'comment_text' and 'content' lack length/format guidance.
Recommendations
Expand tool descriptions to 100-200 chars. For fetchPosts: 'Fetch the hottest posts from a subreddit, sorted by current engagement. Use this to discover trending content. Returns up to 100 posts per call; results are newest-first. Requires subreddit name (e.g. python, gaming).'
Add output schemas to all tools. Example for fetchPosts: '{"type": "object", "properties": {"posts": {"type": "array", "items": {"type": "object", "properties": {"post_id": {"type": "string"}, "title": {"type": "string"}, "author": {"type": "string"}, "score": {"type": "integer"}, "created_at": {"type": "string", "format": "iso8601"}}}}}'
Document parameter constraints in descriptions. For post_id: 'Reddit post ID (36-character alphanumeric string, found in post URLs as /r/sub/comments/{post_id}/). Prefix "t3_" is automatically stripped by the API.'
Add error recovery guidance to tool descriptions. For postComment: 'Returns error if post_id is invalid (404), if the post is locked (403), or if rate limited (429). If 404, verify the post exists using fetchPosts or searchPosts first. If 403, the post may be archived or require subreddit membership.'
Clarify pagination behavior. Modify fetchPosts and searchPosts descriptions: 'Results are returned in a single call (no cursor/offset needed). Limit parameter caps results at 1-100; default 10. If more results are needed, call the tool again with different parameters (e.g., different search query or subreddit).'
Add tool composition guidance in the server's main description (e.g., in the __doc__ string): 'Common workflows: (1) fetchPosts → getComments to retrieve a discussion; (2) searchPosts → postComment to join a conversation; (3) getSubredditInfo → postToSubreddit to understand community rules before posting.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
No error handling guidance in tool definitions. What happens if a subreddit does not exist? If a post is deleted? If the agent lacks permission to post? LLMs receive no recovery instructions.
write tools (postComment, postToSubreddit) lack confirmation or dry-run capability. No mechanism to prevent accidental posting. Tool definitions do not declare side effects or irreversibility.
Tool composition guidance missing. No documented chain relationships (e.g., 'fetchPosts returns post IDs needed by getComments'). Agents must reverse-engineer which tools work together, leading to inefficient planning.
Pagination support unclear. searchPosts and fetchPosts accept 'limit' but no 'offset', 'page', or 'cursor' parameter. Tool descriptions do not clarify whether results are paginated or if all available data is returned in one call.
fetchPostssearchPosts
Implement dry-run or confirmation for write tools. Add an optional 'dry_run' parameter to postComment and postToSubreddit. When true, validate the post/comment but do not submit. Return what would be posted for user confirmation.
Document authentication and permissions. Add server-level note: 'Requires Reddit app credentials (REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET, REDDIT_USERNAME, REDDIT_PASSWORD). Script-type apps support posting; OAuth apps are read-only. Verify your app type at https://reddit.com/prefs/apps before calling write tools.'
Add natural-language parameter alternatives. postComment currently requires opaque post_id. Consider: 'For convenience, post_id can be a subreddit URL (e.g., reddit.com/r/python/comments/abc123/title) or short post code (abc123). Tool resolves to full ID internally.'
Return field consistency for chaining. Ensure fetchPosts response always includes 'post_id' (not 'id' or 'post.id'), so agent can directly pass to getComments. Document this explicitly: 'Use the "post_id" field from fetchPosts results as input to getComments.'
Add rate-limit guidance. Include in server description: 'Reddit API allows 60 requests/minute. Tools do not implement queueing. If rate-limited (429 error), wait 1 minute before retrying. Plan tool sequences to stay under the limit.'
Specify result limits and truncation. Modify fetchPosts description: 'Returns up to 100 posts. Comment text is truncated at 1000 chars; use getComments to fetch full comment threads. Post content is limited to first 5000 chars for text posts.'
Document the postToSubreddit parameter relationship. content and url are mutually exclusive. Update description: 'For text posts, provide content and omit url. For link posts, provide url and omit content. Providing both or neither will error with clear guidance on required fields.'