CrawlForge MCP Server

reddit_search

Read-onlyIdempotent

Search Reddit posts, comments, or full comment threads using archived data, bypassing Reddit's direct scraping blocks.

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:[...]}); collapsed branches appear as {more_count, more_ids}
`checkedAt`	No
`subreddit`	No
`discovered`	No	web_discovery: how many post ids the site-restricted web search surfaced before archive hydration
`comment_count`	No
`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

Schema Changelog

Changes observed during successful MCP inspections.

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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses substantial behavioral traits: it reads from Arctic Shift and PullPush archives, explains that Reddit blocks direct scraping, details fallback logic with fallback_used, describes timeout retry windows (7d, 3d, 1d) and window_applied, mentions PullPush's refusal of automated clients since August 2026, and notes the cost of 5 credits. This adds meaningful context that annotations alone cannot convey.

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?

The description is long but information-dense and front-loaded with the core purpose and mode overview. It covers many nuances without redundancy. It could be slightly trimmed, but every sentence earns its place given the tool's complexity, and the structure flows logically from general usage to specifics like fallbacks and exclusions.

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?

The description is comprehensive for a tool with 10 parameters and 3 enums. It explains all modes, backend behaviors, fallback mechanisms, constraints (e.g., PullPush refusal, Reddit blocking), cost, and provides a full example. With an output schema present, no additional return-value explanation is needed, and nothing critical is missing for an agent to invoke it correctly.

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 the schema already documents all parameters clearly. The description adds value by providing a concrete example (reddit_search({query: "best mechanical keyboard", subreddit: "MechanicalKeyboards", limit: 10})) and clarifying mode-specific behavior (e.g., posts matches title+selftext, comments matches body, thread requires link_id). While not essential, this contextualization helps an agent understand how parameters interact in practice.

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?

The description opens with a clear statement of purpose: 'Use this to search Reddit posts or comments, or read a full comment thread.' It names the resource (Reddit), the verbs (search, read), and distinguishes itself from siblings by explicitly stating it is not for reddit.com URLs via scrape/fetch_url, which separates it from the generic fetch_url and scraper tools.

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?

The description explicitly states when to use the tool and provides explicit exclusions: 'Not for reddit.com URLs via scrape or fetch_url (blocked) - use mode:"thread" with the post's link_id.' It also explains when to use each mode, the fallback behavior, and the two-step discovery for unscoped searches, giving clear guidance on usage contexts and alternatives.

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