reddit-mcp-server 1.4.8 → 1.5.1

package/dist/index.js

@@ -3,6 +3,93 @@ import dotenv from "dotenv";
 import { FastMCP } from "fastmcp";
 import { Left, Option, Right, Try } from "functype";
 import { z } from "zod";
+//#region src/client/errors.ts
+/**
+* Typed error channel for the Reddit client.
+*
+* The client's methods are the imperative-to-functional boundary: each captures throws
+* (network, HTTP, JSON parsing, validation, deliberate domain errors) inside a `Try` and
+* converts to a typed `Either<RedditError, T>`. Modelling the error as a discriminated ADT
+* — rather than a bare `Error` — makes the failure contract explicit at the type level, so
+* callers can reason about (and branch on) what actually went wrong without string-matching.
+*
+* `classifyRedditError` is TOTAL and never re-throws — every captured `Error` maps to a
+* variant — which is what makes the migration behavior-preserving: an error that was a
+* graceful `Left` before is still a graceful `Left` after, just with a richer type.
+*
+* Two-tier behavior, to preserve the exact messages of the original try/catch code:
+*  - A *deliberate* typed throw (HttpError, NotFoundError, …) already carries its final
+*    message, so it passes through unchanged.
+*  - An *unexpected* generic error (fetch/JSON/orThrow) is wrapped as UnknownError, with the
+*    optional `context` prefix — present for read methods (which prefixed in their catch),
+*    absent for write methods (which returned the raw message).
+*/
+var RedditErrorBase = class extends Error {};
+/** A non-ok HTTP response from the Reddit API. Carries the status for caller branching. */
+var HttpError = class extends RedditErrorBase {
+	status;
+	_tag = "HttpError";
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+		this.name = "HttpError";
+	}
+};
+/** A write operation was attempted without the required user credentials / in a wrong mode. */
+var NotAuthenticatedError = class extends RedditErrorBase {
+	_tag = "NotAuthenticatedError";
+	constructor(message) {
+		super(message);
+		this.name = "NotAuthenticatedError";
+	}
+};
+/** Reddit accepted the request but returned errors in its JSON envelope (or an unusable body). */
+var ApiError = class extends RedditErrorBase {
+	_tag = "ApiError";
+	constructor(message) {
+		super(message);
+		this.name = "ApiError";
+	}
+};
+/** The requested post/entity does not exist or is not accessible. */
+var NotFoundError = class extends RedditErrorBase {
+	_tag = "NotFoundError";
+	constructor(message) {
+		super(message);
+		this.name = "NotFoundError";
+	}
+};
+/** Client-side input or safety-policy rejection (invalid sort, duplicate-content guard). */
+var ValidationError = class extends RedditErrorBase {
+	_tag = "ValidationError";
+	constructor(message) {
+		super(message);
+		this.name = "ValidationError";
+	}
+};
+/** Any failure that is not a recognized category: network, JSON parsing, unexpected throws. */
+var UnknownError = class extends RedditErrorBase {
+	cause;
+	_tag = "UnknownError";
+	constructor(message, cause) {
+		super(message);
+		this.cause = cause;
+		this.name = "UnknownError";
+	}
+};
+function isRedditError(error) {
+	return error instanceof RedditErrorBase;
+}
+/**
+* Total classifier from a captured `Error` to a `RedditError`. Deliberate typed throws pass
+* through unchanged; everything else becomes an `UnknownError`, prefixed with `context` when
+* provided so the observable message text matches the previous try/catch-based wrapping.
+*/
+function classifyRedditError(error, context) {
+	if (isRedditError(error)) return error;
+	return new UnknownError(Option(context).fold(() => error.message, (ctx) => `${ctx}: ${error.message}`), error);
+}
+//#endregion
 //#region src/client/response-cache.ts
 const SECOND = 1e3;
 var ResponseCache = class {
@@ -65,8 +152,13 @@ var ResponseCache = class {
 };
 //#endregion
 //#region src/client/reddit-client.ts
-function toError(error) {
-	return error instanceof Error ? error : new Error(String(error));
+function listingCursor(data) {
+	const after = typeof data.after === "string" ? { after: data.after } : {};
+	const before = typeof data.before === "string" ? { before: data.before } : {};
+	return {
+		...after,
+		...before
+	};
 }
 function parsePostData(post) {
 	return {
@@ -100,6 +192,7 @@ var RedditClient = class {
 	safeMode;
 	botDisclosure;
 	cache;
+	retry;
 	accessToken;
 	tokenExpiry = 0;
 	authenticated = false;
@@ -127,6 +220,11 @@ var RedditClient = class {
 			footer: ""
 		};
 		this.cache = ((_config$cache = config.cache) === null || _config$cache === void 0 ? void 0 : _config$cache.enabled) === true ? new ResponseCache({ maxBytes: config.cache.maxBytes }) : void 0;
+		this.retry = config.retry ?? {
+			maxRetries: 3,
+			baseDelayMs: 1e3,
+			maxDelayMs: 6e4
+		};
 	}
 	determineBaseUrl() {
 		switch (this.authMode) {
@@ -136,13 +234,13 @@ var RedditClient = class {
 		}
 	}
 	async makeRequest(path, options = {}) {
-		try {
+		return (await Try.async(async () => {
 			const url = `${this.baseUrl}${path}`;
 			const method = (options.method ?? "GET").toUpperCase();
 			const cacheable = this.cache !== void 0 && method === "GET";
 			if (cacheable) {
 				const cached = this.cache.get(url);
-				if (cached !== void 0) return Right(new Response(cached.body, { status: cached.status }));
+				if (cached !== void 0) return new Response(cached.body, { status: cached.status });
 			}
 			const requiresAuth = this.authMode === "authenticated" || this.authMode === "auto" && this.hasCredentials;
 			if (requiresAuth && (Date.now() >= this.tokenExpiry || !this.authenticated)) (await this.authenticate()).orThrow();
@@ -151,30 +249,18 @@ var RedditClient = class {
 				...options.headers
 			};
 			if (requiresAuth && this.accessToken !== void 0) headers["Authorization"] = `Bearer ${this.accessToken}`;
-			const response = await fetch(url, {
-				...options,
-				headers
-			});
-			if (response.status === 401 && this.authenticated) {
-				(await this.authenticate()).orThrow();
-				const retryHeaders = {
-					...headers,
-					Authorization: `Bearer ${this.accessToken}`
-				};
-				return Right(await fetch(url, {
-					...options,
-					headers: retryHeaders
-				}));
-			}
+			const first = await this.fetchWithRetry(url, options, headers, path, 0);
+			const response = first.status === 401 && this.authenticated ? await this.fetchWithRetry(url, options, {
+				...headers,
+				Authorization: await this.reauthorize()
+			}, path, 0) : first;
 			if (cacheable && response.ok) {
 				const text = await response.text();
 				this.cache.set(url, text, response.status);
-				return Right(new Response(text, { status: response.status }));
+				return new Response(text, { status: response.status });
 			}
-			return Right(response);
-		} catch (error) {
-			return Left(toError(error));
-		}
+			return response;
+		})).toEither((error) => error);
 	}
 	async authenticate() {
 		if (this.authMode === "anonymous") {
@@ -186,9 +272,9 @@ var RedditClient = class {
 			this.authenticated = false;
 			return Right(void 0);
 		}
-		try {
+		return (await Try.async(async () => {
 			const now = Date.now();
-			if (this.accessToken !== void 0 && now < this.tokenExpiry) return Right(void 0);
+			if (this.accessToken !== void 0 && now < this.tokenExpiry) return;
 			const authUrl = "https://www.reddit.com/api/v1/access_token";
 			const authData = new URLSearchParams();
 			const { username } = this;
@@ -210,16 +296,13 @@ var RedditClient = class {
 			});
 			if (!response.ok) {
 				const statusText = response.statusText !== "" ? response.statusText : "Unknown Error";
-				return Left(/* @__PURE__ */ new Error(`Authentication failed: ${response.status} ${statusText}`));
+				throw new Error(`Authentication failed: ${response.status} ${statusText}`);
 			}
 			const data = await response.json();
 			this.accessToken = data.access_token;
 			this.tokenExpiry = now + data.expires_in * 1e3;
 			this.authenticated = true;
-			return Right(void 0);
-		} catch (error) {
-			return Left(toError(error));
-		}
+		})).toEither((error) => error);
 	}
 	async checkAuthentication() {
 		if (!this.authenticated) return (await this.authenticate()).isRight();
@@ -227,8 +310,8 @@ var RedditClient = class {
 	}
 	validateWriteAccess() {
 		if (this.username === void 0 || this.password === void 0) {
-			if (this.authMode === "anonymous") throw new Error("Write operations not available in anonymous mode. Set REDDIT_USERNAME, REDDIT_PASSWORD and use 'auto' or 'authenticated' mode.");
-			throw new Error("Write operations require REDDIT_USERNAME and REDDIT_PASSWORD");
+			if (this.authMode === "anonymous") throw new NotAuthenticatedError("Write operations not available in anonymous mode. Set REDDIT_USERNAME, REDDIT_PASSWORD and use 'auto' or 'authenticated' mode.");
+			throw new NotAuthenticatedError("Write operations require REDDIT_USERNAME and REDDIT_PASSWORD");
 		}
 	}
 	async enforceWriteRateLimit() {
@@ -249,8 +332,8 @@ var RedditClient = class {
 		const hash = this.hashContent(content);
 		const duplicate = this.recentContentRecords.find((record) => record.hash === hash);
 		if (duplicate !== void 0) {
-			if (subreddit !== void 0 && duplicate.subreddit !== "" && subreddit !== duplicate.subreddit) throw new Error("Cross-subreddit duplicate detected. Reddit's Responsible Builder Policy prohibits posting identical or substantially similar content across multiple subreddits. Please create unique content for each subreddit.");
-			throw new Error("Duplicate content detected. Reddit's spam filter may ban your account for posting identical content. Please modify your content and try again.");
+			if (subreddit !== void 0 && duplicate.subreddit !== "" && subreddit !== duplicate.subreddit) throw new ValidationError("Cross-subreddit duplicate detected. Reddit's Responsible Builder Policy prohibits posting identical or substantially similar content across multiple subreddits. Please create unique content for each subreddit.");
+			throw new ValidationError("Duplicate content detected. Reddit's spam filter may ban your account for posting identical content. Please modify your content and try again.");
 		}
 		this.recentContentRecords.push({
 			hash,
@@ -259,16 +342,49 @@ var RedditClient = class {
 		});
 		this.recentContentRecords = this.recentContentRecords.slice(-this.safeMode.maxRecentHashes);
 	}
+	async reauthorize() {
+		(await this.authenticate()).orThrow();
+		return `Bearer ${this.accessToken}`;
+	}
+	async fetchWithRetry(url, options, headers, path, attempt) {
+		const response = await fetch(url, {
+			...options,
+			headers
+		});
+		if (response.status !== 429 || attempt >= this.retry.maxRetries) return response;
+		const wait = this.retryAfterMs(response).fold(() => Math.min(this.retry.baseDelayMs * 2 ** attempt, this.retry.maxDelayMs), (ms) => ms);
+		if (wait > this.retry.maxDelayMs) return response;
+		console.error(`[RateLimit] 429 from ${path} — retry ${attempt + 1}/${this.retry.maxRetries} in ${wait}ms`);
+		await new Promise((resolve) => setTimeout(resolve, wait));
+		return this.fetchWithRetry(url, options, headers, path, attempt + 1);
+	}
+	retryAfterMs(response) {
+		const { headers } = response;
+		const retryAfter = headers.get("retry-after");
+		if (retryAfter !== null && retryAfter !== "") {
+			const seconds = Number(retryAfter);
+			if (!Number.isNaN(seconds)) return Option(seconds * 1e3);
+			const when = Date.parse(retryAfter);
+			if (!Number.isNaN(when)) return Option(Math.max(0, when - Date.now()));
+		}
+		const reset = headers.get("x-ratelimit-reset");
+		if (reset !== null && reset !== "") {
+			const seconds = Number(reset);
+			if (!Number.isNaN(seconds)) return Option(seconds * 1e3);
+		}
+		return Option.none();
+	}
 	appendBotDisclosure(content) {
 		if (!this.botDisclosure.enabled || this.botDisclosure.footer === "") return content;
 		return `${content}${this.botDisclosure.footer}`;
 	}
 	async getUser(username) {
-		try {
+		const context = `Failed to get user info for ${username}`;
+		return (await Try.async(async () => {
 			const response = (await this.makeRequest(`/user/${username}/about.json`)).orThrow();
-			if (!response.ok) return Left(/* @__PURE__ */ new Error(`Failed to get user info for ${username}: HTTP ${response.status}`));
+			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
 			const { data } = await response.json();
-			return Right({
+			return {
 				name: data.name,
 				id: data.id,
 				commentKarma: data.comment_karma,
@@ -279,17 +395,79 @@ var RedditClient = class {
 				isEmployee: data.is_employee,
 				createdUtc: data.created_utc,
 				profileUrl: `https://reddit.com/user/${data.name}`
-			});
-		} catch (error) {
-			return Left(/* @__PURE__ */ new Error(`Failed to get user info for ${username}: ${toError(error).message}`));
-		}
+			};
+		})).toEither((error) => classifyRedditError(error, context));
+	}
+	async getUserContent(path, context) {
+		return (await Try.async(async () => {
+			const response = (await this.makeRequest(path)).orThrow();
+			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
+			const json = await response.json();
+			return {
+				posts: json.data.children.filter((child) => child.kind === "t3").map((child) => parsePostData(child.data)),
+				comments: json.data.children.filter((child) => child.kind === "t1").map((child) => {
+					const comment = child.data;
+					return {
+						id: comment.id,
+						author: comment.author,
+						body: comment.body ?? "",
+						score: comment.score,
+						controversiality: comment.controversiality,
+						subreddit: comment.subreddit,
+						submissionTitle: comment.link_title ?? "",
+						createdUtc: comment.created_utc,
+						edited: Boolean(comment.edited),
+						isSubmitter: comment.is_submitter,
+						permalink: comment.permalink,
+						parentId: comment.parent_id
+					};
+				}),
+				...listingCursor(json.data)
+			};
+		})).toEither((error) => classifyRedditError(error, context));
+	}
+	async getMyOverview(options = {}) {
+		if (this.username === void 0) return Left(new NotAuthenticatedError("Fetching your overview requires REDDIT_USERNAME"));
+		const { limit = 25, after } = options;
+		const params = new URLSearchParams({ limit: limit.toString() });
+		if (after !== void 0) params.set("after", after);
+		return this.getUserContent(`/user/${this.username}/overview.json?${params}`, "Failed to get your overview");
+	}
+	async getMySaved(options = {}) {
+		if (this.username === void 0) return Left(new NotAuthenticatedError("Fetching saved content requires REDDIT_USERNAME"));
+		const { limit = 25, after } = options;
+		const params = new URLSearchParams({ limit: limit.toString() });
+		if (after !== void 0) params.set("after", after);
+		return this.getUserContent(`/user/${this.username}/saved.json?${params}`, "Failed to get saved content");
+	}
+	async getMe() {
+		if (this.username === void 0) return Left(new NotAuthenticatedError("Fetching your account requires REDDIT_USERNAME"));
+		const context = "Failed to get authenticated user info";
+		return (await Try.async(async () => {
+			const response = (await this.makeRequest("/api/v1/me")).orThrow();
+			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
+			const data = await response.json();
+			return {
+				name: data.name,
+				id: data.id,
+				commentKarma: data.comment_karma,
+				linkKarma: data.link_karma,
+				totalKarma: data.total_karma ?? data.comment_karma + data.link_karma,
+				isMod: data.is_mod,
+				isGold: data.is_gold,
+				isEmployee: data.is_employee,
+				createdUtc: data.created_utc,
+				profileUrl: `https://reddit.com/user/${data.name}`
+			};
+		})).toEither((error) => classifyRedditError(error, context));
 	}
 	async getSubredditInfo(subredditName) {
-		try {
+		const context = `Failed to get subreddit info for ${subredditName}`;
+		return (await Try.async(async () => {
 			const response = (await this.makeRequest(`/r/${subredditName}/about.json`)).orThrow();
-			if (!response.ok) return Left(/* @__PURE__ */ new Error(`Failed to get subreddit info for ${subredditName}: HTTP ${response.status}`));
+			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
 			const { data } = await response.json();
-			return Right({
+			return {
 				displayName: data.display_name,
 				title: data.title,
 				description: data.description,
@@ -300,26 +478,56 @@ var RedditClient = class {
 				over18: data.over18,
 				subredditType: data.subreddit_type,
 				url: data.url
-			});
-		} catch (error) {
-			return Left(/* @__PURE__ */ new Error(`Failed to get subreddit info for ${subredditName}: ${toError(error).message}`));
-		}
+			};
+		})).toEither((error) => classifyRedditError(error, context));
 	}
-	async getTopPosts(subreddit, timeFilter = "week", limit = 10) {
+	async getSubredditRules(subreddit) {
+		const context = `Failed to get rules for r/${subreddit}`;
+		return (await Try.async(async () => {
+			const response = (await this.makeRequest(`/r/${subreddit}/about/rules.json`)).orThrow();
+			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
+			return (await response.json()).rules.map((rule) => ({
+				shortName: rule.short_name,
+				description: rule.description,
+				kind: rule.kind,
+				violationReason: rule.violation_reason,
+				priority: rule.priority,
+				createdUtc: rule.created_utc
+			}));
+		})).toEither((error) => classifyRedditError(error, context));
+	}
+	async getPostFlairs(subreddit) {
+		const context = `Failed to get post flairs for r/${subreddit}`;
+		return (await Try.async(async () => {
+			const response = (await this.makeRequest(`/r/${subreddit}/api/link_flair_v2.json`)).orThrow();
+			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
+			return (await response.json()).map((flair) => ({
+				id: flair.id,
+				text: flair.text,
+				type: flair.type,
+				textEditable: flair.text_editable
+			}));
+		})).toEither((error) => classifyRedditError(error, context));
+	}
+	async getTopPosts(subreddit, timeFilter = "week", limit = 10, after) {
 		const endpoint = subreddit !== "" ? `/r/${subreddit}/top.json` : "/top.json";
 		const params = new URLSearchParams({
 			t: timeFilter,
 			limit: limit.toString()
 		});
-		try {
+		if (after !== void 0) params.set("after", after);
+		const context = `Failed to get top posts for ${subreddit !== "" ? subreddit : "home"}`;
+		return (await Try.async(async () => {
 			const response = (await this.makeRequest(`${endpoint}?${params}`)).orThrow();
-			if (!response.ok) return Left(/* @__PURE__ */ new Error(`Failed to get top posts: HTTP ${response.status}`));
-			return Right((await response.json()).data.children.map((child) => parsePostData(child.data)));
-		} catch (error) {
-			return Left(/* @__PURE__ */ new Error(`Failed to get top posts for ${subreddit !== "" ? subreddit : "home"}: ${toError(error).message}`));
-		}
+			if (!response.ok) throw new HttpError(response.status, `Failed to get top posts: HTTP ${response.status}`);
+			const json = await response.json();
+			return {
+				items: json.data.children.map((child) => parsePostData(child.data)),
+				...listingCursor(json.data)
+			};
+		})).toEither((error) => classifyRedditError(error, context));
 	}
-	async browseSubreddit(subreddit, sort = "hot", timeFilter = "week", limit = 10) {
+	async browseSubreddit(subreddit, sort = "hot", timeFilter = "week", limit = 10, after) {
 		const validSorts = [
 			"hot",
 			"new",
@@ -327,43 +535,46 @@ var RedditClient = class {
 			"rising",
 			"controversial"
 		];
-		if (!validSorts.includes(sort)) return Left(/* @__PURE__ */ new Error(`Invalid sort "${sort}". Valid options are: ${validSorts.join(", ")}`));
+		if (!validSorts.includes(sort)) return Left(new ValidationError(`Invalid sort "${sort}". Valid options are: ${validSorts.join(", ")}`));
 		const endpoint = subreddit !== "" ? `/r/${subreddit}/${sort}.json` : `/${sort}.json`;
 		const params = new URLSearchParams({ limit: limit.toString() });
 		if (sort === "top" || sort === "controversial") params.set("t", timeFilter);
-		try {
+		if (after !== void 0) params.set("after", after);
+		const home = subreddit !== "" ? subreddit : "home";
+		const context = `Failed to browse r/${home} (${sort})`;
+		return (await Try.async(async () => {
 			const response = (await this.makeRequest(`${endpoint}?${params}`)).orThrow();
-			if (!response.ok) return Left(/* @__PURE__ */ new Error(`Failed to browse r/${subreddit !== "" ? subreddit : "home"}: HTTP ${response.status}`));
-			return Right((await response.json()).data.children.map((child) => parsePostData(child.data)));
-		} catch (error) {
-			return Left(/* @__PURE__ */ new Error(`Failed to browse r/${subreddit !== "" ? subreddit : "home"} (${sort}): ${toError(error).message}`));
-		}
+			if (!response.ok) throw new HttpError(response.status, `Failed to browse r/${home}: HTTP ${response.status}`);
+			const json = await response.json();
+			return {
+				items: json.data.children.map((child) => parsePostData(child.data)),
+				...listingCursor(json.data)
+			};
+		})).toEither((error) => classifyRedditError(error, context));
 	}
 	async getPost(postId, subreddit) {
 		const endpoint = Option(subreddit).fold(() => `/api/info.json?id=t3_${postId}`, (sr) => `/r/${sr}/comments/${postId}.json`);
-		try {
+		const context = `Failed to get post with ID ${postId}`;
+		return (await Try.async(async () => {
 			const response = (await this.makeRequest(endpoint)).orThrow();
-			if (!response.ok) return Left(/* @__PURE__ */ new Error(`Failed to get post with ID ${postId}: HTTP ${response.status}`));
-			if (subreddit !== void 0) return Right(parsePostData((await response.json())[0].data.children[0].data));
+			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
+			if (subreddit !== void 0) return parsePostData((await response.json())[0].data.children[0].data);
 			const json = await response.json();
-			if (json.data.children.length === 0) return Left(/* @__PURE__ */ new Error(`Post with ID ${postId} not found`));
-			return Right(parsePostData(json.data.children[0].data));
-		} catch (error) {
-			return Left(/* @__PURE__ */ new Error(`Failed to get post with ID ${postId}: ${toError(error).message}`));
-		}
+			if (json.data.children.length === 0) throw new NotFoundError(`Post with ID ${postId} not found`);
+			return parsePostData(json.data.children[0].data);
+		})).toEither((error) => classifyRedditError(error, context));
 	}
 	async getTrendingSubreddits(limit = 5) {
 		const params = new URLSearchParams({ limit: limit.toString() });
-		try {
+		const context = `Failed to get trending subreddits`;
+		return (await Try.async(async () => {
 			const response = (await this.makeRequest(`/subreddits/popular.json?${params}`)).orThrow();
-			if (!response.ok) return Left(/* @__PURE__ */ new Error(`Failed to get trending subreddits: HTTP ${response.status}`));
-			return Right((await response.json()).data.children.map((child) => child.data.display_name));
-		} catch (error) {
-			return Left(/* @__PURE__ */ new Error(`Failed to get trending subreddits: ${toError(error).message}`));
-		}
+			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
+			return (await response.json()).data.children.map((child) => child.data.display_name);
+		})).toEither((error) => classifyRedditError(error, context));
 	}
-	async createPost(subreddit, title, content, isSelf = true) {
-		try {
+	async createPost(subreddit, title, content, isSelf = true, flairId, flairText) {
+		return (await Try.async(async () => {
 			var _json$json$data, _json$json$data2;
 			this.validateWriteAccess();
 			await this.enforceWriteRateLimit();
@@ -376,35 +587,30 @@ var RedditClient = class {
 			params.append("title", title);
 			params.append(isSelf ? "text" : "url", finalContent);
 			params.append("api_type", "json");
+			if (flairId !== void 0) params.append("flair_id", flairId);
+			if (flairText !== void 0) params.append("flair_text", flairText);
 			const response = (await this.makeRequest("/api/submit", {
 				method: "POST",
 				headers: { "Content-Type": "application/x-www-form-urlencoded" },
 				body: params.toString()
 			})).orThrow();
-			if (!response.ok) return Left(/* @__PURE__ */ new Error(`Failed to create post: HTTP ${response.status}`));
+			if (!response.ok) throw new HttpError(response.status, `Failed to create post: HTTP ${response.status}`);
 			const json = await response.json();
-			if (json.json.errors !== void 0 && json.json.errors.length > 0) {
-				const errors = json.json.errors.map((e) => e[1]).join(", ");
-				return Left(/* @__PURE__ */ new Error(`Reddit API errors: ${errors}`));
-			}
+			if (json.json.errors !== void 0 && json.json.errors.length > 0) throw new ApiError(`Reddit API errors: ${json.json.errors.map((e) => e[1]).join(", ")}`);
 			const postId = ((_json$json$data = json.json.data) === null || _json$json$data === void 0 ? void 0 : _json$json$data.id) ?? ((_json$json$data2 = json.json.data) === null || _json$json$data2 === void 0 || (_json$json$data2 = _json$json$data2.name) === null || _json$json$data2 === void 0 ? void 0 : _json$json$data2.replace("t3_", ""));
-			if (postId === void 0) return Left(/* @__PURE__ */ new Error("No post ID returned from Reddit"));
-			return this.getPost(postId, subreddit);
-		} catch (error) {
-			return Left(toError(error));
-		}
+			if (postId === void 0) throw new ApiError("No post ID returned from Reddit");
+			return (await this.getPost(postId, subreddit)).orThrow();
+		})).toEither((error) => classifyRedditError(error));
 	}
 	async checkPostExists(postId) {
-		try {
+		return (await Try.async(async () => {
 			const response = (await this.makeRequest(`/api/info.json?id=t3_${postId}`)).orThrow();
 			if (!response.ok) return false;
 			return (await response.json()).data.children.length > 0;
-		} catch {
-			return false;
-		}
+		})).orElse(false);
 	}
 	async replyToPost(postId, content) {
-		try {
+		return (await Try.async(async () => {
 			var _json$json$data3;
 			this.validateWriteAccess();
 			await this.enforceWriteRateLimit();
@@ -412,7 +618,7 @@ var RedditClient = class {
 			const finalContent = this.appendBotDisclosure(content);
 			const fullThingId = postId.startsWith("t3_") || postId.startsWith("t1_") ? postId : `t3_${postId}`;
 			if (!postId.startsWith("t1_")) {
-				if (!await this.checkPostExists(postId.replace(/^t3_/, ""))) return Left(/* @__PURE__ */ new Error(`Post with ID ${postId} does not exist or is not accessible`));
+				if (!await this.checkPostExists(postId.replace(/^t3_/, ""))) throw new NotFoundError(`Post with ID ${postId} does not exist or is not accessible`);
 			}
 			const params = new URLSearchParams();
 			params.append("thing_id", fullThingId);
@@ -423,12 +629,12 @@ var RedditClient = class {
 				headers: { "Content-Type": "application/x-www-form-urlencoded" },
 				body: params.toString()
 			})).orThrow();
-			if (!response.ok) return Left(/* @__PURE__ */ new Error(`Failed to reply: HTTP ${response.status}`));
+			if (!response.ok) throw new HttpError(response.status, `Failed to reply: HTTP ${response.status}`);
 			const json = await response.json();
 			if (((_json$json$data3 = json.json.data) === null || _json$json$data3 === void 0 ? void 0 : _json$json$data3.things) !== void 0 && json.json.data.things.length > 0) {
 				const commentData = json.json.data.things[0].data;
 				const author = this.username ?? "[unknown]";
-				return Right({
+				return {
 					id: commentData.id,
 					author,
 					body: content,
@@ -440,17 +646,13 @@ var RedditClient = class {
 					edited: false,
 					isSubmitter: false,
 					permalink: commentData.permalink
-				});
-			} else if (json.json.errors !== void 0 && json.json.errors.length > 0) {
-				const errors = json.json.errors.map((e) => e[1]).join(", ");
-				return Left(/* @__PURE__ */ new Error(`Reddit API errors: ${errors}`));
-			} else return Left(/* @__PURE__ */ new Error("Failed to parse reply response"));
-		} catch (error) {
-			return Left(toError(error));
-		}
+				};
+			} else if (json.json.errors !== void 0 && json.json.errors.length > 0) throw new ApiError(`Reddit API errors: ${json.json.errors.map((e) => e[1]).join(", ")}`);
+			else throw new ApiError("Failed to parse reply response");
+		})).toEither((error) => classifyRedditError(error));
 	}
 	async deletePost(thingId) {
-		try {
+		return (await Try.async(async () => {
 			this.validateWriteAccess();
 			const fullThingId = thingId.startsWith("t3_") || thingId.startsWith("t1_") ? thingId : `t3_${thingId}`;
 			const params = new URLSearchParams();
@@ -464,21 +666,21 @@ var RedditClient = class {
 				const errorText = await response.text();
 				console.error(`[Reddit API] Delete failed: ${response.status} ${response.statusText}`);
 				console.error(`[Reddit API] Error response: ${errorText}`);
-				return Left(/* @__PURE__ */ new Error(`HTTP ${response.status}: ${errorText}`));
+				throw new HttpError(response.status, `HTTP ${response.status}: ${errorText}`);
 			}
 			console.error(`[Reddit API] Successfully deleted ${fullThingId}`);
-			return Right(true);
-		} catch (error) {
-			console.error(`[Reddit API] Delete exception:`, error);
-			return Left(toError(error));
-		}
+			return true;
+		})).toEither((error) => {
+			if (!isRedditError(error)) console.error(`[Reddit API] Delete exception:`, error);
+			return classifyRedditError(error);
+		});
 	}
 	async deleteComment(thingId) {
 		const fullThingId = thingId.startsWith("t1_") ? thingId : `t1_${thingId}`;
 		return this.deletePost(fullThingId);
 	}
 	async editPost(thingId, newText) {
-		try {
+		return (await Try.async(async () => {
 			this.validateWriteAccess();
 			await this.enforceWriteRateLimit();
 			this.checkDuplicateContent(newText);
@@ -493,23 +695,18 @@ var RedditClient = class {
 				headers: { "Content-Type": "application/x-www-form-urlencoded" },
 				body: params.toString()
 			})).orThrow();
-			if (!response.ok) return Left(/* @__PURE__ */ new Error(`Failed to edit: HTTP ${response.status}`));
+			if (!response.ok) throw new HttpError(response.status, `Failed to edit: HTTP ${response.status}`);
 			const json = await response.json();
-			if (json.json.errors !== void 0 && json.json.errors.length > 0) {
-				const errors = json.json.errors.map((e) => e[1]).join(", ");
-				return Left(/* @__PURE__ */ new Error(`Reddit API errors: ${errors}`));
-			}
-			return Right(true);
-		} catch (error) {
-			return Left(toError(error));
-		}
+			if (json.json.errors !== void 0 && json.json.errors.length > 0) throw new ApiError(`Reddit API errors: ${json.json.errors.map((e) => e[1]).join(", ")}`);
+			return true;
+		})).toEither((error) => classifyRedditError(error));
 	}
 	async editComment(thingId, newText) {
 		const fullThingId = thingId.startsWith("t1_") ? thingId : `t1_${thingId}`;
 		return this.editPost(fullThingId, newText);
 	}
 	async searchReddit(query, options = {}) {
-		const { subreddit, sort = "relevance", timeFilter = "all", limit = 25, type = "link" } = options;
+		const { subreddit, sort = "relevance", timeFilter = "all", limit = 25, type = "link", after, before } = options;
 		const endpoint = Option(subreddit).fold(() => "/search.json", (sr) => `/r/${sr}/search.json`);
 		const params = new URLSearchParams({
 			q: query,
@@ -517,15 +714,20 @@ var RedditClient = class {
 			t: timeFilter,
 			limit: limit.toString(),
 			type,
-			...subreddit !== void 0 ? { restrict_sr: "true" } : {}
+			...subreddit !== void 0 ? { restrict_sr: "true" } : {},
+			...after !== void 0 ? { after } : {},
+			...before !== void 0 ? { before } : {}
 		});
-		try {
+		const context = `Failed to search Reddit for: ${query}`;
+		return (await Try.async(async () => {
 			const response = (await this.makeRequest(`${endpoint}?${params}`)).orThrow();
-			if (!response.ok) return Left(/* @__PURE__ */ new Error(`Failed to search Reddit: HTTP ${response.status}`));
-			return Right((await response.json()).data.children.filter((child) => child.kind === "t3").map((child) => parsePostData(child.data)));
-		} catch (error) {
-			return Left(/* @__PURE__ */ new Error(`Failed to search Reddit for: ${query}: ${toError(error).message}`));
-		}
+			if (!response.ok) throw new HttpError(response.status, `Failed to search Reddit: HTTP ${response.status}`);
+			const json = await response.json();
+			return {
+				items: json.data.children.filter((child) => child.kind === "t3").map((child) => parsePostData(child.data)),
+				...listingCursor(json.data)
+			};
+		})).toEither((error) => classifyRedditError(error, context));
 	}
 	async getPostComments(postId, subreddit, options = {}) {
 		const { sort = "best", limit = 100 } = options;
@@ -533,9 +735,10 @@ var RedditClient = class {
 			sort,
 			limit: limit.toString()
 		});
-		try {
+		const context = `Failed to get comments for post ${postId}`;
+		return (await Try.async(async () => {
 			const response = (await this.makeRequest(`/r/${subreddit}/comments/${postId}.json?${params}`)).orThrow();
-			if (!response.ok) return Left(/* @__PURE__ */ new Error(`Failed to get comments: HTTP ${response.status}`));
+			if (!response.ok) throw new HttpError(response.status, `Failed to get comments: HTTP ${response.status}`);
 			const json = await response.json();
 			const postData = json[0].data.children[0].data;
 			const post = parsePostData(postData);
@@ -559,58 +762,95 @@ var RedditClient = class {
 				const { replies } = item.data;
 				return [comment, ...replies !== void 0 && typeof replies !== "string" ? parseComments(replies.data.children, depth + 1) : []];
 			});
-			return Right({
+			return {
 				post,
 				comments: parseComments(json[1].data.children)
+			};
+		})).toEither((error) => classifyRedditError(error, context));
+	}
+	async getMoreComments(linkId, commentIds) {
+		const fullLinkId = linkId.startsWith("t3_") ? linkId : `t3_${linkId}`;
+		const context = `Failed to expand comments for ${fullLinkId}`;
+		const params = new URLSearchParams({
+			api_type: "json",
+			link_id: fullLinkId,
+			children: commentIds.join(",")
+		});
+		return (await Try.async(async () => {
+			var _json$json$data4;
+			const response = (await this.makeRequest(`/api/morechildren?${params}`)).orThrow();
+			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
+			return (((_json$json$data4 = (await response.json()).json.data) === null || _json$json$data4 === void 0 ? void 0 : _json$json$data4.things) ?? []).filter((thing) => thing.kind === "t1" && thing.data.body !== void 0).map((thing) => {
+				const comment = thing.data;
+				return {
+					id: comment.id,
+					author: comment.author,
+					body: comment.body ?? "",
+					score: comment.score,
+					controversiality: comment.controversiality,
+					subreddit: comment.subreddit,
+					submissionTitle: comment.link_title ?? "",
+					createdUtc: comment.created_utc,
+					edited: Boolean(comment.edited),
+					isSubmitter: comment.is_submitter,
+					permalink: comment.permalink,
+					parentId: comment.parent_id
+				};
 			});
-		} catch (error) {
-			return Left(/* @__PURE__ */ new Error(`Failed to get comments for post ${postId}: ${toError(error).message}`));
-		}
+		})).toEither((error) => classifyRedditError(error, context));
 	}
 	async getUserPosts(username, options = {}) {
-		const { sort = "new", timeFilter = "all", limit = 25 } = options;
+		const { sort = "new", timeFilter = "all", limit = 25, after } = options;
 		const params = new URLSearchParams({
 			sort,
 			t: timeFilter,
 			limit: limit.toString()
 		});
-		try {
+		if (after !== void 0) params.set("after", after);
+		const context = `Failed to get posts for user ${username}`;
+		return (await Try.async(async () => {
 			const response = (await this.makeRequest(`/user/${username}/submitted.json?${params}`)).orThrow();
-			if (!response.ok) return Left(/* @__PURE__ */ new Error(`Failed to get posts for user ${username}: HTTP ${response.status}`));
-			return Right((await response.json()).data.children.filter((child) => child.kind === "t3").map((child) => parsePostData(child.data)));
-		} catch (error) {
-			return Left(/* @__PURE__ */ new Error(`Failed to get posts for user ${username}: ${toError(error).message}`));
-		}
+			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
+			const json = await response.json();
+			return {
+				items: json.data.children.filter((child) => child.kind === "t3").map((child) => parsePostData(child.data)),
+				...listingCursor(json.data)
+			};
+		})).toEither((error) => classifyRedditError(error, context));
 	}
 	async getUserComments(username, options = {}) {
-		const { sort = "new", timeFilter = "all", limit = 25 } = options;
+		const { sort = "new", timeFilter = "all", limit = 25, after } = options;
 		const params = new URLSearchParams({
 			sort,
 			t: timeFilter,
 			limit: limit.toString()
 		});
-		try {
+		if (after !== void 0) params.set("after", after);
+		const context = `Failed to get comments for user ${username}`;
+		return (await Try.async(async () => {
 			const response = (await this.makeRequest(`/user/${username}/comments.json?${params}`)).orThrow();
-			if (!response.ok) return Left(/* @__PURE__ */ new Error(`Failed to get comments for user ${username}: HTTP ${response.status}`));
-			return Right((await response.json()).data.children.filter((child) => child.kind === "t1").map((child) => {
-				const comment = child.data;
-				return {
-					id: comment.id,
-					author: comment.author,
-					body: comment.body ?? "",
-					score: comment.score,
-					controversiality: comment.controversiality,
-					subreddit: comment.subreddit,
-					submissionTitle: comment.link_title ?? "",
-					createdUtc: comment.created_utc,
-					edited: Boolean(comment.edited),
-					isSubmitter: comment.is_submitter,
-					permalink: comment.permalink
-				};
-			}));
-		} catch (error) {
-			return Left(/* @__PURE__ */ new Error(`Failed to get comments for user ${username}: ${toError(error).message}`));
-		}
+			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
+			const json = await response.json();
+			return {
+				items: json.data.children.filter((child) => child.kind === "t1").map((child) => {
+					const comment = child.data;
+					return {
+						id: comment.id,
+						author: comment.author,
+						body: comment.body ?? "",
+						score: comment.score,
+						controversiality: comment.controversiality,
+						subreddit: comment.subreddit,
+						submissionTitle: comment.link_title ?? "",
+						createdUtc: comment.created_utc,
+						edited: Boolean(comment.edited),
+						isSubmitter: comment.is_submitter,
+						permalink: comment.permalink
+					};
+				}),
+				...listingCursor(json.data)
+			};
+		})).toEither((error) => classifyRedditError(error, context));
 	}
 };
 const clientHolder = { instance: Option.none() };
@@ -752,7 +992,7 @@ function formatSubredditInfo(subreddit) {
 //#endregion
 //#region src/index.ts
 dotenv.config({ quiet: true });
-const VERSION = "1.4.8";
+const VERSION = "1.5.1";
 function validateUserAgent(userAgent, username) {
 	if (!/^[\w-]+:[\w-]+:[\d.]+ \(by \/u\/\w+\)$/.test(userAgent)) {
 		console.error("[Warning] User-Agent does not follow Reddit's recommended format");
@@ -803,6 +1043,15 @@ function buildSafeModeConfig(safeMode) {
 function unwrapClient() {
 	return getRedditClient().orThrow(/* @__PURE__ */ new Error("Reddit client not initialized"));
 }
+function nextPageHint(after) {
+	return Option(after).fold(() => "", (cursor) => `\n\n---\nMore results available — call again with after="${cursor}" for the next page.`);
+}
+function formatUserContent(heading, content) {
+	return `# ${heading}\n\n${content.posts.length === 0 ? "" : `## Posts (${content.posts.length})\n${content.posts.map((post, index) => `${index + 1}. ${post.title} — r/${post.subreddit}, score ${post.score.toLocaleString()} — https://reddit.com${post.permalink}`).join("\n")}\n\n`}${content.comments.length === 0 ? "" : `## Comments (${content.comments.length})\n${content.comments.map((comment, index) => {
+		const body = comment.body.length > 200 ? `${comment.body.substring(0, 200)}...` : comment.body;
+		return `${index + 1}. in r/${comment.subreddit}: ${body} — https://reddit.com${comment.permalink}`;
+	}).join("\n")}\n\n`}${content.posts.length === 0 && content.comments.length === 0 ? "No items found.\n\n" : ""}`.trimEnd() + nextPageHint(content.after);
+}
 async function setupRedditClient() {
 	const clientId = process.env.REDDIT_CLIENT_ID;
 	const clientSecret = process.env.REDDIT_CLIENT_SECRET;
@@ -847,6 +1096,7 @@ async function setupRedditClient() {
 		enabled: cacheEnabled,
 		maxBytes: (Number.isFinite(cacheMaxMb) && cacheMaxMb > 0 ? cacheMaxMb : 50) * 1024 * 1024
 	};
+	const maxRetriesRaw = Number(process.env.REDDIT_MAX_RETRIES ?? "3");
 	const client = initializeRedditClient({
 		clientId: clientId ?? "",
 		clientSecret: clientSecret ?? "",
@@ -856,7 +1106,12 @@ async function setupRedditClient() {
 		authMode,
 		safeMode: safeModeConfig,
 		botDisclosure: botDisclosureConfig,
-		cache: cacheConfig
+		cache: cacheConfig,
+		retry: {
+			maxRetries: Number.isFinite(maxRetriesRaw) && maxRetriesRaw >= 0 ? Math.floor(maxRetriesRaw) : 3,
+			baseDelayMs: 1e3,
+			maxDelayMs: 6e4
+		}
 	});
 	console.error("[Setup] Reddit client initialized");
 	console.error(`[Setup] Authentication mode: ${authMode}`);
@@ -938,7 +1193,12 @@ For details: https://support.reddithelp.com/hc/en-us/articles/42728983564564-Res
 });
 server.addTool({
 	name: "test_reddit_mcp_server",
-	description: "Test the Reddit MCP Server connection and configuration",
+	description: "Health check for the Reddit MCP server. Read-only and side-effect-free — inspects local configuration only and makes no Reddit API calls. Returns the server version, whether the Reddit client is initialized, whether OAuth credentials are present, and whether write access (REDDIT_USERNAME/REDDIT_PASSWORD) is configured. Use this first to diagnose setup/auth problems. Do NOT use it to check Reddit's own status or connectivity — it never contacts Reddit. A \"✗ Write Access\" result means the write tools (create_post, reply_to_post, edit_*, delete_*) will fail.",
+	annotations: {
+		title: "Test Reddit MCP Server",
+		readOnlyHint: true,
+		openWorldHint: false
+	},
 	parameters: z.object({}),
 	execute: () => {
 		const client = getRedditClient();
@@ -955,8 +1215,13 @@ Ready to handle Reddit API requests!`);
 });
 server.addTool({
 	name: "get_user_info",
-	description: "Get detailed information about a Reddit user including karma, account status, and activity analysis",
-	parameters: z.object({ username: z.string().describe("The Reddit username (without u/ prefix)") }),
+	description: "Get a public profile for any Reddit user: comment/post/total karma, account age and status flags, plus a short activity analysis and engagement tips. Read-only; works in anonymous mode. Returns profile stats only — use get_user_posts / get_user_comments for their actual content. Use get_me instead for your own authenticated account; do NOT expect private fields here, as only public data is returned.",
+	annotations: {
+		title: "Get User Info",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
+	parameters: z.object({ username: z.string().describe("The target user's Reddit username, without the u/ prefix (e.g. 'spez', not 'u/spez').") }),
 	execute: async (args) => {
 		return (await unwrapClient().getUser(args.username)).fold((err) => {
 			throw new Error(`Failed to get user info: ${err.message}`);
@@ -982,16 +1247,91 @@ server.addTool({
 		});
 	}
 });
+server.addTool({
+	name: "get_me",
+	description: "Get the authenticated user's own profile (karma, account age, status flags). Read-only, but requires user credentials (REDDIT_USERNAME/REDDIT_PASSWORD) and fails in anonymous mode. Use this instead of get_user_info when you need the current account rather than an arbitrary user. Do NOT use it to look up other users — it always returns the logged-in account.",
+	annotations: {
+		title: "Get My Account",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
+	parameters: z.object({}),
+	execute: async () => {
+		return (await unwrapClient().getMe()).fold((err) => {
+			throw new Error(`Failed to get authenticated user: ${err.message}`);
+		}, (user) => {
+			const formattedUser = formatUserInfo(user);
+			return `# Your Account: u/${formattedUser.username}
+
+## Profile Overview
+- Username: u/${formattedUser.username}
+- Karma:
+  - Comment Karma: ${formattedUser.karma.commentKarma.toLocaleString()}
+  - Post Karma: ${formattedUser.karma.postKarma.toLocaleString()}
+  - Total Karma: ${formattedUser.karma.totalKarma.toLocaleString()}
+- Account Status: ${formattedUser.accountStatus.join(", ")}
+- Account Created: ${formattedUser.accountCreated}
+- Profile URL: ${formattedUser.profileUrl}`;
+		});
+	}
+});
+server.addTool({
+	name: "get_my_overview",
+	description: "Get the authenticated user's own recent activity — posts and comments interleaved, newest first. Read-only but requires user credentials (REDDIT_USERNAME/REDDIT_PASSWORD). Returns up to `limit` items plus an `after` cursor for the next page. Use get_my_saved for saved items, or get_user_posts / get_user_comments for another user. Do NOT use this to fetch a specific post's thread — use get_post_comments.",
+	annotations: {
+		title: "Get My Overview",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
+	parameters: z.object({
+		limit: z.number().min(1).max(100).default(25).describe("How many activity items to return, 1–100 (default 25)."),
+		after: z.string().optional().describe("Forward pagination cursor: the `after` value returned by a previous call. Omit for the first page.")
+	}),
+	execute: async (args) => {
+		return (await unwrapClient().getMyOverview({
+			limit: args.limit,
+			after: args.after
+		})).fold((err) => {
+			throw new Error(`Failed to get your overview: ${err.message}`);
+		}, (content) => formatUserContent("Your Overview", content));
+	}
+});
+server.addTool({
+	name: "get_my_saved",
+	description: "Get the authenticated user's saved posts and comments (private to the account). Read-only but requires user credentials (REDDIT_USERNAME/REDDIT_PASSWORD). Returns up to `limit` items plus an `after` pagination cursor. Use get_my_overview for your authored activity. Do NOT use this for another user — saved items are private and have no cross-user equivalent.",
+	annotations: {
+		title: "Get My Saved",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
+	parameters: z.object({
+		limit: z.number().min(1).max(100).default(25).describe("How many saved items to return, 1–100 (default 25)."),
+		after: z.string().optional().describe("Forward pagination cursor: the `after` value returned by a previous call. Omit for the first page.")
+	}),
+	execute: async (args) => {
+		return (await unwrapClient().getMySaved({
+			limit: args.limit,
+			after: args.after
+		})).fold((err) => {
+			throw new Error(`Failed to get saved content: ${err.message}`);
+		}, (content) => formatUserContent("Your Saved Content", content));
+	}
+});
 server.addTool({
 	name: "get_user_posts",
-	description: "Get recent posts by a Reddit user with sorting and filtering options",
+	description: "Get posts submitted by a specific user, with sort (new/hot/top) and time filter. Read-only; works anonymously. Returns a page of posts (title, subreddit, score, upvote ratio, comment count, permalink) plus an `after` cursor for paging. Use get_user_comments for their comments, or get_user_info for karma/profile stats. Do NOT use this to search a subreddit — use search_reddit or browse_subreddit.",
+	annotations: {
+		title: "Get User Posts",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
 	parameters: z.object({
-		username: z.string().describe("The Reddit username (without u/ prefix)"),
+		username: z.string().describe("The author's Reddit username, without the u/ prefix (e.g. 'spez')."),
 		sort: z.enum([
 			"new",
 			"hot",
 			"top"
-		]).default("new").describe("Sort order for posts"),
+		]).default("new").describe("Ordering: 'new' (most recent), 'hot' (currently active), or 'top' (highest score within `time_filter`). Default 'new'."),
 		time_filter: z.enum([
 			"hour",
 			"day",
@@ -999,17 +1339,20 @@ server.addTool({
 			"month",
 			"year",
 			"all"
-		]).default("all").describe("Time filter for top posts"),
-		limit: z.number().min(1).max(100).default(10).describe("Number of posts to retrieve")
+		]).default("all").describe("Time window for scoring; only applies when sort='top'. Ignored for 'new'/'hot'. Default 'all'."),
+		limit: z.number().min(1).max(100).default(10).describe("How many posts to return, 1–100 (default 10)."),
+		after: z.string().optional().describe("Forward pagination cursor: the `after` value from a previous call. Omit for the first page.")
 	}),
 	execute: async (args) => {
 		return (await unwrapClient().getUserPosts(args.username, {
 			sort: args.sort,
 			timeFilter: args.time_filter,
-			limit: args.limit
+			limit: args.limit,
+			after: args.after
 		})).fold((err) => {
 			throw new Error(`Failed to get user posts: ${err.message}`);
-		}, (posts) => {
+		}, (page) => {
+			const posts = page.items;
 			if (posts.length === 0) return `No posts found for u/${args.username} with the specified filters.`;
 			const postSummaries = posts.map((post, index) => {
 				const flags = [...post.over18 ? ["**NSFW**"] : [], ...post.spoiler === true ? ["**Spoiler**"] : []];
@@ -1022,20 +1365,25 @@ server.addTool({
 			}).join("\n\n");
 			return `# Posts by u/${args.username} (${args.sort} - ${args.time_filter})
 
-${postSummaries}`;
+${postSummaries}${nextPageHint(page.after)}`;
 		});
 	}
 });
 server.addTool({
 	name: "get_user_comments",
-	description: "Get recent comments by a Reddit user with sorting and filtering options",
+	description: "Get comments made by a specific user, with sort (new/hot/top) and time filter. Read-only; works anonymously. Returns a page of comments (subreddit, parent post title, body excerpt, score, permalink) plus an `after` cursor. Use get_user_posts for their submissions, or get_user_info for karma/profile stats. Do NOT use this to read one post's thread — use get_post_comments.",
+	annotations: {
+		title: "Get User Comments",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
 	parameters: z.object({
-		username: z.string().describe("The Reddit username (without u/ prefix)"),
+		username: z.string().describe("The author's Reddit username, without the u/ prefix (e.g. 'spez')."),
 		sort: z.enum([
 			"new",
 			"hot",
 			"top"
-		]).default("new").describe("Sort order for comments"),
+		]).default("new").describe("Ordering: 'new' (most recent), 'hot' (currently active), or 'top' (highest score within `time_filter`). Default 'new'."),
 		time_filter: z.enum([
 			"hour",
 			"day",
@@ -1043,17 +1391,20 @@ server.addTool({
 			"month",
 			"year",
 			"all"
-		]).default("all").describe("Time filter for top comments"),
-		limit: z.number().min(1).max(100).default(10).describe("Number of comments to retrieve")
+		]).default("all").describe("Time window for scoring; only applies when sort='top'. Ignored for 'new'/'hot'. Default 'all'."),
+		limit: z.number().min(1).max(100).default(10).describe("How many comments to return, 1–100 (default 10)."),
+		after: z.string().optional().describe("Forward pagination cursor: the `after` value from a previous call. Omit for the first page.")
 	}),
 	execute: async (args) => {
 		return (await unwrapClient().getUserComments(args.username, {
 			sort: args.sort,
 			timeFilter: args.time_filter,
-			limit: args.limit
+			limit: args.limit,
+			after: args.after
 		})).fold((err) => {
 			throw new Error(`Failed to get user comments: ${err.message}`);
-		}, (comments) => {
+		}, (page) => {
+			const comments = page.items;
 			if (comments.length === 0) return `No comments found for u/${args.username} with the specified filters.`;
 			const commentSummaries = comments.map((comment, index) => {
 				const truncatedBody = comment.body.length > 300 ? `${comment.body.substring(0, 300)}...` : comment.body;
@@ -1069,16 +1420,21 @@ In r/${comment.subreddit} on "${comment.submissionTitle}"
 			}).join("\n\n");
 			return `# Comments by u/${args.username} (${args.sort} - ${args.time_filter})
 
-${commentSummaries}`;
+${commentSummaries}${nextPageHint(page.after)}`;
 		});
 	}
 });
 server.addTool({
 	name: "get_reddit_post",
-	description: "Get detailed information about a specific Reddit post including content, stats, and engagement analysis",
+	description: "Get a single post by subreddit + post id: title, author, self-text or link content, score, upvote ratio, comment count, flair/flags, and an engagement analysis. Read-only; works anonymously. Returns the post only — use get_post_comments for its comment thread. Do NOT use this to list a subreddit's posts (use browse_subreddit / get_top_posts) or to find posts by keyword (use search_reddit).",
+	annotations: {
+		title: "Get Reddit Post",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
 	parameters: z.object({
-		subreddit: z.string().describe("The subreddit name (without r/ prefix)"),
-		post_id: z.string().describe("The Reddit post ID")
+		subreddit: z.string().describe("The subreddit the post lives in, without the r/ prefix (e.g. 'programming')."),
+		post_id: z.string().describe("Base36 post id — the segment after /comments/ in a permalink like reddit.com/r/<sub>/comments/<post_id>/... (e.g. '1abc23'). With or without a t3_ prefix.")
 	}),
 	execute: async (args) => {
 		return (await unwrapClient().getPost(args.post_id, args.subreddit)).fold((err) => {
@@ -1119,9 +1475,14 @@ ${formattedPost.bestTimeToEngage}`;
 });
 server.addTool({
 	name: "get_top_posts",
-	description: "Get top posts from a subreddit or from the Reddit home feed",
+	description: "Get the top-scoring posts from a subreddit — or from the authenticated home feed if no subreddit is given — within a time window (hour…all). Read-only; works anonymously. Returns a page of posts (title, author, score, upvote ratio, comments, link) plus an `after` cursor. This is a shortcut for the 'top' sort; use browse_subreddit for hot/new/rising/controversial, or search_reddit to find posts by keyword.",
+	annotations: {
+		title: "Get Top Posts",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
 	parameters: z.object({
-		subreddit: z.string().optional().describe("The subreddit name (without r/ prefix). Leave empty for home feed"),
+		subreddit: z.string().optional().describe("Subreddit to read, without the r/ prefix (e.g. 'science'). Omit to use the authenticated home feed (requires credentials)."),
 		time_filter: z.enum([
 			"hour",
 			"day",
@@ -1129,13 +1490,15 @@ server.addTool({
 			"month",
 			"year",
 			"all"
-		]).default("week").describe("Time period for top posts"),
-		limit: z.number().min(1).max(100).default(10).describe("Number of posts to retrieve")
+		]).default("week").describe("Time window the 'top' ranking is computed over (e.g. 'day' = top today). Default 'week'."),
+		limit: z.number().min(1).max(100).default(10).describe("How many posts to return, 1–100 (default 10)."),
+		after: z.string().optional().describe("Forward pagination cursor: the `after` value from a previous call. Omit for the first page.")
 	}),
 	execute: async (args) => {
-		return (await unwrapClient().getTopPosts(args.subreddit ?? "", args.time_filter, args.limit)).fold((err) => {
+		return (await unwrapClient().getTopPosts(args.subreddit ?? "", args.time_filter, args.limit, args.after)).fold((err) => {
 			throw new Error(`Failed to get top posts: ${err.message}`);
-		}, (posts) => {
+		}, (page) => {
+			const posts = page.items;
 			if (posts.length === 0) return `No posts found in ${Option(args.subreddit).fold(() => "home feed", (sr) => `r/${sr}`)} for the specified time period.`;
 			const postSummaries = posts.map(formatPostInfo).map((post, index) => `### ${index + 1}. ${post.title}
 - Author: u/${post.author}
@@ -1145,22 +1508,27 @@ server.addTool({
 - Link: ${post.links.shortLink}`).join("\n\n");
 			return `# Top Posts from ${Option(args.subreddit).fold(() => "Home Feed", (sr) => `r/${sr}`)} (${args.time_filter})
 
-${postSummaries}`;
+${postSummaries}${nextPageHint(page.after)}`;
 		});
 	}
 });
 server.addTool({
 	name: "browse_subreddit",
-	description: "Browse posts from a subreddit or the Reddit home feed with a sort order (hot, new, top, rising, controversial). The time_filter only applies to top and controversial sorts.",
+	description: "Browse a subreddit — or the authenticated home feed when no subreddit is given — by sort order: hot, new, top, rising, or controversial. Read-only; works anonymously. `time_filter` applies only to the top and controversial sorts. Returns a page of posts (title, author, score, upvote ratio, comments, link) plus an `after` cursor. Use get_top_posts as a shortcut for the top sort, or search_reddit to find posts by keyword rather than by feed order.",
+	annotations: {
+		title: "Browse Subreddit",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
 	parameters: z.object({
-		subreddit: z.string().optional().describe("The subreddit name (without r/ prefix). Leave empty for home feed"),
+		subreddit: z.string().optional().describe("Subreddit to browse, without the r/ prefix (e.g. 'news'). Omit to use the authenticated home feed (requires credentials)."),
 		sort: z.enum([
 			"hot",
 			"new",
 			"top",
 			"rising",
 			"controversial"
-		]).default("hot").describe("Sort order for posts"),
+		]).default("hot").describe("Feed ordering: 'hot' (default), 'new', 'rising', 'top', or 'controversial'. 'top'/'controversial' honor `time_filter`."),
 		time_filter: z.enum([
 			"hour",
 			"day",
@@ -1168,13 +1536,15 @@ server.addTool({
 			"month",
 			"year",
 			"all"
-		]).default("week").describe("Time period (only applies to top and controversial sorts)"),
-		limit: z.number().min(1).max(100).default(10).describe("Number of posts to retrieve")
+		]).default("week").describe("Time window; only applies to sort='top' or 'controversial'. Ignored otherwise. Default 'week'."),
+		limit: z.number().min(1).max(100).default(10).describe("How many posts to return, 1–100 (default 10)."),
+		after: z.string().optional().describe("Forward pagination cursor: the `after` value from a previous call. Omit for the first page.")
 	}),
 	execute: async (args) => {
-		return (await unwrapClient().browseSubreddit(args.subreddit ?? "", args.sort, args.time_filter, args.limit)).fold((err) => {
+		return (await unwrapClient().browseSubreddit(args.subreddit ?? "", args.sort, args.time_filter, args.limit, args.after)).fold((err) => {
 			throw new Error(`Failed to browse subreddit: ${err.message}`);
-		}, (posts) => {
+		}, (page) => {
+			const posts = page.items;
 			const location = Option(args.subreddit).fold(() => "home feed", (sr) => `r/${sr}`);
 			if (posts.length === 0) return `No posts found in ${location}.`;
 			const postSummaries = posts.map(formatPostInfo).map((post, index) => `### ${index + 1}. ${post.title}
@@ -1187,14 +1557,19 @@ server.addTool({
 			const heading = location === "home feed" ? "Home Feed" : location;
 			return `# ${args.sort} posts from ${heading} (${args.sort}${timeSuffix})
 
-${postSummaries}`;
+${postSummaries}${nextPageHint(page.after)}`;
 		});
 	}
 });
 server.addTool({
 	name: "get_subreddit_info",
-	description: "Get detailed information about a subreddit including description, stats, and community analysis",
-	parameters: z.object({ subreddit_name: z.string().describe("The subreddit name (without r/ prefix)") }),
+	description: "Get a subreddit's profile: title, description, subscriber and active-user counts, creation date, flags, wiki/link URLs, plus a community analysis and posting tips. Read-only; works anonymously. Returns metadata about the community itself — use browse_subreddit / get_top_posts for its posts, or get_subreddit_rules for its posting rules. Do NOT use this to find subreddits by topic — use search_reddit with type='sr'.",
+	annotations: {
+		title: "Get Subreddit Info",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
+	parameters: z.object({ subreddit_name: z.string().describe("The subreddit name, without the r/ prefix (e.g. 'askscience').") }),
 	execute: async (args) => {
 		return (await unwrapClient().getSubredditInfo(args.subreddit_name)).fold((err) => {
 			throw new Error(`Failed to get subreddit info: ${err.message}`);
@@ -1230,9 +1605,65 @@ ${formattedSubreddit.description.full}
 		});
 	}
 });
+server.addTool({
+	name: "get_subreddit_rules",
+	description: "Get a subreddit's posting rules (each rule's name, what it applies to, and its description). Read-only; works anonymously. Returns the rules list, or a note when the subreddit lists none. Call this before create_post to check requirements and avoid auto-removal. For available post flairs use get_post_flairs instead.",
+	annotations: {
+		title: "Get Subreddit Rules",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
+	parameters: z.object({ subreddit_name: z.string().describe("The subreddit name, without the r/ prefix (e.g. 'AskReddit').") }),
+	execute: async (args) => {
+		return (await unwrapClient().getSubredditRules(args.subreddit_name)).fold((err) => {
+			throw new Error(`Failed to get subreddit rules: ${err.message}`);
+		}, (rules) => {
+			if (rules.length === 0) return `r/${args.subreddit_name} has no listed subreddit-specific rules.`;
+			const ruleList = rules.map((rule, index) => {
+				const applies = rule.kind === "all" ? "posts & comments" : `${rule.kind}s`;
+				const detail = rule.description.trim() === "" ? "" : `\n${rule.description.trim()}`;
+				return `### ${index + 1}. ${rule.shortName} _(applies to ${applies})_${detail}`;
+			}).join("\n\n");
+			return `# Posting Rules for r/${args.subreddit_name}
+
+${ruleList}`;
+		});
+	}
+});
+server.addTool({
+	name: "get_post_flairs",
+	description: "List a subreddit's selectable link flairs (flair text + flair_id) for use with create_post. Read-only, but requires user credentials; many subreddits expose flairs only to members, so this can 403 or return empty anonymously. Pass a returned flair_id (and flair_text for text-editable flairs) to create_post. For the subreddit's posting rules use get_subreddit_rules instead.",
+	annotations: {
+		title: "Get Post Flairs",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
+	parameters: z.object({ subreddit_name: z.string().describe("The subreddit name, without the r/ prefix (e.g. 'gadgets').") }),
+	execute: async (args) => {
+		return (await unwrapClient().getPostFlairs(args.subreddit_name)).fold((err) => {
+			throw new Error(`Failed to get post flairs: ${err.message}`);
+		}, (flairs) => {
+			if (flairs.length === 0) return `r/${args.subreddit_name} has no selectable link flairs (or none are visible to this account).`;
+			const flairList = flairs.map((flair) => {
+				const editable = flair.textEditable === true ? " _(text editable)_" : "";
+				return `- ${flair.text}${editable} — \`flair_id: ${flair.id}\``;
+			}).join("\n");
+			return `# Available Link Flairs for r/${args.subreddit_name}
+
+${flairList}
+
+Pass the desired \`flair_id\` to \`create_post\`.`;
+		});
+	}
+});
 server.addTool({
 	name: "get_trending_subreddits",
-	description: "Get a list of currently trending subreddits",
+	description: "Get the subreddits Reddit is currently featuring as trending/popular. Read-only, no parameters; works anonymously. Returns a list of subreddit names that changes through the day (cached briefly server-side). To find subreddits by keyword instead of by trend, use search_reddit with type='sr'.",
+	annotations: {
+		title: "Get Trending Subreddits",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
 	parameters: z.object({}),
 	execute: async () => {
 		return (await unwrapClient().getTrendingSubreddits()).fold((err) => {
@@ -1244,17 +1675,22 @@ ${trendingSubreddits.map((subreddit, index) => `${index + 1}. r/${subreddit}`).j
 });
 server.addTool({
 	name: "search_reddit",
-	description: "Search Reddit for posts and content across subreddits",
+	description: "Search Reddit for posts — or subreddits/users via `type` — optionally scoped to one subreddit, with sort and time filters. Read-only; works anonymously. Returns a page of results (title, subreddit, author, score, comments, link) plus an `after` cursor for paging. Use this to find content by keyword; use browse_subreddit / get_top_posts to list a known subreddit's feed instead.",
+	annotations: {
+		title: "Search Reddit",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
 	parameters: z.object({
-		query: z.string().describe("Search query"),
-		subreddit: z.string().optional().describe("Limit search to specific subreddit (without r/ prefix)"),
+		query: z.string().describe("Search terms; supports Reddit operators (quotes for exact phrases, author:name, self:yes). Must be non-empty."),
+		subreddit: z.string().optional().describe("Restrict results to this subreddit, without the r/ prefix (e.g. 'python'). Omit to search all of Reddit."),
 		sort: z.enum([
 			"relevance",
 			"hot",
 			"top",
 			"new",
 			"comments"
-		]).default("relevance").describe("Sort order"),
+		]).default("relevance").describe("Sort order. Prefer 'relevance' (default) for finding posts about a topic. Use 'top'/'hot' only for what's currently popular and 'new' for the latest — these rank by karma/recency and, especially combined with a narrow time_filter, can surface loosely-matching posts over the best topical results."),
 		time_filter: z.enum([
 			"hour",
 			"day",
@@ -1262,13 +1698,14 @@ server.addTool({
 			"month",
 			"year",
 			"all"
-		]).default("all").describe("Time filter"),
-		limit: z.number().min(1).max(100).default(10).describe("Number of results"),
+		]).default("all").describe("Restrict to results from this recent window (e.g. 'week'). Default 'all' (no time limit)."),
+		limit: z.number().min(1).max(100).default(10).describe("How many results to return, 1–100 (default 10)."),
 		type: z.enum([
 			"link",
 			"sr",
 			"user"
-		]).default("link").describe("Type of content to search")
+		]).default("link").describe("What to search for: 'link' = posts (default), 'sr' = subreddits, 'user' = users."),
+		after: z.string().optional().describe("Forward pagination cursor: the `after` value from a previous call. Omit for the first page.")
 	}),
 	execute: async (args) => {
 		const client = unwrapClient();
@@ -1278,10 +1715,12 @@ server.addTool({
 			sort: args.sort,
 			timeFilter: args.time_filter,
 			limit: args.limit,
-			type: args.type
+			type: args.type,
+			after: args.after
 		})).fold((err) => {
 			throw new Error(`Failed to search: ${err.message}`);
-		}, (posts) => {
+		}, (page) => {
+			const posts = page.items;
 			if (posts.length === 0) {
 				const searchLocation = Option(args.subreddit).fold(() => "", (sr) => ` in r/${sr}`);
 				return `No results found for "${args.query}"${searchLocation}.`;
@@ -1301,23 +1740,32 @@ server.addTool({
 
 Sorted by: ${args.sort} | Time: ${args.time_filter} | Type: ${args.type}
 
-${searchResults}`;
+${searchResults}${nextPageHint(page.after)}`;
 		});
 	}
 });
 server.addTool({
 	name: "create_post",
-	description: "Create a new post in a subreddit (requires REDDIT_USERNAME and REDDIT_PASSWORD). WARNING: Rapid posting or duplicate content may trigger Reddit's spam detection and result in account bans. Consider enabling REDDIT_SAFE_MODE=standard for protection.",
+	description: "Create a new text or link post in a subreddit. Mutating and NOT idempotent — each call publishes a separate post. Requires REDDIT_USERNAME and REDDIT_PASSWORD; fails without them. Returns the new post's id and URL. Check get_subreddit_rules and get_post_flairs first, since many subreddits require a flair or reject certain content. WARNING: rapid posting or duplicate content may trigger Reddit's spam detection and account bans — enable REDDIT_SAFE_MODE=standard for rate limiting and duplicate detection.",
+	annotations: {
+		title: "Create Post",
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: false,
+		openWorldHint: true
+	},
 	parameters: z.object({
-		subreddit: z.string().describe("The subreddit name (without r/ prefix)"),
-		title: z.string().describe("The post title"),
-		content: z.string().describe("The post content (text for self posts, URL for link posts)"),
-		is_self: z.boolean().default(true).describe("Whether this is a self post (text) or link post")
+		subreddit: z.string().describe("Target subreddit, without the r/ prefix (e.g. 'test')."),
+		title: z.string().describe("Post title (cannot be edited after creation)."),
+		content: z.string().describe("For a self post (is_self=true): the body text, Reddit markdown supported. For a link post (is_self=false): the destination URL."),
+		is_self: z.boolean().default(true).describe("true = text/self post using `content` as the body (default); false = link post using `content` as the URL."),
+		flair_id: z.string().optional().describe("Link flair template id from get_post_flairs; many subreddits require one or the post is auto-removed."),
+		flair_text: z.string().optional().describe("Custom flair text, allowed only for flairs whose template is text-editable.")
 	}),
 	execute: async (args) => {
 		const client = unwrapClient();
 		if (process.env.REDDIT_USERNAME === void 0 || process.env.REDDIT_PASSWORD === void 0) throw new Error("User authentication required. Please set REDDIT_USERNAME and REDDIT_PASSWORD environment variables.");
-		return (await client.createPost(args.subreddit, args.title, args.content, args.is_self)).fold((err) => {
+		return (await client.createPost(args.subreddit, args.title, args.content, args.is_self, args.flair_id, args.flair_text)).fold((err) => {
 			throw new Error(`Failed to create post: ${err.message}`);
 		}, (post) => {
 			const formattedPost = formatPostInfo(post);
@@ -1335,10 +1783,17 @@ Your post has been successfully submitted to r/${formattedPost.subreddit}.`;
 });
 server.addTool({
 	name: "reply_to_post",
-	description: "Post a reply to an existing Reddit post or comment (requires REDDIT_USERNAME and REDDIT_PASSWORD). WARNING: Rapid commenting or duplicate content may trigger Reddit's spam detection. Enable REDDIT_SAFE_MODE=standard for rate limiting and duplicate detection.",
+	description: "Post a reply to an existing post or comment. Mutating and NOT idempotent — each call adds a new comment. Requires REDDIT_USERNAME and REDDIT_PASSWORD. The parent is identified by its thing id — t3_ for a post, t1_ for a comment — so this creates both top-level and nested replies. Returns the new comment's id. Use edit_comment to change a reply you already posted. WARNING: rapid or duplicate replies may trigger Reddit's spam detection; enable REDDIT_SAFE_MODE=standard for rate limiting and duplicate detection.",
+	annotations: {
+		title: "Reply to Post or Comment",
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: false,
+		openWorldHint: true
+	},
 	parameters: z.object({
-		post_id: z.string().describe("The Reddit post ID (thing_id, e.g., t3_xxxxx for posts, t1_xxxxx for comments)"),
-		content: z.string().describe("The reply content")
+		post_id: z.string().describe("Parent thing id to reply under: t3_<id> for a post (creates a top-level comment) or t1_<id> for a comment (creates a nested reply)."),
+		content: z.string().describe("Reply body text; Reddit markdown supported.")
 	}),
 	execute: async (args) => {
 		const client = unwrapClient();
@@ -1357,8 +1812,15 @@ Your reply has been successfully posted.`);
 });
 server.addTool({
 	name: "delete_post",
-	description: "Delete your own Reddit post (requires REDDIT_USERNAME and REDDIT_PASSWORD). WARNING: This action is permanent and cannot be undone!",
-	parameters: z.object({ thing_id: z.string().describe("The full Reddit thing ID (e.g., 't3_abc123' for posts) or just the post ID (e.g., 'abc123'). The 't3_' prefix will be added automatically if missing.") }),
+	description: "Permanently delete one of your own posts. Mutating and destructive but idempotent — deleting an already-deleted post is a no-op. Requires REDDIT_USERNAME and REDDIT_PASSWORD, and only works on posts authored by the authenticated account. Only affects the post you name; use delete_comment for comments. WARNING: this cannot be undone — the content is removed, though the post id remains.",
+	annotations: {
+		title: "Delete Post",
+		readOnlyHint: false,
+		destructiveHint: true,
+		idempotentHint: true,
+		openWorldHint: true
+	},
+	parameters: z.object({ thing_id: z.string().describe("The post to delete: a full thing id 't3_<id>' or just the base36 post id '<id>' (the 't3_' prefix is added automatically). Must be a post you authored.") }),
 	execute: async (args) => {
 		const client = unwrapClient();
 		if (process.env.REDDIT_USERNAME === void 0 || process.env.REDDIT_PASSWORD === void 0) throw new Error("User authentication required. Please set REDDIT_USERNAME and REDDIT_PASSWORD environment variables.");
@@ -1373,8 +1835,15 @@ The post ${args.thing_id} has been permanently deleted from Reddit.
 });
 server.addTool({
 	name: "delete_comment",
-	description: "Delete your own Reddit comment (requires REDDIT_USERNAME and REDDIT_PASSWORD). WARNING: This action is permanent and cannot be undone!",
-	parameters: z.object({ thing_id: z.string().describe("The full Reddit thing ID (e.g., 't1_abc123' for comments) or just the comment ID (e.g., 'abc123'). The 't1_' prefix will be added automatically if missing.") }),
+	description: "Permanently delete one of your own comments. Mutating and destructive but idempotent — deleting an already-deleted comment is a no-op. Requires REDDIT_USERNAME and REDDIT_PASSWORD, and only works on comments authored by the authenticated account. Only affects the comment you name; use delete_post for posts. WARNING: this cannot be undone — the content is removed, though the comment id remains.",
+	annotations: {
+		title: "Delete Comment",
+		readOnlyHint: false,
+		destructiveHint: true,
+		idempotentHint: true,
+		openWorldHint: true
+	},
+	parameters: z.object({ thing_id: z.string().describe("The comment to delete: a full thing id 't1_<id>' or just the base36 comment id '<id>' (the 't1_' prefix is added automatically). Must be a comment you authored.") }),
 	execute: async (args) => {
 		const client = unwrapClient();
 		if (process.env.REDDIT_USERNAME === void 0 || process.env.REDDIT_PASSWORD === void 0) throw new Error("User authentication required. Please set REDDIT_USERNAME and REDDIT_PASSWORD environment variables.");
@@ -1389,10 +1858,17 @@ The comment ${args.thing_id} has been permanently deleted from Reddit.
 });
 server.addTool({
 	name: "edit_post",
-	description: "Edit your own Reddit post (self-text posts only, requires REDDIT_USERNAME and REDDIT_PASSWORD). You can only edit the text content of self posts, not titles or link posts. WARNING: Rapid edits may trigger spam detection. Enable REDDIT_SAFE_MODE for protection.",
+	description: "Replace the body text of one of your own self-text posts. Mutating and idempotent (same text → same result); it overwrites the previous body. Requires REDDIT_USERNAME and REDDIT_PASSWORD, and works only on self posts you authored — titles and link posts cannot be edited. Adds an \"edited\" marker. Use create_post to make a new post, or edit_comment for comments. WARNING: rapid edits may trigger spam detection; enable REDDIT_SAFE_MODE for protection.",
+	annotations: {
+		title: "Edit Post",
+		readOnlyHint: false,
+		destructiveHint: true,
+		idempotentHint: true,
+		openWorldHint: true
+	},
 	parameters: z.object({
-		thing_id: z.string().describe("The full Reddit thing ID (e.g., 't3_abc123' for posts) or just the post ID (e.g., 'abc123'). The 't3_' prefix will be added automatically if missing."),
-		new_text: z.string().describe("The new text content for the post. Supports Reddit markdown formatting.")
+		thing_id: z.string().describe("The post to edit: a full thing id 't3_<id>' or just the base36 post id '<id>' (the 't3_' prefix is added automatically). Must be a self-text post you authored."),
+		new_text: z.string().describe("Replacement body text; fully overwrites the current body. Reddit markdown supported.")
 	}),
 	execute: async (args) => {
 		const client = unwrapClient();
@@ -1412,10 +1888,17 @@ The post ${args.thing_id} has been updated with your new content.
 });
 server.addTool({
 	name: "edit_comment",
-	description: "Edit your own Reddit comment (requires REDDIT_USERNAME and REDDIT_PASSWORD). Update the text content of a comment you previously posted. WARNING: Rapid edits may trigger spam detection. Enable REDDIT_SAFE_MODE for protection.",
+	description: "Replace the text of one of your own comments. Mutating and idempotent (same text → same result); it overwrites the previous content. Requires REDDIT_USERNAME and REDDIT_PASSWORD, and works only on comments you authored. Adds an \"edited\" marker. Use reply_to_post to add a new comment, or edit_post for posts. WARNING: rapid edits may trigger spam detection; enable REDDIT_SAFE_MODE for protection.",
+	annotations: {
+		title: "Edit Comment",
+		readOnlyHint: false,
+		destructiveHint: true,
+		idempotentHint: true,
+		openWorldHint: true
+	},
 	parameters: z.object({
-		thing_id: z.string().describe("The full Reddit thing ID (e.g., 't1_abc123' for comments) or just the comment ID (e.g., 'abc123'). The 't1_' prefix will be added automatically if missing."),
-		new_text: z.string().describe("The new text content for the comment. Supports Reddit markdown formatting.")
+		thing_id: z.string().describe("The comment to edit: a full thing id 't1_<id>' or just the base36 comment id '<id>' (the 't1_' prefix is added automatically). Must be a comment you authored."),
+		new_text: z.string().describe("Replacement comment text; fully overwrites the current content. Reddit markdown supported.")
 	}),
 	execute: async (args) => {
 		const client = unwrapClient();
@@ -1431,10 +1914,15 @@ The comment ${args.thing_id} has been updated with your new content.
 });
 server.addTool({
 	name: "get_post_comments",
-	description: "Get comments from a specific Reddit post",
+	description: "Get the comment thread for a post (by post id + subreddit), sorted best/top/new/controversial/old/qa. Read-only; works anonymously. Returns the post header plus threaded comments (author, OP/edited badges, score, body, nesting depth) up to `limit`. Long threads are truncated with 'load more' stubs — expand those with get_more_comments. Use get_reddit_post for just the post body, not the thread.",
+	annotations: {
+		title: "Get Post Comments",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
 	parameters: z.object({
-		post_id: z.string().describe("The Reddit post ID"),
-		subreddit: z.string().describe("The subreddit name (without r/ prefix)"),
+		post_id: z.string().describe("Base36 post id — the segment after /comments/ in a permalink (e.g. '1abc23'). With or without a t3_ prefix."),
+		subreddit: z.string().describe("The subreddit the post lives in, without the r/ prefix (e.g. 'movies')."),
 		sort: z.enum([
 			"best",
 			"top",
@@ -1442,8 +1930,8 @@ server.addTool({
 			"controversial",
 			"old",
 			"qa"
-		]).default("best").describe("Comment sort order"),
-		limit: z.number().min(1).max(500).default(100).describe("Maximum number of comments to retrieve")
+		]).default("best").describe("Comment ordering: 'best' (default), 'top', 'new', 'controversial', 'old', or 'qa' (Q&A)."),
+		limit: z.number().min(1).max(500).default(100).describe("Maximum comments to return, 1–500 (default 100). Deeply nested replies may still be truncated as 'load more' stubs.")
 	}),
 	execute: async (args) => {
 		const client = unwrapClient();
@@ -1477,6 +1965,38 @@ ${comment.body}
 		});
 	}
 });
+server.addTool({
+	name: "get_more_comments",
+	description: "Expand truncated 'load more comments' stubs in a thread. Read-only; works anonymously. Pass the post's link id and the comment ids from a 'more' node (surfaced by get_post_comments) to fetch those hidden comments; returns the expanded comments (author, body excerpt, score, link). Call get_post_comments first to obtain the thread and its 'more' node ids — do NOT invent ids.",
+	annotations: {
+		title: "Get More Comments",
+		readOnlyHint: true,
+		openWorldHint: true
+	},
+	parameters: z.object({
+		link_id: z.string().describe("The parent post's link id (base36, with or without the t3_ prefix) that the stub belongs to."),
+		comment_ids: z.array(z.string()).min(1).describe("Base36 comment ids to expand, taken from a 'more' node returned by get_post_comments (not arbitrary ids).")
+	}),
+	execute: async (args) => {
+		return (await unwrapClient().getMoreComments(args.link_id, args.comment_ids)).fold((err) => {
+			throw new Error(`Failed to expand comments: ${err.message}`);
+		}, (comments) => {
+			if (comments.length === 0) return "No additional comments were returned for those ids.";
+			const commentList = comments.map((comment, index) => {
+				const truncated = comment.body.length > 300 ? `${comment.body.substring(0, 300)}...` : comment.body;
+				const flags = [...comment.edited ? ["*(edited)*"] : [], ...comment.isSubmitter ? ["**OP**"] : []];
+				return `### ${index + 1}. u/${comment.author} ${flags.join(" ")}
+> ${truncated}
+
+- Score: ${comment.score.toLocaleString()}
+- Link: https://reddit.com${comment.permalink}`;
+			}).join("\n\n");
+			return `# Expanded Comments (${comments.length})
+
+${commentList}`;
+		});
+	}
+});
 async function main() {
 	await setupRedditClient();
 	const useHttp = process.env.TRANSPORT_TYPE === "httpStream" || process.env.TRANSPORT_TYPE === "http";