Use CiteRocket MCP as a read-only Reddit API bridge for MCP clients like Claude and Cursor.
Fetch posts from a subreddit with sorting, timeframes, pagination, and limits.
Search Reddit posts, comments, communities, media, and users, with filters like NSFW, sort, timeframe, and media kind.
Get a subreddit's top posts or its metadata, rules, and moderators.
Fetch one post by ID and retrieve a post's full comment tree by permalink.
Look up user profiles/karma, recent comments, and account status/shadowban checks.
Check your CiteRocket credits, usage, plan access, and billing overview for free.
All tools are read-only; normal calls are metered as CiteRocket API usage.
Provides tools for interacting with Reddit's API, enabling searching posts and comments, retrieving subreddit posts and metadata, reading full comment trees, and looking up user profiles, karma, and account status.
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., "@CiteRocket MCP What are the top posts on r/programming this week?"
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.
The official CiteRocket MCP server, the fastest way to use the Reddit API from an AI assistant. Give Claude, Cursor, or any Model Context Protocol client direct access to Reddit data: search Reddit posts and comments, pull a subreddit's top, read full comment trees, look up users and their karma, search communities, media and users, and run shadowban checks, all over one clean, fast, camelCase JSON API.
Tools stay current automatically. When CiteRocket ships a new endpoint, the new tool shows up on your next restart, with no reinstall and no config change.
→ Get an API key at citerocket.com · API docs · Rate limits
Add it to your MCP client config (Claude Desktop, Cursor, Windsurf, etc.):
{
"mcpServers": {
"citerocket": {
"command": "npx",
"args": ["-y", "@citerocket/reddit-mcp@latest"],
"env": {
"CITEROCKET_API_KEY": "cite_live_..."
}
}
}
}Get your CITEROCKET_API_KEY from the CiteRocket dashboard.
That's all it needs.
Or via the Claude Code CLI:
claude mcp add citerocket -e CITEROCKET_API_KEY=cite_live_... -- npx -y @citerocket/reddit-mcp@latestRelated MCP server: MCP Reddit Server
Once installed, just ask your assistant naturally:
"Find the top posts in r/programming this week" "Search Reddit for posts about the new iPhone, sorted by top" "What's u/spez's karma and account age?" "Is u/some_account shadowbanned or suspended?" "Get the full comment tree for this post: https://reddit.com/r/..." "Search r/startups comments that mention 'pricing'" "Show me the rules and moderators of r/webdev"
All tools are read-only. Query parameters are snake_case; responses are
camelCase JSON.
Tool | What it does |
| Fetch posts from a subreddit |
| Search posts across Reddit |
| A post's full comment tree |
| Fetch one post by id |
| A subreddit's top posts |
| Subreddit metadata, rules, moderators |
| User profile and karma |
| A user's recent comments |
| Account status / shadowban check |
| Search communities |
| Search comments |
| Search media |
| Search users |
| Your credit, usage, and billing snapshot |
The live set is whatever the server pulls from the manifest at startup, so this table tracks what's shipped today, not a hardcoded ceiling.
Every tool call is a normal CiteRocket API call authenticated with your
CITEROCKET_API_KEY, metered exactly like direct API usage, no separate MCP
billing. Standard reads cost 1 credit; get_cite_rocket_overview is free.
Per-plan QPS ceilings apply, see the rate limits.
Env var | Required | Purpose |
| yes | Your API key, sent as |
If CiteRocket is briefly unreachable at startup, the server falls back to the tool set bundled in the package so your existing tools keep working.
npm install
npm run build:manifest # regenerate the bundled tool manifest from the OpenAPI spec
npm run build # compile TypeScript to dist/🌐 Website: citerocket.com
📚 API docs: citerocket.com/docs
🔑 Get an API key: app.citerocket.com
📈 Status: citerocket.com/status
✉️ Support: support@citerocket.com
CiteRocket is an independent third-party API for developers and researchers. Not affiliated with, endorsed by, or sponsored by Reddit, Inc.
MIT
Return member identity, plan access, spendable credits, lifetime usage and billing history in one free request
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile, and the description adds that this is a single free request aggregating multiple data types. It does not disclose response format, data freshness, or any authentication requirements, but those are not critical given the annotation and simple zero-parameter contract.
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?
One clean sentence with no filler. The most identifying content (member identity, billing history) comes first, and the phrase 'in one free request' adds useful context without bloat.
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 zero-parameter, read-only endpoint with no output schema, the description gives a solid list of returned categories that an agent can act on. Minor omissions like authentication expectations or field formatting are unlikely to trip up an agent for an overview call.
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 tool has zero parameters, so schema coverage is trivially 100% and no parameter documentation is needed. The description instead clarifies what the returned payload covers, which is more useful than parameter detail here.
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 names a specific verb ('Return') and a concrete set of resources: member identity, plan access, spendable credits, lifetime usage, and billing history. This clearly differentiates it from the sibling get_posts, get_comments, and user/subreddit search tools, whose scope is entirely different.
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?
No explicit when-to-use guidance or alternative routing is provided. However, the unique account/billing scope makes the intended context reasonably obvious among the sibling tools, so usage is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A post's full comment tree
| Name | Required | Description | Default |
|---|---|---|---|
| permalink | Yes | Post permalink, e.g. /r/X/comments/abc/title/ |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers safety, so the description's job is lighter. The phrase 'full comment tree' usefully implies nested, complete comments for the post. However, it does not disclose pagination, ordering, or behavior for posts with no comments; these are minor for a simple read 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 extremely concise, with no filler or repeated information. Every word contributes to identifying the tool's output, and the key qualifier 'full comment tree' is front and center.
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 one-parameter, read-only tool with no output schema, the description names both the resource and the expected return shape. It could be more complete with an explicit verb or a note about nested comment structure, but the total information is likely sufficient for correct invocation.
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%, and the single permalink parameter includes a concrete example. The description itself adds no additional detail about the parameter format, so the baseline of 3 applies.
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 identifies the resource (a post's comments) and the return shape (full comment tree), which is clear enough to distinguish it from sibling comment tools like get_search_comments or get_user_by_name_comments. However, it uses a noun phrase rather than an explicit verb like 'get' or 'retrieve', so it stops short of a fully specified purpose statement.
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?
There is no guidance about when to use this tool versus alternatives. The description does not mention get_search_comments, get_user_by_name_comments, or any exclusion, leaving the agent to infer from the permalink parameter that this is for a single post's comments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one post by id
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Reddit post id, e.g. 1sgjld3 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds a minimal behavioral trait ('one post by id') but does not detail return format, error behavior, or any other context beyond the annotation.
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 a single five-word sentence with no filler. The core purpose is front-loaded and every word contributes meaning.
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 one-parameter read-only fetch, the description combined with the schema and readOnlyHint covers the essentials needed to invoke the tool correctly. Return shape and error details could be added, but they are not critical for this simple lookup tool.
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 coverage is 100% for the single required 'id' parameter, and the schema already provides type and an example. The description adds no new parameter semantics beyond the core 'by id' concept, so the baseline of 3 is appropriate.
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?
Description uses a specific verb ('Fetch'), names the resource ('post'), and identifies the lookup key ('by id'). The singular 'one' distinguishes it from sibling get_posts, so an agent can clearly select this tool for single-post lookups.
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 phrase 'by id' implies the tool should be used when the agent has a specific Reddit post id and needs that one post. However, it does not explicitly mention alternatives like get_posts or get_comments, nor does it state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch posts from a subreddit
| Name | Required | Description | Default |
|---|---|---|---|
| t | No | Timeframe for sort=top/controversial | |
| sort | No | Sort tab | new |
| after | No | Pagination cursor from a previous response | |
| limit | No | Items to return, 1-100 | |
| subreddit | Yes | Subreddit name (no r/ prefix) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, and the description simply repeats the read-only nature with 'Fetch' without adding extra behavioral context. It does not mention pagination, default limit, sort-specific behavior, or any other runtime characteristics beyond what the schema already states.
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?
A single sentence with no filler, direct and front-loaded. It communicates the essential purpose without redundancy.
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 lack of an output schema and the presence of many overlapping sibling tools, the description is too sparse. It does not clarify how get_posts relates to get_sub_by_name_top, get_sub_by_name_info, or get_search, nor does it mention that the response is a post listing. The schema covers parameters well, but tool selection context is incomplete.
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 coverage is 100%, so the baseline is 3. The description adds no parameter meaning, but also needs none because every parameter already has a descriptive schema entry.
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 'Fetch' and the resource 'posts from a subreddit', making the core function obvious. It distinguishes itself from get_comments and get_post_by_id, but does not differentiate from similar subreddit-listing siblings like get_sub_by_name_top or get_search.
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 no guidance on when to use this tool versus its many siblings. It does not mention alternatives, exclusions, or typical use cases, leaving the agent to infer selection solely from the tool name and generic description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search posts across Reddit
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query | |
| t | No | Timeframe | |
| nsfw | No | true to include NSFW results | |
| sort | No | Sort order | |
| after | No | Pagination cursor from a previous response | |
| limit | No | Items to return, 1-100 | |
| subreddit | No | Restrict to a subreddit |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already tells the agent this is a safe read operation. The description adds only the resource scope ('posts') and does not disclose rate limits, pagination behavior, or result format. This is not a contradiction, but the description adds little behavioral context beyond the annotation.
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 a single front-loaded sentence with zero wasted words. It immediately communicates the tool's purpose without restating schema details.
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 7-parameter search tool with no output schema, the one-sentence description is thin. It does not explain result shape, how the pagination cursor works, default sort/timeframe behavior, or how search syntax is interpreted. The schema covers parameter formats but not overall search semantics.
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%, with every parameter (q, t, nsfw, sort, after, limit, subreddit) already documented. The description adds no parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.
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 states a specific verb ('Search') and resource ('posts') with scope ('across Reddit'), and it distinguishes this tool from sibling search tools like get_search_comments, get_search_media, and get_search_users. An agent can tell exactly what resource this targets.
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 intended use is implied by the name and the phrase 'Search posts', and sibling names make the alternative search targets clear. However, the description does not explicitly state when to choose this tool over get_posts or other search variants, nor does it mention exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search comments
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query | |
| t | No | Timeframe | |
| nsfw | No | true to include NSFW results | |
| sort | No | Sort order | relevance |
| after | No | Pagination cursor from a previous response | |
| limit | No | Items to return, 1-100 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds no behavioral context beyond that. It does not mention pagination, result ordering, NSFW handling, or whether the search covers all comments or a limited scope; with no output schema, the agent gets little signal about behavior.
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?
Two words is concise, but this is under-specification rather than appropriately sized structure. It does not front-load any scoping or behavioral caveat and provides no value beyond restating the tool's purpose.
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 six parameters, no output schema, and a large sibling set, a two-word description is incomplete. There is no mention of what the response contains, how results are scoped, or how this differs from other comment/search 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 of 3 applies. The description itself adds no parameter meaning, but the schema already documents q, t, nsfw, sort, after, and limit clearly.
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 'Search comments' states the operation and resource, but it is essentially a restatement of the tool name and provides no scope or context. It does little to distinguish this tool from siblings like get_comments or get_search.
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?
There is no guidance on when to use this tool versus alternatives such as get_comments, get_search, or get_search_media. With many sibling search tools, the agent must infer the right choice from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search communities
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query | |
| nsfw | No | true to include NSFW results | |
| after | No | Pagination cursor from a previous response | |
| limit | No | Items to return, 1-100 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral details beyond the readOnlyHint annotation. It does not mention pagination behavior, result ordering, or any side effects, leaving the agent with no information about what happens when the tool is called.
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 extremely concise, consisting of only two words. While it is succinct, it lacks any structured information such as examples, context, or clarifying details, making it too minimal to be highly effective.
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?
The description is incomplete for a tool with four parameters and no output schema. It does not explain what 'communities' refers to, what the expected output format is, or how the parameters affect the search, leaving the agent without essential context.
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 already provides descriptions for all four parameters (q, nsfw, after, limit), so the description adds no extra meaning. The baseline of 3 is appropriate because the schema coverage is complete but the description itself contributes nothing additional.
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 states the action 'Search communities' with a clear verb and resource, but it lacks specificity about what constitutes a 'community' and the scope of the search. It is not as precise as sibling tools like get_sub_by_name_top or get_search_comments.
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 no guidance on when to use this tool versus alternatives such as get_search_comments, get_search_media, or get_search_users. It does not mention any conditions, filters, or use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search media
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query | |
| t | No | Timeframe | |
| kind | No | Media kind | all |
| nsfw | No | true to include NSFW results | |
| sort | No | Sort order | relevance |
| after | No | Pagination cursor from a previous response | |
| limit | No | Items to return, 1-100 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation is present and not contradicted, but the description contributes no behavioral detail: nothing about pagination via the 'after' cursor, default sort behavior, NSFW handling, limits, or what the response looks like. The annotation covers safety only, so the description itself is behaviorally empty.
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?
Two words are undeniably concise and front-loaded, but the brevity crosses into under-specification for a tool with seven parameters and several sibling alternatives. There is no structural content, such as a clarifying sentence, to help an agent understand the tool's purpose.
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?
Despite a fully documented schema, the description leaves out how the tool behaves, what it returns, and when it applies relative to similar sibling search tools. With no output schema and no usage context, an agent has too little information to confidently select and invoke this tool.
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 every parameter already has meaningful documentation in the schema. The description adds no additional parameter semantics beyond the word 'media,' so the baseline score of 3 is appropriate.
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 states a verb and resource ('Search media') but is essentially a restatement of the tool name and gives no indication of what exactly counts as media or how it differs from sibling search tools like get_search, get_search_communities, or get_search_users. The schema later clarifies kind filters, but the description itself is vague without that external context.
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?
There is no guidance on when to use this tool versus the many similar sibling search tools. No intended use cases, exclusions, or alternatives are mentioned, leaving the agent to infer selection criteria from the name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search users
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query | |
| nsfw | No | true to include NSFW results | |
| after | No | Pagination cursor from a previous response | |
| limit | No | Items to return, 1-100 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates this is a read-only operation, and the description adds no behavioral context beyond that. It does not mention pagination behavior, result format, rate limits, or any other operational characteristics.
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 very short and free of fluff, which is concise, but it is so minimal that it adds little value beyond the tool name. It is adequate as a bare statement of purpose but lacks meaningful structure or informative content.
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 search tool with four parameters and no output schema, the description is insufficiently complete. It does not describe what kind of user data is searched, what the response looks like, or how pagination and NSFW filtering behave. The schema covers request parameters, but the description offers almost no supporting context.
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 parameters are already documented with descriptions for q, nsfw, after, and limit. The tool description itself adds no parameter meaning, but per the baseline for complete schema coverage, a score of 3 is appropriate.
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 'Search users' clearly identifies the action (search) and the resource (users), so an agent can understand the basic purpose. However, it does not distinguish this from sibling tools like get_search or get_user_by_name, and it largely restates the tool name.
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?
There is no guidance about when to use this tool instead of alternatives such as get_search, get_user_by_name, or get_search_communities. The description implies usage only through the words 'Search users' but provides no exclusions, prerequisites, or routing hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Subreddit metadata, rules, moderators
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Subreddit name (no r/ prefix) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already conveys the safety profile, and the description adds no behavioral traits beyond the returned content. It does not contradict the annotation, but also does not disclose any additional side effects, limits, or output characteristics.
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 four words and front-loads the three key content types with no filler. It is highly concise, though converting it to an explicit sentence would slightly improve structure.
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 read-only one-parameter tool with no output schema, the description adequately outlines what the call returns (metadata, rules, moderators). It is sufficient for an agent to decide to invoke it, though it leaves the exact metadata fields unspecified.
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 only parameter, name, is fully described in the schema with a useful 'no r/ prefix' instruction (100% coverage), so the description does not need to add parameter details. It simply reinforces the subreddit context without adding new semantic value.
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 identifies the resource (subreddit) and the content categories (metadata, rules, moderators), which distinguishes it from siblings like get_sub_by_name_top that return posts. It is clear but uses a noun phrase rather than an explicit verb.
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 intended use is implied by the listed data categories—an agent would select this when it needs subreddit overviews—but there is no explicit statement of when to prefer this tool over get_sub_by_name_top or other siblings, and no when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A subreddit's top posts
| Name | Required | Description | Default |
|---|---|---|---|
| t | No | Timeframe | week |
| name | Yes | Subreddit name (no r/ prefix) | |
| after | No | Pagination cursor from a previous response | |
| limit | No | Items to return, 1-100 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true covers the safety profile, but the description adds no behavioral context beyond that. It does not mention how 'top' is determined, the default timeframe, pagination behavior, limit handling, or anything about the response, leaving the agent without useful behavioral expectations.
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?
At just five words, the description is short, but it is an under-specified fragment rather than an informative summary. It lacks a sentence structure that could carry a verb, key constraints, or context, making it more under-specification than effective conciseness.
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?
With no output schema and a parameter set that includes an enum, pagination cursor, and limit, the one-line description is insufficient. An agent cannot infer required parameters, defaults, or the shape of the return value, so the description is not complete enough for reliable invocation.
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 provides 100% description coverage for all parameters, including name, t, after, and limit, so the schema already documents their meaning. The tool description itself contributes no additional semantic information beyond what the schema provides, hence the baseline score is appropriate.
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 is a noun phrase ('A subreddit's top posts') rather than a specific verb+resource statement. It identifies the resource and scope, which helps distinguish it from subreddit info or generic post tools, but the missing action verb like 'retrieve' or 'list' makes the intended behavior less explicit.
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 no guidance on when to use this tool versus siblings such as get_posts or get_sub_by_name_info. There are no explicit conditions, alternatives, or exclusion criteria for an agent to reason about tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
User profile and karma
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Reddit username (no u/ prefix) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral detail beyond what annotations already provide. It only names the output payload ('profile and karma') and does not mention failure modes, field scope, rate limits, or whether the user must exist. The readOnlyHint annotation is present, which covers safety, but no additional behavior is disclosed.
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 only four words and contains no filler, repetition, or unnecessary detail. It is maximally concise while still communicating the core returned data.
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 one-parameter, read-only lookup tool, the description combined with the schema and annotation is mostly sufficient for an agent to invoke it correctly. The main gap is that the exact fields inside 'profile' are unspecified, but this is not critical for selecting and calling the tool.
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%, and the schema already documents the 'name' parameter including the 'no u/ prefix' instruction. The tool description adds no extra parameter semantics, so the baseline score of 3 is appropriate.
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 'User profile and karma' clearly identifies the resource being retrieved, even though it is a noun phrase rather than an explicit verb phrase like 'Gets...'. It also helps distinguish this tool from sibling tools such as get_user_by_name_comments and get_user_by_name_status by indicating that this returns the core profile and karma data.
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?
No usage guidance is provided. The description does not state when to prefer this tool over get_user_by_name_status or get_user_by_name_comments, nor does it mention any prerequisites or alternative conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A user's recent comments
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Reddit username | |
| sort | No | Sort order | new |
| after | No | Pagination cursor from a previous response | |
| limit | No | Items to return, 1-100 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile. The description adds 'recent' and 'user's' but says nothing about pagination via `after`, sort behavior, default `limit`, or what is actually returned. It does not contradict annotations, but it adds minimal behavioral context beyond them.
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 very short and contains no filler, but it is a sentence fragment rather than a well-structured definition. It is concise at the cost of completeness, and the structure does not front-load critical information beyond the vague resource phrase.
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?
With no output schema, the description should clarify return context, but it only says 'comments' without specifying ownership, response shape, or paging behavior. The schema documents inputs, but the surrounding context is too thin for confident invocation alongside similar 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%, with all four parameters (`name`, `sort`, `after`, `limit`) already documented. The description adds no new parameter-level semantics beyond implying that `name` identifies the Reddit user whose comments are retrieved, so the baseline score of 3 is appropriate.
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 identifies the resource as 'a user's recent comments,' which aligns with the tool name and the required `name` parameter. However, it is a noun phrase without a verb, and it doesn't explicitly state that it fetches comments authored by the user, leaving ambiguity versus sibling tools like `get_comments`.
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?
There is no guidance about when to use this tool versus alternatives such as `get_comments`, `get_user_by_name`, or other sibling tools. No conditions, exclusions, or alternative routing are described, so an agent receives no help selecting the correct tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Account status / shadowban check
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Reddit username (no u/ prefix) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals this is a safe read operation, and the description does not contradict that. The phrase 'shadowban check' adds some useful semantic context about what kind of read this is, but the description does not disclose details like return format, rate limits, or how status is determined.
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 extremely concise and front-loaded: 'Account status / shadowban check' conveys the core purpose in a few words with no filler or redundancy. For such a simple tool, this is appropriately sized.
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 has only one parameter, a read-only annotation, and no output schema, the short description is largely sufficient for an agent to select and invoke it correctly. It clearly signals the output domain (status/shadowban) even though it does not specify the exact response structure.
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 input schema fully documents the only parameter 'name' with a clear format warning ('no u/ prefix'), giving 100% schema coverage. The description adds no additional parameter detail, so it remains at baseline.
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 identifies the tool's function as checking account status or shadowban status, which distinguishes it from sibling tools like get_user_by_name and get_user_by_name_comments. The wording uses a specific verb ('check') and resource ('account status'). It could be slightly more explicit about what statuses are returned, but it is not vague or tautological.
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 purpose statement implies this tool should be used when account status or shadowban information is needed. However, it does not explicitly mention when to prefer this tool over get_user_by_name or other user-related tools, nor does it provide exclusions or alternative routing.
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.
v0.1.0get_cite_rocket_overviewget_commentsget_post_by_idget_postsget_searchget_search_commentsget_search_communitiesget_search_mediaget_search_usersget_sub_by_name_infoget_sub_by_name_topget_user_by_nameget_user_by_name_commentsget_user_by_name_statusScored across 14 tools
Most tools target clearly distinct resources (posts, comments, users, subreddits), but get_posts and get_sub_by_name_top both return subreddit posts, and get_search could be confused with the more specific get_search_* variants. Descriptions mostly resolve the ambiguity.
All tools consistently use the get_ prefix with snake_case, which is predictable. Some names like get_search and get_sub_by_name_top are slightly awkward or less verb-driven, but the overall pattern is coherent.
14 tools is on the higher end but reasonable for a Reddit data-access server, especially with separate search endpoints for posts, comments, communities, media, and users. Each tool has a distinct enough role that the count feels justified.
The server covers the main read-only Reddit workflows: posts, comments, subreddits, users, and search. However, there is no tool for a user's submitted posts (only comments), and subreddit-specific retrieval is limited to top posts rather than hot/new or other common listings.
Read-only Reddit search API for AI agents: posts, comments, comment trees, subreddit rules.
Browse and manage Reddit posts, comments, and threads. Fetch user activity, explore hot/new/rising…
Reddit posts, comments, subreddits, and search for AI agents. Free key, self-minted, no signup.
Reddit MCP server: search posts, subreddit feeds, comments & user profiles as JSON. No API key.