CrawlForge MCP Server

reddit_search

Read-onlyIdempotent

Search Reddit posts or comments and read full threads via the Arctic Shift archive, bypassing Reddit scraping blocks without credentials.

Instructions

Use this to search Reddit posts or comments, or read a full comment thread - reddit.com blocks direct scraping, so this reads the Arctic Shift community archive instead (free, no Reddit credentials). Modes: 'posts' (default) and 'comments' search; 'thread' returns a post plus its nested comment tree by link_id. A subreddit/author-scoped search queries the archive directly. A keyword search across ALL of Reddit finds posts with a site-restricted web search and then reads those posts from the archive, because Arctic Shift can only keyword-search within a scope; results come back as real archive rows, ordered by search relevance. An unscoped COMMENT search discovers posts the same way and then searches each post's comments for the keywords. A scoped comment search Arctic Shift times out on is retried over narrower windows (7d, 3d, 1d) and reports window_applied. Arctic Shift is tried first and the PullPush archive second for posts/comments searches (fallback_used says so; PullPush has refused automated clients since August 2026). Not for reddit.com URLs via scrape or fetch_url (blocked) - use mode:'thread' with the post's link_id. Cost: 5 credits. Example: reddit_search({query: "best mechanical keyboard", subreddit: "MechanicalKeyboards", limit: 10})

Input Schema

TableJSON Schema

Name	Required	Description
`mode`	No	What to search: posts (default), comments, or thread (full comment tree — requires link_id)
`sort`	No	Sort by post date (default desc = newest first)
`after`	No	Only content posted after this date — ISO 8601, epoch seconds, or an offset like '7d'
`limit`	No	Max results (default 25; thread mode: max comments returned)
`query`	No	Keyword search. Posts: matches title+selftext; comments: matches body. Supports "quoted phrases", OR, -exclusion
`author`	No	Limit to one author (with or without the u/ prefix)
`before`	No	Only content posted before this date — same formats as after
`source`	No	Backend: auto routes + falls back (default). web_discovery serves only unscoped keyword searches (web search finds the posts, the archive supplies the rows). reddit_api uses the official Reddit Data API — only when REDDIT_CLIENT_ID/REDDIT_CLIENT_SECRET are set; serves posts/thread, not comment search
`link_id`	No	Post ID (e.g. '1twm1zh' or 't3_1twm1zh') — required for thread mode, optional filter for comments mode
`subreddit`	No	Limit to one subreddit (with or without the r/ prefix)

Output Schema

TableJSON Schema

Name	Required	Description
`mode`	No
`post`	No	thread mode: the post itself
`_cost`	No	Cost-transparency metadata (D3.5), present when injected into the text copy of the result
`count`	No
`notes`	No	Data-provenance caveats (archive freshness, coverage gaps)
`query`	No
`author`	No
`source`	No	Which backend served this result — an archive, or web discovery (site-restricted web search hydrated from the archive) for Reddit-wide keyword search
`link_id`	No	Present in thread mode
`results`	No	posts/comments modes
`comments`	No	thread mode: nested comment tree ({...comment, replies:[...]}); a collapsed branch appears as a {more_count, more_ids} stub, where more_count is how many comments it hides, replies included, and more_ids lists only the hidden direct replies, so more_ids can be shorter than more_count
`checkedAt`	No
`subreddit`	No
`discovered`	No	web_discovery: how many post ids the site-restricted web search surfaced before archive hydration
`comment_count`	No	thread mode: comments in `comments` at every depth, stubs excluded; at most limit
`fallback_used`	No	Present when the primary archive failed and the fallback served the result
`posts_searched`	No	web_discovery comments mode: how many discovered posts had their comments searched before limit was reached
`window_applied`	No	arctic_shift comments mode: the after-window ("7d"/"3d"/"1d") the search was narrowed to after the full-history search timed out; absent when the caller set after or no narrowing was needed
`comments_collapsed`	No	thread mode: the sum of every stub's more_count, i.e. comments the source holds for this thread that the response leaves out. comment_count + comments_collapsed is what the source holds; post.num_comments is Reddit's own total from when the post was read, so it can be higher (deleted, removed or not yet archived comments) or lower (comments made after that read)

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv6.19.2Oct 6, 2026

addedOutput schema / properties / comment_count / description

Added value: +"thread mode: comments in `comments` at every depth, stubs excluded; at most limit"

changedOutput schema / properties / comments / description

Previous value: -"thread mode: nested comment tree ({...comment, replies:[...]}); collapsed branches appear as {more_count, more_ids}"New value: +"thread mode: nested comment tree ({...comment, replies:[...]}); a collapsed branch appears as a {more_count, more_ids} stub, where more_count is how many comments it hides, replies included, and more_ids lists only the hidden direct replies, so more_ids can be shorter than more_count"

addedOutput schema / properties / comments_collapsed

Added value: +{
+  "description": "thread mode: the sum of every stub's more_count, i.e. comments the source holds for this thread that the response leaves out. comment_count + comments_collapsed is what the source holds; post.num_comments is Reddit's own total from when the post was read, so it can be higher (deleted, removed or not yet archived comments) or lower (comments made after that read)",
+  "type": "number"
+}

