reddit-mcp-server 1.5.0 → 1.5.2

package/dist/index.js

@@ -59,6 +59,21 @@ var NotFoundError = class extends RedditErrorBase {
 		this.name = "NotFoundError";
 	}
 };
+/**
+* Reddit refused the request at the network level rather than for this specific resource.
+*
+* Reddit 403s the unauthenticated JSON API from many IP ranges (datacenters, VPNs, flagged
+* addresses), answering with an HTML block page instead of JSON. A bare `HttpError(403)` reads
+* as "this subreddit is private", which sends people looking in the wrong place — the fix is to
+* supply OAuth credentials, which also raises the rate limit from ~10 to 60+ req/min.
+*/
+var NetworkBlockedError = class extends RedditErrorBase {
+	_tag = "NetworkBlockedError";
+	constructor(message) {
+		super(message);
+		this.name = "NetworkBlockedError";
+	}
+};
 /** Client-side input or safety-policy rejection (invalid sort, duplicate-content guard). */
 var ValidationError = class extends RedditErrorBase {
 	_tag = "ValidationError";
@@ -90,6 +105,71 @@ function classifyRedditError(error, context) {
 	return new UnknownError(Option(context).fold(() => error.message, (ctx) => `${ctx}: ${error.message}`), error);
 }
 //#endregion
+//#region src/utils/reddit-identifiers.ts
+/**
+* Validation and normalization for Reddit identifiers that get interpolated into API paths.
+*
+* Every identifier reaching the client is model- or user-supplied. Interpolating one raw is a
+* path-injection hole: URL parsing resolves dot segments, so a `subreddit` of `../../api/v1/me`
+* escapes `/r/{sub}/about.json` and steers the OAuth bearer token to a different endpoint, and an
+* embedded `?` or `&` injects query parameters into the request we build.
+*
+* So each identifier is normalized (stripping the `r/`, `/u/`, `t3_` prefixes people naturally
+* type) and then checked against Reddit's own charset. Every value returned from this module
+* matches `[A-Za-z0-9_+-]+`, which is already URL-path-safe — no percent-encoding is applied,
+* because encoding the `+` in a multireddit (`r/science+space`) would break it.
+*/
+const SUBREDDIT_PATTERN = /^(u_)?[A-Za-z0-9][A-Za-z0-9_]{1,20}$/;
+const USERNAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{1,19}$/;
+const THING_ID_PATTERN = /^[a-z0-9]{1,13}$/;
+const stripLeading = (value, prefixes) => {
+	const lower = value.toLowerCase();
+	const matched = prefixes.find((prefix) => lower.startsWith(prefix));
+	return matched === void 0 ? value : value.slice(matched.length);
+};
+const bare = (value, prefixes) => stripLeading(stripLeading(value.trim(), ["/"]), prefixes).replace(/\/+$/, "");
+/**
+* Normalize a subreddit name for use in a path segment.
+*
+* Accepts `science`, `r/science`, `/r/science`, and `+`-joined multireddits (`science+space`).
+* The empty string passes through unchanged — callers use it to mean "the home feed".
+*/
+function normalizeSubreddit(input) {
+	const trimmed = input.trim();
+	if (trimmed === "") return "";
+	const segments = bare(trimmed, ["r/"]).split("+").map((segment) => segment.trim());
+	if (segments.find((segment) => !SUBREDDIT_PATTERN.test(segment)) !== void 0) throw new ValidationError(`Invalid subreddit name "${input}". Expected 2-21 characters of letters, digits, or underscores (e.g. "science").`);
+	return segments.join("+");
+}
+/** Normalize a username for use in a path segment. Accepts `spez`, `u/spez`, `/user/spez`. */
+function normalizeUsername(input) {
+	const name = bare(input, ["user/", "u/"]);
+	if (!USERNAME_PATTERN.test(name)) throw new ValidationError(`Invalid Reddit username "${input}". Expected 2-20 characters of letters, digits, underscores, or hyphens (e.g. "spez").`);
+	return name;
+}
+/**
+* Normalize a post or comment ID to its bare base36 form, dropping any `t1_`/`t3_` fullname
+* prefix. Use this wherever the ID lands in a path segment or query value.
+*/
+function normalizeThingId(input) {
+	const id = bare(input, [
+		"t1_",
+		"t3_",
+		"t4_",
+		"t5_"
+	]).toLowerCase();
+	if (!THING_ID_PATTERN.test(id)) throw new ValidationError(`Invalid Reddit ID "${input}". Expected a base36 id such as "1abc2de", optionally prefixed with t1_ or t3_.`);
+	return id;
+}
+/**
+* Normalize an ID to a Reddit fullname (`t3_1abc2de`), preserving an explicit `t1_`/`t3_` prefix
+* and falling back to `defaultKind` when the caller passed a bare ID.
+*/
+function normalizeFullname(input, defaultKind) {
+	const trimmed = input.trim().toLowerCase();
+	return `${trimmed.startsWith("t1_") ? "t1" : trimmed.startsWith("t3_") ? "t3" : defaultKind}_${normalizeThingId(input)}`;
+}
+//#endregion
 //#region src/client/response-cache.ts
 const SECOND = 1e3;
 var ResponseCache = class {
@@ -160,6 +240,10 @@ function listingCursor(data) {
 		...before
 	};
 }
+function headerValue(response, name) {
+	const headers = response.headers;
+	return (headers === null || headers === void 0 ? void 0 : headers.get(name)) ?? "";
+}
 function parsePostData(post) {
 	return {
 		id: post.id,
@@ -254,6 +338,7 @@ var RedditClient = class {
 				...headers,
 				Authorization: await this.reauthorize()
 			}, path, 0) : first;
+			if (!requiresAuth && response.status === 403 && !headerValue(response, "content-type").includes("json")) throw new NetworkBlockedError("Reddit is blocking unauthenticated requests from this network (HTTP 403 with a block page). Set REDDIT_CLIENT_ID and REDDIT_CLIENT_SECRET to authenticate with OAuth, which also raises the rate limit from ~10 to 60+ requests/min. See https://www.reddit.com/prefs/apps to create an app.");
 			if (cacheable && response.ok) {
 				const text = await response.text();
 				this.cache.set(url, text, response.status);
@@ -381,7 +466,7 @@ var RedditClient = class {
 	async getUser(username) {
 		const context = `Failed to get user info for ${username}`;
 		return (await Try.async(async () => {
-			const response = (await this.makeRequest(`/user/${username}/about.json`)).orThrow();
+			const response = (await this.makeRequest(`/user/${normalizeUsername(username)}/about.json`)).orThrow();
 			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
 			const { data } = await response.json();
 			return {
@@ -431,14 +516,14 @@ var RedditClient = class {
 		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");
+		return this.getUserContent(`/user/${encodeURIComponent(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");
+		return this.getUserContent(`/user/${encodeURIComponent(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"));
@@ -464,7 +549,7 @@ var RedditClient = class {
 	async getSubredditInfo(subredditName) {
 		const context = `Failed to get subreddit info for ${subredditName}`;
 		return (await Try.async(async () => {
-			const response = (await this.makeRequest(`/r/${subredditName}/about.json`)).orThrow();
+			const response = (await this.makeRequest(`/r/${normalizeSubreddit(subredditName)}/about.json`)).orThrow();
 			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
 			const { data } = await response.json();
 			return {
@@ -484,7 +569,7 @@ var RedditClient = class {
 	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();
+			const response = (await this.makeRequest(`/r/${normalizeSubreddit(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,
@@ -499,7 +584,7 @@ var RedditClient = class {
 	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();
+			const response = (await this.makeRequest(`/r/${normalizeSubreddit(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,
@@ -510,7 +595,6 @@ var RedditClient = class {
 		})).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()
@@ -518,6 +602,8 @@ var RedditClient = class {
 		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 name = normalizeSubreddit(subreddit);
+			const endpoint = name !== "" ? `/r/${name}/top.json` : "/top.json";
 			const response = (await this.makeRequest(`${endpoint}?${params}`)).orThrow();
 			if (!response.ok) throw new HttpError(response.status, `Failed to get top posts: HTTP ${response.status}`);
 			const json = await response.json();
@@ -536,13 +622,14 @@ var RedditClient = class {
 			"controversial"
 		];
 		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);
 		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 name = normalizeSubreddit(subreddit);
+			const endpoint = name !== "" ? `/r/${name}/${sort}.json` : `/${sort}.json`;
 			const response = (await this.makeRequest(`${endpoint}?${params}`)).orThrow();
 			if (!response.ok) throw new HttpError(response.status, `Failed to browse r/${home}: HTTP ${response.status}`);
 			const json = await response.json();
@@ -553,9 +640,10 @@ var RedditClient = class {
 		})).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`);
 		const context = `Failed to get post with ID ${postId}`;
 		return (await Try.async(async () => {
+			const id = normalizeThingId(postId);
+			const endpoint = Option(subreddit).fold(() => `/api/info.json?id=t3_${id}`, (sr) => `/r/${normalizeSubreddit(sr)}/comments/${id}.json`);
 			const response = (await this.makeRequest(endpoint)).orThrow();
 			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);
@@ -579,10 +667,12 @@ var RedditClient = class {
 			this.validateWriteAccess();
 			await this.enforceWriteRateLimit();
 			this.checkDuplicateContent(title + content, subreddit);
+			const targetSubreddit = normalizeSubreddit(subreddit);
+			if (targetSubreddit === "") throw new ValidationError("A subreddit is required to create a post.");
 			const finalContent = isSelf ? this.appendBotDisclosure(content) : content;
 			const kind = isSelf ? "self" : "link";
 			const params = new URLSearchParams();
-			params.append("sr", subreddit);
+			params.append("sr", targetSubreddit);
 			params.append("kind", kind);
 			params.append("title", title);
 			params.append(isSelf ? "text" : "url", finalContent);
@@ -599,12 +689,12 @@ var RedditClient = class {
 			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) throw new ApiError("No post ID returned from Reddit");
-			return (await this.getPost(postId, subreddit)).orThrow();
+			return (await this.getPost(postId, targetSubreddit)).orThrow();
 		})).toEither((error) => classifyRedditError(error));
 	}
 	async checkPostExists(postId) {
 		return (await Try.async(async () => {
-			const response = (await this.makeRequest(`/api/info.json?id=t3_${postId}`)).orThrow();
+			const response = (await this.makeRequest(`/api/info.json?id=t3_${normalizeThingId(postId)}`)).orThrow();
 			if (!response.ok) return false;
 			return (await response.json()).data.children.length > 0;
 		})).orElse(false);
@@ -616,9 +706,9 @@ var RedditClient = class {
 			await this.enforceWriteRateLimit();
 			this.checkDuplicateContent(content);
 			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_/, ""))) throw new NotFoundError(`Post with ID ${postId} does not exist or is not accessible`);
+			const fullThingId = normalizeFullname(postId, "t3");
+			if (!fullThingId.startsWith("t1_")) {
+				if (!await this.checkPostExists(normalizeThingId(postId))) throw new NotFoundError(`Post with ID ${postId} does not exist or is not accessible`);
 			}
 			const params = new URLSearchParams();
 			params.append("thing_id", fullThingId);
@@ -651,10 +741,10 @@ var RedditClient = class {
 			else throw new ApiError("Failed to parse reply response");
 		})).toEither((error) => classifyRedditError(error));
 	}
-	async deletePost(thingId) {
+	async deleteThing(thingId, defaultKind) {
 		return (await Try.async(async () => {
 			this.validateWriteAccess();
-			const fullThingId = thingId.startsWith("t3_") || thingId.startsWith("t1_") ? thingId : `t3_${thingId}`;
+			const fullThingId = normalizeFullname(thingId, defaultKind);
 			const params = new URLSearchParams();
 			params.append("id", fullThingId);
 			const response = (await this.makeRequest("/api/del", {
@@ -675,17 +765,19 @@ var RedditClient = class {
 			return classifyRedditError(error);
 		});
 	}
+	async deletePost(thingId) {
+		return this.deleteThing(thingId, "t3");
+	}
 	async deleteComment(thingId) {
-		const fullThingId = thingId.startsWith("t1_") ? thingId : `t1_${thingId}`;
-		return this.deletePost(fullThingId);
+		return this.deleteThing(thingId, "t1");
 	}
-	async editPost(thingId, newText) {
+	async editThing(thingId, newText, defaultKind) {
 		return (await Try.async(async () => {
 			this.validateWriteAccess();
 			await this.enforceWriteRateLimit();
 			this.checkDuplicateContent(newText);
 			const finalText = this.appendBotDisclosure(newText);
-			const fullThingId = thingId.startsWith("t3_") || thingId.startsWith("t1_") ? thingId : `t3_${thingId}`;
+			const fullThingId = normalizeFullname(thingId, defaultKind);
 			const params = new URLSearchParams();
 			params.append("thing_id", fullThingId);
 			params.append("text", finalText);
@@ -701,13 +793,14 @@ var RedditClient = class {
 			return true;
 		})).toEither((error) => classifyRedditError(error));
 	}
+	async editPost(thingId, newText) {
+		return this.editThing(thingId, newText, "t3");
+	}
 	async editComment(thingId, newText) {
-		const fullThingId = thingId.startsWith("t1_") ? thingId : `t1_${thingId}`;
-		return this.editPost(fullThingId, newText);
+		return this.editThing(thingId, newText, "t1");
 	}
 	async searchReddit(query, 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,
 			sort,
@@ -720,6 +813,7 @@ var RedditClient = class {
 		});
 		const context = `Failed to search Reddit for: ${query}`;
 		return (await Try.async(async () => {
+			const endpoint = Option(subreddit).fold(() => "/search.json", (sr) => `/r/${normalizeSubreddit(sr)}/search.json`);
 			const response = (await this.makeRequest(`${endpoint}?${params}`)).orThrow();
 			if (!response.ok) throw new HttpError(response.status, `Failed to search Reddit: HTTP ${response.status}`);
 			const json = await response.json();
@@ -737,7 +831,7 @@ var RedditClient = class {
 		});
 		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();
+			const response = (await this.makeRequest(`/r/${normalizeSubreddit(subreddit)}/comments/${normalizeThingId(postId)}.json?${params}`)).orThrow();
 			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;
@@ -769,15 +863,14 @@ var RedditClient = class {
 		})).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(",")
-		});
+		const context = `Failed to expand comments for ${linkId}`;
 		return (await Try.async(async () => {
 			var _json$json$data4;
+			const params = new URLSearchParams({
+				api_type: "json",
+				link_id: normalizeFullname(linkId, "t3"),
+				children: commentIds.map((id) => normalizeThingId(id)).join(",")
+			});
 			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) => {
@@ -809,7 +902,7 @@ var RedditClient = class {
 		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();
+			const response = (await this.makeRequest(`/user/${normalizeUsername(username)}/submitted.json?${params}`)).orThrow();
 			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
 			const json = await response.json();
 			return {
@@ -828,7 +921,7 @@ var RedditClient = class {
 		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();
+			const response = (await this.makeRequest(`/user/${normalizeUsername(username)}/comments.json?${params}`)).orThrow();
 			if (!response.ok) throw new HttpError(response.status, `${context}: HTTP ${response.status}`);
 			const json = await response.json();
 			return {
@@ -872,7 +965,7 @@ function formatTimestamp(timestamp) {
 function analyzeUserActivity(karmaRatio, isMod, accountAgeDays) {
 	return [
 		...karmaRatio > 5 ? ["Primarily a commenter, highly engaged in discussions"] : karmaRatio < .2 ? ["Content creator, focuses on sharing posts"] : ["Balanced participation in both posting and commenting"],
-		...accountAgeDays < 30 ? ["New user, still exploring Reddit"] : accountAgeDays > 365 * 5 ? ["Long-time Redditor with extensive platform experience"] : [],
+		...accountAgeDays < 30 ? ["New user, still exploring Reddit"] : accountAgeDays > 1825 ? ["Long-time Redditor with extensive platform experience"] : [],
 		...isMod ? ["Community leader who helps maintain subreddit quality"] : []
 	].join("\n  - ");
 }
@@ -882,7 +975,7 @@ function analyzePostEngagement(score, ratio, numComments) {
 function analyzeSubredditHealth(subscribers, activeUsers, ageDays) {
 	const sizeInsights = subscribers > 1e6 ? ["Major subreddit with massive following"] : subscribers > 1e5 ? ["Well-established community"] : subscribers < 1e3 ? ["Niche community, potential for growth"] : [];
 	const activityInsights = activeUsers.map((active) => active / subscribers).fold(() => [], (activityRatio) => activityRatio > .1 ? ["Highly active community with strong engagement"] : activityRatio < .01 ? ["Could benefit from more community engagement initiatives"] : []);
-	const ageInsights = ageDays > 365 * 5 ? ["Mature subreddit with established culture"] : ageDays < 90 ? ["New subreddit still forming its community"] : [];
+	const ageInsights = ageDays > 1825 ? ["Mature subreddit with established culture"] : ageDays < 90 ? ["New subreddit still forming its community"] : [];
 	return [
 		...sizeInsights,
 		...activityInsights,
@@ -910,7 +1003,7 @@ function getSubredditEngagementTips(subreddit) {
 	return allTips.length > 0 ? allTips.join("\n  - ") : "Regular engagement recommended to maintain community presence";
 }
 function formatUserInfo(user) {
-	const accountAgeDays = (Date.now() / 1e3 - user.createdUtc) / (24 * 3600);
+	const accountAgeDays = (Date.now() / 1e3 - user.createdUtc) / 86400;
 	const karmaRatio = user.commentKarma / (user.linkKarma === 0 ? 1 : user.linkKarma);
 	const status = [
 		...user.isMod ? ["Moderator"] : [],
@@ -965,7 +1058,7 @@ function formatPostInfo(post) {
 }
 function formatSubredditInfo(subreddit) {
 	const flags = [...subreddit.over18 ? ["NSFW"] : [], ...Option(subreddit.subredditType).fold(() => [], (type) => [`Type: ${type}`])];
-	const ageDays = (Date.now() / 1e3 - subreddit.createdUtc) / (24 * 3600);
+	const ageDays = (Date.now() / 1e3 - subreddit.createdUtc) / 86400;
 	return {
 		name: subreddit.displayName,
 		title: subreddit.title,
@@ -992,7 +1085,7 @@ function formatSubredditInfo(subreddit) {
 //#endregion
 //#region src/index.ts
 dotenv.config({ quiet: true });
-const VERSION = "1.5.0";
+const VERSION = "1.5.2";
 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");
@@ -1193,7 +1286,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();
@@ -1210,8 +1308,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}`);
@@ -1239,7 +1342,12 @@ server.addTool({
 });
 server.addTool({
 	name: "get_me",
-	description: "Get the authenticated user's own account info (karma, account status). Requires user credentials (REDDIT_USERNAME/REDDIT_PASSWORD); fails in anonymous mode.",
+	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) => {
@@ -1262,10 +1370,15 @@ server.addTool({
 });
 server.addTool({
 	name: "get_my_overview",
-	description: "Get your own recent activity (posts and comments combined). Requires user credentials (REDDIT_USERNAME/REDDIT_PASSWORD).",
+	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("Number of items to retrieve"),
-		after: z.string().optional().describe("Pagination cursor: pass the `after` value from a previous page")
+		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({
@@ -1278,10 +1391,15 @@ server.addTool({
 });
 server.addTool({
 	name: "get_my_saved",
-	description: "Get your saved posts and comments. Requires user credentials (REDDIT_USERNAME/REDDIT_PASSWORD); saved content is private.",
+	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("Number of items to retrieve"),
-		after: z.string().optional().describe("Pagination cursor: pass the `after` value from a previous page")
+		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({
@@ -1294,14 +1412,19 @@ server.addTool({
 });
 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",
@@ -1309,9 +1432,9 @@ 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"),
-		after: z.string().optional().describe("Pagination cursor: pass the `after` value from a previous page to fetch the next page")
+		]).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, {
@@ -1341,14 +1464,19 @@ ${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",
@@ -1356,9 +1484,9 @@ 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"),
-		after: z.string().optional().describe("Pagination cursor: pass the `after` value from a previous page to fetch the next page")
+		]).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, {
@@ -1391,10 +1519,15 @@ ${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) => {
@@ -1435,9 +1568,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",
@@ -1445,9 +1583,9 @@ 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"),
-		after: z.string().optional().describe("Pagination cursor: pass the `after` value from a previous page to fetch the next page")
+		]).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, args.after)).fold((err) => {
@@ -1469,16 +1607,21 @@ ${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",
@@ -1486,9 +1629,9 @@ 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"),
-		after: z.string().optional().describe("Pagination cursor: pass the `after` value from a previous page to fetch the next page")
+		]).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, args.after)).fold((err) => {
@@ -1513,8 +1656,13 @@ ${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}`);
@@ -1552,8 +1700,13 @@ ${formattedSubreddit.description.full}
 });
 server.addTool({
 	name: "get_subreddit_rules",
-	description: "Get a subreddit's posting rules. Useful to check requirements before creating a post to avoid auto-removal.",
-	parameters: z.object({ subreddit_name: z.string().describe("The subreddit name (without r/ prefix)") }),
+	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}`);
@@ -1572,8 +1725,13 @@ ${ruleList}`;
 });
 server.addTool({
 	name: "get_post_flairs",
-	description: "List the available link flairs for a subreddit (use a flair_id with create_post). Requires user credentials; many subreddits only expose flairs to members, so this may fail in anonymous mode.",
-	parameters: z.object({ subreddit_name: z.string().describe("The subreddit name (without r/ prefix)") }),
+	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}`);
@@ -1593,7 +1751,12 @@ 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) => {
@@ -1605,10 +1768,15 @@ ${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",
@@ -1623,14 +1791,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"),
-		after: z.string().optional().describe("Pagination cursor: pass the `after` value from a previous page to fetch the next page")
+		]).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();
@@ -1671,14 +1839,21 @@ ${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"),
-		flair_id: z.string().optional().describe("Link flair template id (from get_post_flairs); many subreddits require a flair"),
-		flair_text: z.string().optional().describe("Custom flair text, only for flairs whose template is text-editable")
+		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();
@@ -1701,10 +1876,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();
@@ -1723,8 +1905,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.");
@@ -1739,8 +1928,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.");
@@ -1755,10 +1951,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();
@@ -1778,10 +1981,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();
@@ -1797,10 +2007,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",
@@ -1808,8 +2023,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();
@@ -1845,10 +2060,15 @@ ${comment.body}
 });
 server.addTool({
 	name: "get_more_comments",
-	description: "Expand truncated 'load more comments' stubs in a thread. Pass the post's link id and the comment ids from a 'more' node (returned by get_post_comments) to fetch those 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 post (link) id, with or without the t3_ prefix"),
-		comment_ids: z.array(z.string()).min(1).describe("Comment ids to expand (from a 'more' node)")
+		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) => {