Skip to main content
Glama
redditapis

RedditAPIs

by redditapis
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

reddit_user_upvoted

Read-only

List the posts and comments a Reddit account has upvoted. Requires login as that same account, as Reddit serves this private data only to its owner.

Instructions

List the posts and comments a Reddit account has UPVOTED. PRIVATE data -- Reddit only serves it to the account that owns it, so you must be logged in as name (see the reddit_session/loid args) or this returns 403. Mixed listing: each item is a post or a comment, tagged kind. Requires calling POST /api/reddit/login on the REST API first to get session cookies (not an MCP tool). Example: name='spez' (must match the logged-in account).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
tNoTime window, only applied when sort is 'top' or 'controversial'. E.g. 'week' = top of the past week. Ignored for other sorts.
loidYesReddit account loid cookie, from the same POST /api/reddit/login response. Required.
nameYesReddit username WITHOUT the u/ prefix. Must be the SAME account the supplied cookies belong to, or Reddit returns 403. Required (path parameter).
sortNoSort order for a user's comments. 'new' = most recent (default), 'hot', 'top' (in the `t` window), 'controversial'.
afterNoOpaque pagination cursor. Pass back the previous response's `after` value EXACTLY as it was returned; the format is not stable and a hand-written Reddit fullname loses the paging depth the cursor carries. Omit on the first call. When `after` comes back null there is no next page to request, and that does NOT reliably mean you have every item: Reddit often stops serving a busy listing long before it runs out. Read `listing_status` on that final response instead. It is `complete`, `truncated` or `unknown`, and ONLY `complete` means nothing is missing. Never report `truncated` or `unknown` to a user as the end of the data; say the answer is partial and widen across sorts, timeframes or search terms.
limitNoMax items to return (1 to 100). The API clamps out-of-range values; endpoint default applies if omitted.
csrf_tokenNoReddit CSRF cookie, from the same login response. Not required for a read (CSRF only guards state-changing calls) but harmless to pass if you have it.
reddit_sessionYesReddit account session cookie. Obtain it by calling POST /api/reddit/login on the REST API first (not an MCP tool) and reusing the `reddit_session` cookie it returns. Required.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.5.3

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnly/destructive/openWorld, and the description still adds substantial behavior: 403 if the cookies don't belong to `name`, the mixed post/comment listing tagged by `kind`, the out-of-band login step required before calling, and the `listing_status` truncation semantics with an explicit warning not to report truncated data as complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the one-line purpose, then adds only the caveats an agent needs (auth, mixed kinds, pagination). It is dense but each sentence carries operational weight; the auth/pagination guidance is slightly compressed into a single long paragraph rather than clearly separated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, open-world tool with no output schema, the description covers the riskiest unknowns: who may call it, how to authenticate, what the item kinds are, and how to interpret end-of-pagination via listing_status. Nothing essential to calling it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3, but the description ties the parameters together into an auth story (reddit_session/loid must come from the same login as `name`, csrf only needed for writes) and reinforces why mismatched `name` yields 403. It adds framing value beyond the per-field schema text without re-documenting enums.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the posts and comments a Reddit account has UPVOTED'), and the upvoted scope cleanly separates it from siblings like reddit_user_saved, reddit_user_hidden, and reddit_user_submitted. An agent can route to it without opening any other schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear precondition ('you must be logged in as `name`') and points at the required session args, plus a worked example (name='spez'). It does not explicitly compare against the other user-listing siblings, so the alternative-selection guidance is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools