Skip to main content
Glama
redditapis

RedditAPIs

by redditapis
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

reddit_subreddit_top

Read-only

Fetch the highest-scoring posts from any subreddit over a chosen time window, returning score, author, comments, and permalinks. Use the after cursor to page through results.

Instructions

Get the TOP posts of a subreddit for a time window. Shorthand for the highest-scoring posts of a community. Returns posts with score, author, comments, and permalink plus an after cursor. Example: name='science' t='month'.

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.
nameYesSubreddit name WITHOUT the r/ prefix (e.g. 'science'). Required (path parameter).
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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.3
    • changedInput schema / properties / after / description
      Previous value: -"Opaque Reddit pagination cursor from the previous response's `after` field (a fullname like `t3_abc123`). Omit on the first call; pass it to fetch the next page."New value: +"Opaque 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."
  2. First observedv0.1.12

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already establish the safe read-only, open-world profile, so the bar is lower. The description adds valuable return-shape information (score, author, comments, permalink) and notes the `after` cursor, which is useful since no output schema exists. It does not itself carry the pagination/truncation caveats, but those are thoroughly covered in the schema's `after` description.

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?

Three short sentences, front-loaded with the operation and scope, followed by the return shape and a concrete example. The second sentence is mildly redundant with the first but does sharpen what 'TOP' means; overall there is very little waste.

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

Completeness4/5

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

For a low-complexity filtered-listing tool with full schema coverage and annotations, the description covers purpose, scope, return fields, and an example. The only gap is sibling differentiation against reddit_subreddit_posts, which an agent would have to resolve from names alone.

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

Parameters3/5

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

Schema description coverage is 100%, so baseline is 3: name, t, after, and limit are all documented in the schema with formats, ranges, and cursor semantics. The description's inline example (name='science', t='month') reinforces the calling convention but adds no semantics beyond what the schema already states.

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

Purpose4/5

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

Names a specific verb (get) and resource (top posts of a subreddit) and defines the scope as the highest-scoring posts in a time window, which is meaningfully different from a generic listing. It stops short of naming the sibling it competes with (reddit_subreddit_posts), so an agent must infer the sort-based distinction from the 'TOP' wording alone.

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

Usage Guidelines3/5

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

'Shorthand for the highest-scoring posts of a community' implies the use case, and the t parameter context makes the time-window intent clear. However, there is no explicit when-to-use or when-not-to-use guidance versus reddit_subreddit_posts, reddit_home_feed, or reddit_subreddit_comments, so the routing decision is left to inference.

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