Provides comprehensive Reddit API access with 13 tools covering both read-only operations (getting posts, comments, user profiles, subreddit info, search) and authenticated actions (voting, commenting, creating posts) through OAuth2 authentication.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Reddit MCP Server show me the top posts from r/technology today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that provides read-only access to Reddit's API through a standardized interface. This server focuses on content discovery and analysis without requiring OAuth authentication.
7 Read-Only Tools: Comprehensive Reddit content access without authentication
No OAuth Required: Works immediately without any setup or configuration
Type-Safe Architecture: Full TypeScript with Zod schema validation and z.infer types
Error Handling: Robust error handling with dynamic troubleshooting tips
Clean Code Patterns: Consistent tool handlers with reduced boilerplate
MCP Standard: Compliant with Model Context Protocol specifications
Smart Defaults: Intelligent parameter defaults for better user experience
Related MCP server: Reddit MCP Server
This server provides read-only access to Reddit's public API without requiring any authentication. All tools work immediately without OAuth setup or API credentials.
The server uses Reddit's public API endpoints that don't require authentication:
Public Posts: Access to all public subreddit posts
Public Comments: Access to all public comments
Public Profiles: Access to public user information
Public Subreddits: Access to subreddit information and metadata
Clone the repository:
git clone <repository-url>
cd mcp-redditInstall dependencies:
npm installBuild the project:
npm run buildStart the server:
npm startNo configuration required! The server works immediately without any setup.
You can create a .env file for optional configuration:
# Optional: Custom User-Agent (recommended)
REDDIT_USER_AGENT=Your-App-Name/1.0.0 (by /u/YourUsername)
# Optional: Request timeout
TIMEOUT_SECONDS=30While not required, it's recommended to set a custom User-Agent string to identify your application:
Format: AppName/Version (by /u/YourUsername)
Example: MCP-Reddit-Server/1.0.0 (by /u/YourUsername)
Start MCP Inspector:
npx @modelcontextprotocol/inspector node dist/index.jsOpen browser: http://localhost:6274
Test tools: Use the comprehensive test data in test-data.json
All tools work immediately without any setup:
get_subreddit_posts - Get posts from any subreddit
search_reddit - Search across Reddit or specific subreddits
get_user_profile - Get user profile information
get_subreddit_info - Get subreddit details
get_post_comments - Get comments for any post
get_trending_subreddits - Get trending subreddits
get_cross_posts - Find crossposts of a post
get_subreddit_posts - Get posts from a subreddit with sorting options
search_reddit - Search for posts across Reddit or within specific subreddits
get_user_profile - Get detailed profile information for any Reddit user
get_subreddit_info - Get comprehensive subreddit information
get_post_comments - Get comments for a specific post with sorting
get_trending_subreddits - Get trending and popular subreddits
get_cross_posts - Find crossposts of a specific post
{
"name": "get_subreddit_posts",
"arguments": {
"subreddit": "programming",
"sort": "hot"
}
}{
"name": "search_reddit",
"arguments": {
"query": "python tutorial",
"subreddit": "learnprogramming"
}
}{
"name": "get_user_profile",
"arguments": {
"username": "spez"
}
}{
"name": "get_subreddit_info",
"arguments": {
"subreddit": "programming"
}
}{
"name": "get_post_comments",
"arguments": {
"post_id": "1n1nlse",
"sort": "best"
}
}{
"name": "get_trending_subreddits",
"arguments": {}
}{
"name": "get_cross_posts",
"arguments": {
"post_id": "1n1nlse"
}
}Smart Defaults: Intelligent parameter defaults for better UX
Type Safety: Full TypeScript validation with Zod schemas
Error Handling: Comprehensive error messages with troubleshooting tips
Rate Limiting: Built-in protection against API rate limits
Inline Documentation: Detailed descriptions with examples for each tool
npm install
npm run buildnpx @modelcontextprotocol/inspector node dist/index.jsNavigate to http://localhost:6274
All tools work immediately without any setup:
get_trending_subreddits - See what's popular on Reddit
get_subreddit_info - Get details about any subreddit
get_subreddit_posts - Browse posts from any subreddit
search_reddit - Search for content across Reddit
get_user_profile - Get information about any Reddit user
get_post_comments - Read comments on any post
get_cross_posts - Find crossposts of any post
Public API: 60 requests per minute (Reddit default)
Built-in Protection: Server includes rate limiting to prevent API abuse
Header Monitoring: Automatically reads X-Ratelimit-Remaining and X-Ratelimit-Reset headers
Smart Warnings: Logs warnings when approaching rate limits
Graceful Handling: Returns helpful error messages when rate limits are exceeded
403 Forbidden
Check User-Agent string format in .env file
Ensure User-Agent follows Reddit's guidelines
Verify app is not suspended on Reddit
Rate Limit Exceeded
Server automatically monitors rate limits
Check console for rate limit warnings
Wait for the reset time shown in error messages
Consider implementing request queuing for high-volume usage
404 Not Found
Verify subreddit name is correct (without r/ prefix)
Check if post ID is valid
Ensure username exists on Reddit
Test with MCP Inspector:
npx @modelcontextprotocol/inspector node dist/index.jsVerify Environment (optional):
cat .envTest All Tools:
Start with get_trending_subreddits to verify basic connectivity
Try get_subreddit_posts with popular subreddits like "programming"
Use search_reddit to test search functionality
Type Safety: All tools now use z.infer<typeof Schema> for compile-time type checking
Consistent Patterns: Unified createToolHandler wrapper eliminates boilerplate try-catch blocks
Magic Number Constants: Replaced hardcoded values with named constants for better maintainability
Error Handling: Dynamic error messages with context-specific troubleshooting tips
Rate Limit Intelligence: Real-time monitoring of Reddit API rate limit headers
Smart Defaults: Intelligent parameter defaults based on tool context
Clean Code: Consistent patterns and reduced boilerplate
Inline Documentation: Comprehensive tool descriptions with examples and usage patterns
TypeScript Strict Mode: Full type safety with strict TypeScript configuration
Consistent Error Responses: Standardized error format across all tools
Build Validation: Automated TypeScript compilation with error checking
mcp-reddit/
├── src/
│ ├── services/
│ │ └── reddit-api.ts # Reddit API service
│ ├── types/
│ │ └── index.ts # TypeScript types and Zod schemas
│ └── index.ts # Main MCP server with 7 read-only tools
├── test-data.json # Comprehensive test data for all tools
├── MCP_TEST_DATA.md # Detailed testing guide
├── QUICK_START.md # Quick start guide
├── .env # Optional environment variables
├── env.example # Environment template
└── README.md # This fileFork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
This project is licensed under the MIT License.
🔄 Find crossposts of a Reddit post 🎯 What it does: Finds posts that were cross-posted from the original post 📝 Required: post_id (Reddit post ID to find crossposts for) 💡 Examples: • Find crossposts: {"post_id": "1n1nlse"} • Check shares: {"post_id": "1abc123"} 🔍 Output: List of crossposts with title, author, subreddit, score, and Reddit link
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | Reddit post ID to find crossposts for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions output format but lacks details on rate limits, authentication needs, error handling, or whether this is a read-only operation. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with emoji sections and bullet points, making it easy to scan. However, the 'Examples' section could be more concise, and some decorative elements like emojis don't add functional value, slightly reducing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter tool with no output schema, the description covers purpose and output format adequately but lacks context on behavioral aspects like rate limits or error cases. Given the low complexity, it's minimally complete but could be more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds value by specifying that post_id is a 'Reddit post ID to find crossposts for' and provides concrete examples, enhancing understanding beyond the schema's basic type information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verb ('Find crossposts') and resource ('Reddit post'), distinguishing it from siblings like get_post_comments or get_subreddit_posts by focusing on crosspost relationships rather than comments, subreddit info, or general posts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied through examples showing post_id usage, but there's no explicit guidance on when to use this tool versus alternatives like search_reddit or get_subreddit_posts for related content. The description doesn't mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
💬 Get comments for a Reddit post 🎯 What it does: Fetches comments and replies for any Reddit post 📝 Required: post_id (Reddit post ID, found in post URLs) ⚙️ Optional: sort ('best', 'top', 'new') 💡 Examples: • Get comments: {"post_id": "1n1nlse"} • Best comments: {"post_id": "1n1nlse", "sort": "best"} • New comments: {"post_id": "1n1nlse", "sort": "new"} 🔍 Output: Formatted comment tree with author, score, timestamp, and nested replies
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | Reddit post ID to get comments for | |
| sort | No | Sort order (default: best) | best |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it fetches comments and replies (read operation), specifies the output format ('formatted comment tree with author, score, timestamp, and nested replies'), and mentions optional sorting. However, it doesn't cover potential rate limits, authentication needs, or pagination behavior, which are gaps for a Reddit API tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose and uses bullet points efficiently for examples. Every sentence earns its place: the emoji sections (💬, 🎯, etc.) organize information without waste, and the output description is succinct. No redundant or verbose content is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is mostly complete. It covers purpose, parameters with examples, and output format. However, it lacks details on error handling, rate limits, or authentication—common for API tools. With no output schema, the output description is helpful but could be more detailed (e.g., structure of the tree).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters well. The description adds value by explaining post_id ('found in post URLs'), providing examples of parameter usage, and clarifying sort options with examples. This goes beyond the schema's basic descriptions, though it doesn't add deep semantic nuances.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'fetches' and resource 'comments and replies for any Reddit post', making the purpose specific. It distinguishes from siblings like get_subreddit_posts (which gets posts, not comments) and get_user_profile (user-focused rather than post-focused). The emoji '💬 Get comments for a Reddit post' reinforces this distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing comments for a Reddit post, but provides no explicit guidance on when to use this tool versus alternatives like search_reddit (which might find comments via search) or get_cross_posts (which focuses on cross-posting). There's no mention of prerequisites or exclusions, leaving usage context inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🏠 Get subreddit information 🎯 What it does: Fetches detailed info about any Reddit subreddit 📝 Required: subreddit name (without r/ prefix) 💡 Examples: • Get info: {"subreddit": "programming"} • Check subreddit: {"subreddit": "AskReddit"} • View details: {"subreddit": "MachineLearning"} 🔍 Output: Subreddit details with description, subscribers, active users, creation date, NSFW status, and URL
| Name | Required | Description | Default |
|---|---|---|---|
| subreddit | Yes | Subreddit name to get information about |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool 'fetches' (read operation) and lists output details, but does not mention behavioral traits like rate limits, authentication needs, error handling, or whether it's idempotent. The description adds some context about the output format, but lacks comprehensive behavioral disclosure for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with key information (purpose and required parameter) using emoji sections. Each section ('🎯', '📝', '💡', '🔍') earns its place by adding distinct value without redundancy. The structure is efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is mostly complete: it covers purpose, parameter details, examples, and output format. However, it lacks information on error cases or limitations (e.g., invalid subreddit names), which would be helpful for a tool with no annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying the parameter semantics: it specifies 'subreddit name (without r/ prefix)' and provides examples, which goes beyond the schema's generic 'Subreddit name to get information about'. This extra detail compensates adequately, but doesn't fully explain edge cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'fetches detailed info about any Reddit subreddit' with specific verb ('fetches') and resource ('subreddit'), and distinguishes it from sibling tools like get_subreddit_posts (which gets posts) or get_user_profile (which gets user info). The emoji '🏠' and '🎯' sections reinforce this specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (to get subreddit details like description, subscribers, etc.), but does not explicitly state when not to use it or name alternatives among siblings. The '📝 Required' section implies usage for subreddit info retrieval, but lacks explicit comparison to tools like get_trending_subreddits or search_reddit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
📖 Get posts from a subreddit 🎯 What it does: Fetches posts from any Reddit subreddit with sorting options 📝 Required: subreddit name (e.g., 'programming', 'AskReddit', 'MachineLearning') ⚙️ Optional: sort ('hot', 'new', 'top') 💡 Examples: • Get hot posts: {"subreddit": "programming"} • Get new posts: {"subreddit": "AskReddit", "sort": "new"} • Get top posts: {"subreddit": "MachineLearning", "sort": "top"} 🔍 Output: Formatted list with title, author, score, comments, date, and Reddit link
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort order (default: hot) | hot |
| subreddit | Yes | Subreddit name (e.g., 'programming', 'AskReddit') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool fetches data (implied read-only) and describes the output format, but does not mention rate limits, authentication needs, pagination, or error handling. It adds some behavioral context (output format) but is incomplete for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with emoji sections, front-loaded purpose, and efficient bullet points. Every sentence earns its place by providing purpose, requirements, examples, and output details without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is fairly complete—it covers purpose, parameters with examples, and output format. However, it lacks details on behavioral aspects like rate limits or error handling, which would be beneficial since there are no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds minimal value beyond the schema by listing examples and noting that subreddit is required and sort is optional, but does not provide additional semantics like format constraints or usage tips beyond what's in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('fetches posts') and resources ('from any Reddit subreddit'), and distinguishes it from siblings like get_subreddit_info (which gets metadata) or get_post_comments (which gets comments). The emoji section 'What it does' explicitly defines the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (to fetch posts from a subreddit) but does not explicitly mention when not to use it or name alternatives like get_trending_subreddits or search_reddit. The examples imply usage scenarios but lack explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔥 Get trending/popular subreddits 🎯 What it does: Fetches list of currently popular and trending subreddits 📝 Required: None (no parameters needed) 💡 Examples: • Get trending: {} • Simple call: {} 🔍 Output: List of trending subreddits with name, title, subscribers, description, and URL
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that no parameters are needed and describes the output format, but lacks details on rate limits, authentication needs, or data freshness (e.g., how 'trending' is defined). The description adds value beyond annotations but is not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with emoji-led sections, front-loads the purpose, and includes only essential elements (what it does, parameters, examples, output). Every sentence earns its place without redundancy, making it efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is largely complete—it explains the purpose, parameter requirements, and output format. However, it could improve by mentioning limitations (e.g., no filtering options) or linking to siblings for more specific data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description explicitly states 'Required: None (no parameters needed)', which adds clarity beyond the empty schema, earning a baseline above 3 for addressing the parameterless nature.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Fetches list of currently popular and trending subreddits' with a specific verb ('fetches') and resource ('subreddits'), clearly distinguishing it from sibling tools like get_subreddit_info (single subreddit) or search_reddit (search queries). The emoji '🔥 Get trending/popular subreddits' reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use it ('currently popular and trending subreddits'), but does not explicitly state when not to use it or name alternatives. It distinguishes from siblings by focusing on trending lists rather than specific subreddits or posts, though not with explicit 'vs' statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
👤 Get Reddit user profile information 🎯 What it does: Fetches detailed profile info for any Reddit user 📝 Required: username (Reddit username without u/ prefix) 💡 Examples: • Get profile: {"username": "spez"} • Check user: {"username": "AwkwardTension4482"} • View profile: {"username": "gallowboob"} 🔍 Output: User info with karma, account age, gold status, moderator status, and profile link
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | Reddit username to get profile information |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing what information is returned (karma, account age, gold status, moderator status, profile link). It also clarifies the username format requirement ('without u/ prefix'), which is valuable behavioral context not in the schema. It doesn't mention rate limits or authentication needs, but provides solid operational transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with emoji-labeled sections, each sentence earns its place. It's front-loaded with the core purpose, then provides requirements, examples, and output details without redundancy. The information density is high with zero wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation with no annotations and no output schema, the description does an excellent job covering what the tool does, parameter requirements, examples, and expected output format. The only minor gap is the lack of explicit guidance on when to use versus sibling tools, but otherwise it's quite complete for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage for the single parameter, the baseline would be 3. However, the description adds significant value by clarifying the username format ('without u/ prefix') and providing multiple concrete examples of valid usernames, which goes beyond what the schema provides about parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Fetches detailed profile info for any Reddit user' with a clear verb ('Fetches') and resource ('profile info for any Reddit user'). It distinguishes from sibling tools like get_subreddit_info by focusing specifically on user profiles rather than subreddits or posts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage through examples and the 'Required' section, showing this is for fetching user profiles. However, it doesn't explicitly state when to use this tool versus alternatives (like search_reddit for finding users) or provide exclusion criteria for when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔍 Search Reddit posts and comments 🎯 What it does: Searches across Reddit or within a specific subreddit 📝 Required: query (search terms) ⚙️ Optional: subreddit (limit search to specific subreddit) 💡 Examples: • Global search: {"query": "machine learning"} • Subreddit search: {"query": "python tutorial", "subreddit": "programming"} • Tech search: {"query": "TypeScript", "subreddit": "typescript"} 🔍 Output: Formatted search results with title, author, subreddit, score, and link
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (e.g., 'machine learning', 'python tutorial') | |
| subreddit | No | Limit to specific subreddit (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the output format (formatted results with specific fields) and implies read-only behavior through 'search', but lacks details on rate limits, authentication needs, or pagination. It adds some context but is incomplete for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with emoji icons and bullet points, making it easy to scan. It is front-loaded with the core purpose, followed by required/optional parameters, examples, and output details—all in a compact format with no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description provides basic purpose, parameters, and output format, but lacks deeper behavioral context (e.g., error handling, result limits). It is adequate for a simple search tool but could be more complete, especially in explaining limitations or integration with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explicitly labeling 'query' as required and 'subreddit' as optional, and providing examples that clarify usage (e.g., global vs. subreddit search). This enhances understanding beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches Reddit posts and comments, specifying both global and subreddit-specific searches. It distinguishes itself from siblings like get_subreddit_posts (which likely fetches posts without search) and get_post_comments (which focuses on comments for a specific post), making the purpose specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (searching across Reddit or within a subreddit) and includes examples that illustrate different scenarios. However, it does not explicitly state when not to use it or mention alternatives among sibling tools, such as using get_subreddit_posts for non-search-based retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_cross_postsget_post_commentsget_subreddit_infoget_subreddit_postsget_trending_subredditsget_user_profilesearch_redditScored across 7 tools
Each tool has a clearly distinct purpose targeting specific Reddit entities or actions: crossposts, post comments, subreddit info, subreddit posts, trending subreddits, user profiles, and search. There is no overlap in functionality, and the descriptions clearly differentiate what each tool does, making misselection unlikely.
All tool names follow a consistent verb_noun pattern using snake_case, starting with 'get_' for retrieval operations or 'search_' for search functionality. This uniformity makes the tool set predictable and easy to understand, with no deviations in naming conventions.
With 7 tools, the count is well-scoped for a Reddit server, covering core read-only operations like fetching posts, comments, subreddits, users, and search. Each tool serves a unique and necessary function without bloat, fitting typical expectations for such a domain.
The tool set provides comprehensive read-only coverage for browsing Reddit content, including posts, comments, subreddits, users, and search. A minor gap exists in write operations (e.g., posting, voting, commenting), but for a retrieval-focused server, the surface is nearly complete and supports common agent workflows without dead ends.
Browse and manage Reddit posts, comments, and threads. Fetch user activity, explore hot/new/rising…
Reddit: Reddit Data API offers streamlined access to Reddit’s public data, like posts, comments.
Read-only Reddit search API for AI agents: posts, comments, comment trees, subreddit rules.
Reddit data for AI agents: posts, comments, subreddits, search. Community + sentiment research.