Changed4 schema fields changedv6.0.0Sep 6, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```
changedOutput schema / properties / _cost / additionalProperties
```
Previous value: -trueNew value: +{}
```

changedOutput schema / properties / post / anyOf

Previous value: -[
-  {
-    "$ref": "#/properties/results/items/anyOf/0"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "author": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "created_iso": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "created_utc": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "num_comments": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "permalink": {
+        "description": "Full reddit.com URL of the post",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "score": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "selftext": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "selftext_truncated": {
+        "type": "boolean"
+      },
+      "subreddit": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "title": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "url": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / results / items / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "properties": {
-      "author": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "created_iso": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "created_utc": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "id": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "num_comments": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "permalink": {
-        "description": "Full reddit.com URL of the post",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "score": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "selftext": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "selftext_truncated": {
-        "type": "boolean"
-      },
-      "subreddit": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "title": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "url": {
-        "type": [
-          "string",
-          "null"
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "additionalProperties": true,
-    "properties": {
-      "author": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "body": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "body_truncated": {
-        "type": "boolean"
-      },
-      "created_iso": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "created_utc": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "id": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "link_id": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "parent_id": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "permalink": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "score": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "subreddit": {
-        "type": [
-          "string",
-          "null"
-        ]
-      }
-    },
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "author": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "created_iso": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "created_utc": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "num_comments": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "permalink": {
+        "description": "Full reddit.com URL of the post",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "score": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "selftext": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "selftext_truncated": {
+        "type": "boolean"
+      },
+      "subreddit": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "title": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "url": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "additionalProperties": {},
+    "properties": {
+      "author": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "body": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "body_truncated": {
+        "type": "boolean"
+      },
+      "created_iso": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "created_utc": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "link_id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "parent_id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "permalink": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "score": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "subreddit": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  }
+]

Changed5 schema fields changedv5.6.6Sep 4, 2026

changedInput schema / properties / source / description

Previous value: -"Backend: auto routes + falls back (default). reddit_api uses the official Reddit Data API — only when REDDIT_CLIENT_ID/REDDIT_CLIENT_SECRET are set; serves posts/thread, not comment search"New value: +"Backend: auto routes + falls back (default). web_discovery serves only unscoped keyword searches (web search finds the posts, the archive supplies the rows). reddit_api uses the official Reddit Data API — only when REDDIT_CLIENT_ID/REDDIT_CLIENT_SECRET are set; serves posts/thread, not comment search"

changedInput schema / properties / source / enum

Previous value: -[
-  "auto",
-  "arctic_shift",
-  "pullpush",
-  "reddit_api"
-]New value: +[
+  "auto",
+  "arctic_shift",
+  "pullpush",
+  "reddit_api",
+  "web_discovery"
+]

addedOutput schema / properties / discovered

Added value: +{
+  "description": "web_discovery: how many post ids the site-restricted web search surfaced before archive hydration",
+  "type": "number"
+}

addedOutput schema / properties / posts_searched

Added value: +{
+  "description": "web_discovery comments mode: how many discovered posts had their comments searched before limit was reached",
+  "type": "number"
+}

addedOutput schema / properties / window_applied

Added value: +{
+  "description": "arctic_shift comments mode: the after-window (\"7d\"/\"3d\"/\"1d\") the search was narrowed to after the full-history search timed out; absent when the caller set after or no narrowing was needed",
+  "type": "string"
+}

Addedv5.1.0Aug 26, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only cover the safety profile (readOnly, idempotent, openWorld, non-destructive), but the description adds substantial behavioral context beyond them: cost (5 credits), credential requirements (free, no Reddit credentials vs reddit_api needing env vars), backend ordering and fallback, timeout/retry behavior with narrower windows and window_applied reporting, and PullPush's refusal of automated clients. This is far richer than the annotations.

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 purpose, then modes, then scoping behavior, then fallback/retry details, ending with cost and a concrete example. It is dense and every paragraph carries information, but a few clauses overlap with schema enum text (mode/source definitions) and could be trimmed.

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?

Given a read-only tool with 10 optional params, an output schema, and no required fields, the description supplies everything an agent needs: when to use each mode, credential prerequisites, backend selection and fallback behavior, credit cost, and the result-metadata signals (fallback_used, window_applied). Return-value explanation is rightly left to the output schema.

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 100%, so parameters are already documented, but the description adds routing semantics the schema cannot express — how mode:'thread' requires link_id, that unscoped keyword searches use web discovery plus archive reads, that unscoped comment searches search each post's comments, and that fallback_used/window_applied appear in results. It adds real meaning beyond the enum descriptions, though it restates mode/source enums already in the schema.

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?

Opens with a specific verb and resource ('search Reddit posts or comments, or read a full comment thread') and immediately distinguishes itself from the scraping siblings by explaining why it exists (reddit.com blocks direct scraping, so it reads Arctic Shift). An agent can tell it apart from scrape/fetch_url without opening any schema.

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

Usage Guidelines5/5

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

Explicitly states when NOT to use it ('Not for reddit.com URLs via scrape or fetch_url (blocked) - use mode:'thread' with the post's link_id') and names the alternative to use instead. It also routes between modes (posts vs comments vs thread) and explains which mode fits scoped vs unscoped searches.

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