reddit-mcp-server 1.5.0 → 1.5.1

package/dist/bin.js

@@ -3,12 +3,12 @@
 process.env.TRANSPORT_TYPE ??= "stdio";
 const args = process.argv.slice(2);
 if (args.includes("--version") || args.includes("-v")) {
-	console.log("1.5.0");
+	console.log("1.5.1");
 	process.exit(0);
 }
 if (args.includes("--help") || args.includes("-h")) {
 	console.log(`
-Reddit MCP Server v1.5.0
+Reddit MCP Server v1.5.1
 
 Usage: reddit-mcp-server [options]
 

package/dist/index.js

@@ -992,7 +992,7 @@ function formatSubredditInfo(subreddit) {
 //#endregion
 //#region src/index.ts
 dotenv.config({ quiet: true });
-const VERSION = "1.5.0";
+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");
@@ -1193,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();
@@ -1210,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}`);
@@ -1239,7 +1249,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 +1277,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 +1298,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 +1319,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 +1339,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 +1371,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 +1391,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 +1426,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 +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",
@@ -1445,9 +1490,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 +1514,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 +1536,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 +1563,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 +1607,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 +1632,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 +1658,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 +1675,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 +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"),
-		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 +1746,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 +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();
@@ -1723,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.");
@@ -1739,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.");
@@ -1755,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();
@@ -1778,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();
@@ -1797,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",
@@ -1808,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();
@@ -1845,10 +1967,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) => {