Search, organize, and chat with your saved Reddit posts. Semantic search, labels, notes, reading recommendations, and library insights for your AI assistant.
Scored across 24 tools
Several tools have heavily overlapping purposes: search_posts and semantic_search both use the same semantic pipeline for querying saved posts, get_post and get_post_content both return full post text, and get_stats is largely a subset of analyze_collection. An agent could easily misselect among these pairs.
Most tools follow a clear verb_noun snake_case pattern (add_note, delete_posts, get_unread, list_labels, mark_read, remove_label). The only real deviation is semantic_search, which reads as an adjective_noun rather than a verb-first action, but the overall naming is still predictable and readable.
24 tools is at the heavy end of acceptable for a saved-post manager; the surface is broad but feels somewhat bloated by redundant search and retrieval tools. The count is not absurd, but a few of the overlapping tools could be consolidated.
The tool surface covers search, retrieval, deletion, labels, notes, read state, statistics, and recommendations well. However, reminders are read-only—there is no way to create or delete a reading reminder—which creates a notable dead end for a common 'remind me to read this' workflow.
Add or update a personal note on a saved post.
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | The note text to attach | |
| post_id | Yes | The post ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, matching the write operation described. The description adds the context that the note is personal and the post must be saved, but does not elaborate on whether the note is replaced or created if one already exists, which is a behavioral gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant words. It is front-loaded with the core action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers the essential function but omits details like upsert behavior (whether an existing note is overwritten) and the effect of providing a note for an unsaved post. The idempotentHint implies an upsert, but this is not explicitly communicated, leaving some ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters described (note text and post ID). The tool description repeats the purpose but adds no new meaning beyond the schema. The baseline of 3 applies because the schema already documents the parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add or update) on a specific resource (personal note on a saved post). It is unambiguous and distinguishes from siblings like get_notes (which reads) and delete_posts (which deletes), even without naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (to attach a note to a saved post) but does not explicitly compare with alternatives or mention exclusions. It sets a precondition (saved post) but offers no guidance on when not to use it or when a sibling like get_notes would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deep analysis of the user's saved library — content breakdown, reading habits, subreddit distribution, engagement stats, label usage, saving patterns, and personalized insights.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds scope and the kinds of insights returned, but does not disclose behavior such as latency, rate limits, or whether the analysis is based on all saved items over all time. Given the annotation burden is low, a 3 is fair.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence leads with the core purpose and then delivers a compact list of analysis dimensions. Every clause adds information, there is no fluff, and nothing repeats what the schema or annotations already provide.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with no output schema, the description enumerates the major result areas and even says it produces personalized insights, which is enough for basic invocation. However, it does not describe the output shape, whether results can be empty, or how the analysis is structured, leaving minor ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, and schema description coverage is 100%, so the description does not need to compensate for any undocumented inputs. Baseline score for zero parameters is 4, and the description correctly stays silent since there is nothing to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs deep analysis of the user's saved library and enumerates concrete aspects like content breakdown, subreddit distribution, and personalized insights. This is a specific verb+resource pairing, but it does not explicitly differentiate it from siblings such as get_stats or recommend_posts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like get_stats, list_subreddits, or recommend_posts. No conditions, exclusions, or alternative tool names appear, so an agent has to infer the intended use from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete saved posts. DESTRUCTIVE and IRREVERSIBLE. First call WITHOUT confirmed=true to see which posts will be deleted, then call again WITH confirmed=true after user explicitly approves.
| Name | Required | Description | Default |
|---|---|---|---|
| post_ids | Yes | Array of post IDs to delete | |
| confirmed | No | Must be true to actually delete. First call without this to preview what will be deleted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description extends the destructiveHint annotation by explaining that the deletion is irreversible and by detailing the required confirmation workflow. It makes clear what is destroyed (the passed posts) and the safety gate that methods must complete, adding context the annotations alone don't convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence is a strong, front-loaded warning about the tool's core behavior, and the second provides the essential usage pattern.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive nature, two parameters, and no output schema, the description is complete. It covers the destructive effect, the confirmation protocol, and the correct order to invoke the tool, enabling a model to call it accurately without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not add meaningful parameter information beyond the schema, which already describes the post_ids array and the confirmed flag's 'preview' semantics. Since schema coverage is 100%, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with the specific action 'Permanently delete saved posts,' naming the verb and resource. It also includes a prominent DESTRUCTIVE warning and is easily distinguished from its siblings, which are mostly read or labeling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit invocaction protocol: first call without confirmed=true to preview, then call with confirmed=true only after user approval. This is concrete when-to-use and when-not-to-use direction, leaving no ambiguity about avoiding direct destructive calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract all external URLs from saved posts matching a query. Filters out Reddit CDN URLs — only returns genuinely external links. Use for "compile all resources about X", "get all links from my saves about Y".
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | Optional: filter by label name | |
| limit | No | Max posts to scan for links (default: 50, max: 200) | |
| query | Yes | Topic to search posts for | |
| subreddit | No | Optional: filter by subreddit (without r/) | |
| include_reddit_links | No | Include Reddit permalink URLs (default: false, only external links) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Beyond that, the description discloses a specific behavioral trait—Reddit CDN URLs are filtered out, so only genuinely external links are returned—which is not present in the annotations and is valuable for setting expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The core action is front-loaded, the filtering caveat follows immediately, and the use cases are compactly attached. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, link-extraction tool, the description along with annotations and full schema coverage is nearly complete. The only minor gap is the lack of an explicit output shape (e.g., whether URLs are deduplicated or accompanied by post context), but the return type is strongly implied by 'Extract all external URLs'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters (query, label, limit, subreddit, include_reddit_links) are already documented. The description adds no additional parameter-level meaning beyond the schema, which aligns with the baseline 3 for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Extract'), a resource ('external URLs from saved posts'), and a matching criterion ('matching a query'). It clearly distinguishes itself from siblings like search_posts or get_recent by targeting link extraction rather than post retrieval, and adds the differentiating detail of filtering out Reddit CDN URLs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Two concrete use cases are provided ('compile all resources about X', 'get all links from my saves about Y'), which clearly signal when to invoke this tool. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to select it over post-search siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find semantically similar posts saved from DIFFERENT subreddits — surfaces hidden links between interests. Use for "what connects my saves?", "find cross-subreddit themes", "surprising connections".
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max connections to return (default: 10, max: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral nuance that results are limited to cross-subreddit pairs and that the tool surfaces 'hidden links' — useful context beyond the annotations. However, it doesn't disclose details like whether results are ranked by similarity strength or how 'semantically similar' is determined.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence followed by three short example queries. Every word earns its place: the core function, the cross-subreddit constraint, the value proposition, and usage examples are all front-loaded with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, idempotent tool with one fully-documented parameter and no output schema, the description covers the essential context: what it does, what makes it unique, and when to use it. The only minor gap is the lack of detail about the return format, but since there's no output schema and the tool is simple, this is a small omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the only parameter (limit) is fully documented in the schema with default and max values. The description doesn't add parameter-level detail, but with full schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Find'), a specific resource ('semantically similar posts saved from DIFFERENT subreddits'), and the unique value proposition ('surfaces hidden links between interests'). It clearly distinguishes itself from siblings like find_similar_posts and find_debates by emphasizing cross-subreddit connections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit example queries ('what connects my saves?', 'find cross-subreddit themes', 'surprising connections') that signal when to use this tool. It doesn't explicitly state when not to use it or name alternatives, but the examples and the 'DIFFERENT subreddits' emphasis make the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find posts on similar topics that may argue different sides — surfaces contrasting viewpoints. Looks for opinion/debate signals in titles. Use for "find debates in my saves", "opposing viewpoints", "where do my saves disagree?".
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max debate pairs to return (default: 8, max: 15) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a genuine behavioral detail beyond that: it 'looks for opinion/debate signals in titles' and implies returned items are pairs ('max debate pairs'), which aids an agent in anticipating results and methodology. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences only, tightly written. The core function is front-loaded, the scoping detail about title signals comes second, and the usage examples close it out. Every clause adds value with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a simple read-only tool with one optional, fully documented parameter and no output schema, the description covers what it does, how it does it, and when to call it. The only minor gap is that the exact shape of a 'pair' is not specified, but this does not block correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the 'limit' parameter is already fully described as 'Max debate pairs to return (default: 8, max: 15)'. The description does not add any additional semantic info about the parameter, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource ('Find posts on similar topics that may argue different sides') and names the differentiated output ('surfaces contrasting viewpoints'). The phrases 'opposing viewpoints' and 'where do my saves disagree?' help distinguish it from sibling tools like find_similar_posts (which presumably finds similar perspectives) without even naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear, concrete use cases: 'find debates in my saves', 'opposing viewpoints', 'where do my saves disagree?'. This frames when to invoke the tool, but it does not name alternative tools or state when not to use it, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find posts semantically similar to a reference post or a topic description. Use when asked "what else like this?", "find related posts", "show similar".
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of similar posts to return (default: 8, max: 20) | |
| query | No | Topic or description to find similar posts for when no specific post_id is known | |
| post_id | No | ID of the reference post to find similar posts for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that matching is semantic and can be based on a post or topic, but it does not explain behavior when no parameters are provided, when both post_id and query are given, or what output shape to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose and followed by practical trigger examples. Every sentence earns its place and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The combination of rich schema descriptions and safety annotations makes the basic call clear. However, the input schema marks all parameters optional and the description does not explicitly state that at least one of post_id or query should be provided, nor does it clarify precedence if both are supplied. Without an output schema, this leaves some ambiguity for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well documented in the input schema. The description mostly restates the two input modes ('reference post' and 'topic description') already present in the parameter descriptions, providing no additional semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and names the resource: 'posts semantically similar to a reference post or a topic description.' This is clear and distinct from basic search, but it does not explicitly differentiate this tool from sibling tools like 'semantic_search' or 'recommend_posts,' which likely handle overlapping requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete trigger phrases: 'what else like this?', 'find related posts', 'show similar.' This gives clear context for when to use the tool, though it does not state exclusions or name alternatives when this tool should NOT be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show engagement depth per topic — how many posts saved, read, and labeled in each auto-category. Tiers: Exploring (<6), Familiar (6-15), Deep (16-30), Expert (31+). Use for "what am I most into?", "where am I deepest?", "my expertise breakdown".
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Optional: get depth for a specific topic only |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds useful behavioral context: it defines the tier boundaries (6, 15, 30) and the metrics considered (saved, read, labeled). It does not disclose edge cases like missing data or behavior with no topics, but given annotation coverage of safety, a 3 is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, fitting in three sentences: the primary purpose, tier definitions, and example queries. All sentences earn their place, and the tier information is front-loaded. Minor redundancy with the schema's description of the optional topic parameter, but no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one optional parameter, no required fields, and no output schema, the description covers the input side well. It explains the output metaphor (tiers) but does not specify the exact output structure (e.g., a list of topics with counts). However, the example queries and tier definitions give a clear understanding of what will be returned. Missing performance or pagination notes, but given low complexity, it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes the 'topic' parameter as 'Optional: get depth for a specific topic only', which is clear. The description reinforces this by indicating the tool can be used for overall breakdown or specific topic. Since schema coverage is 100%, the description adds minimal semantic value beyond the schema; the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool shows engagement depth per topic, specifying metrics (posts saved, read, labeled) and auto-categories. It includes tier thresholds (Exploring, Familiar, Deep, Expert) which define the output semantics. This distinguishes it from siblings like get_stats (general stats) and get_recent (recent posts) because it focuses on topic-specific depth classification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit example user queries ('what am I most into?', 'where am I deepest?', 'my expertise breakdown') that signal when to use this tool. However, it does not explicitly state when NOT to use it or name alternative tools (e.g., get_stats for general stats). The given examples cover the typical use case but lack exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get user notes attached to saved posts. Returns posts that have personal notes added by the user.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results when listing all notes (default: 20, max: 50) | |
| post_id | No | Get the note for a specific post ID. If omitted, returns all posts with notes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds the useful context that only posts with notes are returned, which goes beyond the schema. However, it does not mention pagination behavior or default limit, though those are in the schema. With annotations doing heavy lifting, a 3 is fair.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The primary purpose is front-loaded, and the second sentence clarifies the return scope. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two optional parameters and complete schema coverage, the description is sufficient. It explains the tool's purpose and what it returns, which is enough for an agent to call it correctly. A 4 is given because it doesn't explicitly state that it returns only posts with notes (though that is implied) and lacks any mention of sorting or limits beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well-documented. The description adds no additional semantic detail beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get user notes attached to saved posts') and clarifies the scope by saying it returns posts that have notes. It is distinct from sibling tools like add_note, but does not explicitly differentiate itself from other get_* tools, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (fetching notes for saved posts) but does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions. The context is clear but not prescriptive, so it sits at the implied-usage level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details of a specific saved post by its Reddit post ID, including the complete body text (selftext)
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | The Reddit post ID (e.g., "t3_abc123" or just "abc123") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that the complete body text/selftext is included, which is useful, but it doesn't disclose potential errors, invalid IDs, or output structure. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, focused sentence that front-loads the action and resource, includes the key qualifier 'saved post,' and specifies the important selftext detail with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only retrieval tool, the description is largely complete: it states what is retrieved and what the response includes. It could improve by noting behavior for invalid or unsaved IDs, but the current description is adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents post_id with an example and 100% coverage. The description references looking up by post ID but adds no new semantic detail beyond what the schema provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb, resource, and scope: retrieving a single saved post by its Reddit post ID and returning full details including selftext. It is unambiguous and easy to understand, but it does not explicitly differentiate itself from the similarly named sibling get_post_content, so it stops short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies clear usage context: use this tool when you need the full details of one specific saved post identified by post_id. It doesn't mention alternatives or exclusions, but for a simple by-ID retrieval tool the intended use case is evident from the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full text body of one or more posts by ID. Use after search when you need complete content for summarizing, comparing, or deep analysis. Search results include only a short preview — this returns the full text.
| Name | Required | Description | Default |
|---|---|---|---|
| post_ids | Yes | Array of post IDs to get full text for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral context that search results are only previews and this returns full text, which is useful. However, it doesn't disclose details like rate limits, response size limits, or behavior for invalid/nonexistent post IDs, which would be valuable for a batch retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all informative: the action, the use case, and the contrast with search previews. No filler or redundancy. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only batch retrieval tool with one parameter and full schema coverage, the description is nearly complete. It explains when to use it and what it returns. The only minor gap is not describing behavior for missing/invalid IDs or response format, but the output schema is absent and the tool is simple enough that this is a small omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the only parameter, post_ids, is described as 'Array of post IDs to get full text for'. The description adds the context that these are post IDs and the result is full text, but doesn't add meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a specific resource ('full text body of one or more posts by ID'), and explicitly contrasts with search results that include only a short preview. This clearly distinguishes it from siblings like get_post and search_posts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool after search when complete content is needed for summarizing, comparing, or deep analysis, and notes that search results only include a preview. This provides clear when-to-use guidance and implicitly differentiates from search_posts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the N most recently saved posts (no time filter — returns latest saves regardless of when they were saved). For time-bounded queries like "saved this week" or "last month", use search_posts with time_filter instead.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of recent posts to return (default: 10, max: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the key behavioral nuance that there is no time filtering, which is useful. However, it doesn't mention pagination, ordering details beyond 'most recently saved', or what happens when limit exceeds max, though the schema covers the max. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core function and the key caveat (no time filter), followed by a clear routing instruction. Every sentence earns its place with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one parameter and full schema coverage, the description is nearly complete. It covers the core behavior, the caveat, and the alternative. The only minor gap is that it doesn't describe the return format, but with no output schema and a simple list operation, this is a small omission. The annotations cover safety, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the limit parameter with default and max. The description adds the meaning of 'limit' as 'N most recently saved posts' but doesn't add significant new semantics beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: retrieving the N most recently saved posts, with an explicit clarification that there is no time filter. It also distinguishes itself from search_posts, which is a sibling tool, by naming it directly and explaining the difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool (for recent saves without time bounds) and when not to use it (for time-bounded queries), and names the alternative (search_posts with time_filter). This is exactly the kind of routing guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get reading reminders the user has set for saved posts — upcoming, past-due, or all.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default: 20, max: 50) | |
| filter | No | Filter reminders: upcoming (future), past_due (overdue), or all (default: all) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal readOnly, idempotent, and non-destructive behavior. The description adds scoping (saved posts) and filter states, but does not disclose return shape, ordering, or pagination behavior beyond the limit parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence that names the resource, scope, and all relevant filter modes with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only list tool with fully documented parameters and annotations, nothing essential to invoking it correctly is missing. The lack of an output schema is acceptable because the response is a straightforward reminders list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with limit and filter already documented. The description only restates the three enum values and adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description combines a specific verb ('Get'), resource ('reading reminders'), and scope ('the user has set for saved posts'), with the three filter categories. This differentiates it from sibling tools like get_notes or get_unread by naming a distinct reminder resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It establishes clear context: this retrieves the user's saved-post reminders and supports upcoming/past-due/all filters. It does not explicitly name alternative tools or exclusion conditions, but the resource is distinct enough among siblings that an agent can infer when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get library statistics — total posts, subreddit breakdown, top subreddits, saving trends
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful detail about the computed categories, but it does not disclose behaviors such as whether results are cached, live, or limited to a certain time range; this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with a dash-separated list of the statistics it returns. There is no wasted wording, and the core purpose appears first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only statistics tool with no output schema, the description names the main output categories an agent would need to know. However, 'saving trends' and 'top subreddits' lack detail on ordering or time scope, so the description is strong but not fully exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% coverage, so there is nothing for the description to explain about argument semantics. The baseline for a zero-parameter tool is 4, and the description usefully conveys what the output will cover, even though no parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'Get library statistics', followed by an enumerated list of the aggregate results (total posts, subreddit breakdown, top subreddits, saving trends). It is clear, but it does not explicitly differentiate itself from siblings like list_subreddits or analyze_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description only states what statistics are computed, but does not say 'use this when you need an overview' or exclude cases where a sibling tool like list_subreddits or get_expertise_map would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get saved posts that haven't been read yet. Useful for finding posts the user saved but hasn't gotten to.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default: 20, max: 50) | |
| subreddit | No | Filter unread posts by subreddit (without r/ prefix) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds no behavioral detail beyond the obvious read semantics—nothing about pagination, ordering, or side effects—so it adds value mainly by restating the domain context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no fluff. The first sentence states the operation directly, and the second adds a concise user-oriented rationale without repeating the tool name or schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with full parameter descriptions and safety annotations, the description covers the essential context. It lacks details about return shape or ordering, but those are not critical for a tool this straightforward and no output schema exists to clarify them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters have useful descriptions in the schema: limit includes default/max, and subreddit clarifies the format. The tool description itself adds no parameter-level meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: "Get saved posts that haven't been read yet." The qualifier "saved" and "haven't been read yet" differentiates it from a generic recent-posts or search tool, though it does not explicitly name a sibling as an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase "Useful for finding posts the user saved but hasn't gotten to" gives clear user-facing context for when the tool is appropriate. It does not explicitly state when not to use it or name an alternative, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a label/tag to one or more saved posts. Search first to get post IDs, then label them.
| Name | Required | Description | Default |
|---|---|---|---|
| label | Yes | The label to add | |
| post_ids | Yes | Array of post IDs to label |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the safety profile: readOnlyHint=false signals an append-style write, idempotentHint=true means re-labeling is safe, and destructiveHint=false means existing posts/labels are not destroyed. The description's 'Add a label/tag' wording is consistent with these annotations but adds minimal behavioral context beyond them (only the 'saved posts' scoping). No contradiction exists; the description simply doesn't enrich beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The primary action is front-loaded in the first sentence, and the second sentence earns its place by giving actionable workflow guidance. Nothing is redundant or decorative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, low-risk write tool with only two fully documented parameters and annotations covering idempotency and destructiveness, the description is nearly sufficient. It covers purpose and prerequisite workflow. Minor gaps remain — no mention of what happens with invalid post IDs, whether new labels are auto-created, or return format — but these are low-stakes for this use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — both label ('The label to add') and post_ids ('Array of post IDs to label') are already documented in the schema. The description mirrors these concepts ('post IDs', 'label') without adding format, length, or edge-case semantics. Per rubric, high coverage warrants baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Add'), a concrete resource ('label/tag'), and the object being modified ('one or more saved posts'). This action is unambiguous and clearly distinct from siblings like remove_label, list_labels, and add_note without needing to open any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear workflow context: 'Search first to get post IDs, then label them.' This tells an agent the prerequisite step and when the tool fits in a sequence. However, it does not explicitly name alternatives or state when-not-to-use conditions, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all AI-generated topic categories with post counts and sample posts. Shows how posts are automatically grouped by topic. Use for "what topics do I have?", "show my auto categories", "what are my posts grouped into?".
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that the tool is read-only, idempotent, and non-destructive. The description adds useful context by explaining that it shows automated topic grouping and that the output includes post counts and sample posts, which is beyond what the annotations state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, front-loaded with the core purpose, and the usage examples add practical value without redundancy. Every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool, the description plus annotations are completely sufficient. Even without an output schema, it states what the results will contain, and the annotations cover the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters, so there are no parameter details to document. The baseline for zero-parameter tools is 4, and the description's focus on output contents is appropriate since no input semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('list'), a specific resource ('AI-generated topic categories'), and the key fields returned ('post counts and sample posts'). It is clearly distinguishable from sibling tools like list_labels and list_subreddits because it emphasizes 'AI-generated' and topic grouping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete example user queries ('what topics do I have?', 'show my auto categories') that signal when the tool is appropriate. It does not explicitly mention when not to use it or name an alternative such as list_labels, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all labels/tags the user has applied to their saved posts, with counts per label.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds useful context by stating that all labels are returned and that counts per label are included, and it scopes the operation to the user's saved posts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no filler. It front-loads the action and scope and immediately conveys the key output detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only, idempotent tool with strong annotations, the description fully covers the essential behavior: listing user-applied labels with counts. No output schema exists, but the description provides enough return-semantics detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description does not need to explain parameter meaning, and the empty schema imposes no burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and clearly identifies the resource ('labels/tags the user has applied to their saved posts'), while also specifying the output includes counts per label. This makes the tool's purpose distinct from siblings like label_posts and remove_label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the use case clear: retrieving existing user-applied labels for saved posts. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5, but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all subreddits in the saved library with post counts
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's job is reduced. It adds the scope ('saved library') and that results include post counts, which is useful beyond annotations. However, it does not mention ordering, freshness of counts, or pagination, leaving some behavioral ambiguity for a listing operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence states the action, resource, scope, and a key output detail without any filler. Every word earns its place, and the structure is optimally concise for a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only list tool with rich annotations and no output schema, the description is nearly complete: it names the resource scope and indicates post counts will be in the result. Minor gaps like ordering or whether counts are live could be added, but they are not essential for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and schema description coverage is 100% by default. Per the rubric, a zero-parameter tool gets a baseline of 4; the description correctly adds no irrelevant parameter information, and nothing more is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and clearly identifies the resource ('all subreddits in the saved library') with an additional distinguishing detail ('with post counts'). This makes it easy to tell apart from siblings like list_auto_collections or get_stats, even without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need the saved subreddits with post counts) but provides no explicit guidance on when not to use it or how it differs from alternatives. With several sibling list-type tools, some routing direction would help, but the resource scope is clear enough to suggest typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark one or more posts as read or unread.
| Name | Required | Description | Default |
|---|---|---|---|
| is_read | Yes | true = mark as read, false = mark as unread | |
| post_ids | Yes | Array of post IDs |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, covering the key behavioral aspects. The description adds no additional context about permanence, scope, or effects on other data. It does not contradict the annotations, so a score of 3 is appropriate given the low bar set by annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no superfluous words. It front-loads the action and state, making it immediately scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two fully described parameters, no output schema, and annotations covering idempotency and destructiveness, the description is complete. An agent has everything needed to call the tool correctly without further elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters fully described in the schema. The description simply restates the parameter semantics ('read or unread') without adding extra meaning, so it meets the baseline but adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('mark') with a clear resource ('posts') and state ('read or unread'), making the action unambiguous. It distinguishes itself from sibling tools like get_unread (a read operation) and delete_posts (destructive).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of related tools like get_unread for listing unread posts or label_posts for other state changes, leaving the agent to infer appropriate usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get smart reading recommendations from unread saves. Uses engagement signals, recency, content depth, and variety to pick the best posts to read next. Use when the user asks "what should I read?", "recommend something", "suggest a post", or "surprise me".
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of recommendations (default: 5, max: 15) | |
| subreddit | No | Optionally restrict recommendations to a specific subreddit |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context by explaining the selection criteria (engagement signals, recency, content depth, variety), which goes beyond the annotations. It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences, front-loading the core purpose and then providing usage triggers. Every sentence adds value, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two optional parameters, no output schema, and full schema coverage, the description is quite complete. It explains what the tool does, when to use it, and the selection logic. It could slightly improve by explicitly noting that it only considers unread saves (already implied) or what the return type looks like, but these are minor gaps given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (count and subreddit), so the schema already documents them adequately. The description does not add further parameter-specific details, such as the meaning of count in relation to unread saves or how subreddit filtering behaves. With full schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), resource ('smart reading recommendations from unread saves'), and is clearly distinct from siblings like get_unread or search_posts. It also provides concrete user-phrase triggers ('what should I read?', 'recommend something'), making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists when to use the tool via trigger phrases, which is strong guidance. However, it does not mention any exclusions or alternatives (e.g., when to use get_unread or search_posts instead), so it lacks the 'when-not' component that would earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a label/tag from one or more saved posts.
| Name | Required | Description | Default |
|---|---|---|---|
| label | Yes | The label to remove | |
| post_ids | Yes | Array of post IDs |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the key behavioral traits: not read-only, idempotent, and not destructive. The description adds that only the label/tag is affected, not the posts themselves, which is useful. However, it does not disclose how the operation behaves when the label is absent or when some post IDs are invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and resource. It has no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation with annotations covering idempotency and destructiveness, the description plus schema is largely sufficient. It could mention edge-case behavior such as what happens when the label is already missing, but this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the parameters with descriptions for both post_ids and label. The tool description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove a label/tag') and the resource ('from one or more saved posts'). This distinguishes it from the sibling tool label_posts, which performs the inverse operation. An agent can understand exactly what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the verb and resource, but the description does not explicitly state when to use this tool versus alternatives like label_posts or list_labels. It gives no exclusions or contextual conditions, but it is not misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search, filter, and sort saved Reddit posts. When a query is provided, uses the full semantic pipeline (AI query expansion + embedding similarity + keyword matching + precision relevance filter) for high-accuracy topical results. Filters are independent and stack. Use query ONLY for content/topic matching — never put sort/filter intent into query (use sort_by, time_filter, read_status, content_type instead). Omit query entirely for sort-only or filter-only requests.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | Filter to posts with this exact label applied | |
| limit | No | Max results (default: 20, max: 200). Use higher limits (100-200) for exhaustive queries. | |
| query | No | CONTENT/TOPIC search only — what the posts are about (e.g. "Python tutorials", "career advice"). Leave empty for sort/filter-only requests. | |
| author | No | Filter by Reddit username (without u/ prefix) | |
| date_to | No | End of custom date range in ISO format (e.g. "2025-06-30") | |
| sort_by | No | Sort order (default: newest, sorted by save date). Use "relevance" only with a query. | |
| date_from | No | Start of custom date range in ISO format (e.g. "2025-01-15") | |
| item_type | No | Filter by item type. Omit to return both. | |
| max_score | No | Maximum upvote score (for "hidden gems" / low-upvote posts) | |
| min_score | No | Minimum upvote score | |
| subreddit | No | Filter by subreddit name (without r/ prefix) | |
| unlabeled | No | If true, return only posts with no labels applied | |
| date_field | No | Which timestamp time_filter/date_from/date_to applies to. "saved" = when bookmarked (default). "posted" = when originally published on Reddit. | |
| read_status | No | Filter by read/unread state | |
| time_filter | No | Restrict to a time window. Pair with date_field. | |
| content_type | No | Filter by media type. "text" = self posts. "link" = external URLs. "image" = photos. "video" = videos. | |
| min_comments | No | Minimum comment count |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the underlying semantic pipeline (AI query expansion, embedding similarity, keyword matching, precision relevance filter), which is beyond the read-only, idempotent, and non-destructive annotations. It adds meaningful behavioral context about how search works internally, though it doesn't discuss performance or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary purpose, then expands on the pipeline, filter stacking, and query rules in a logical order. Each sentence contributes new information without redundancy, though it is somewhat long—still efficient given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 17 parameters and no output schema, the description covers the most critical usage pitfalls (query misuse, filter independence, when to omit query). It doesn't explain return format or pagination, but those are less critical for a read-only search tool and the annotations cover safety. Overall, it is sufficiently complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the role of the 'query' parameter (content/topic only) and warning against mixing sort/filter intent into it, plus noting that 'relevance' sort is only valid with a query. These nuances go beyond the schema definitions, earning a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches, filters, and sorts saved Reddit posts, specifying the resource and core actions. It explains the semantic pipeline when a query is given, which adds specificity. However, it does not explicitly differentiate from the sibling tool 'semantic_search', which could overlap in function, so it falls short of full distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on query usage: use query only for content/topic matching, never for sort/filter intent, and omit it entirely for sort-only or filter-only requests. It also notes that filters stack independently. This is strong within-tool guidance, though it does not mention when to choose this tool over alternatives like semantic_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search saved posts by meaning — finds posts related to your query even when they use different words. Best for conceptual queries like "posts about building side projects" or "career growth advice". Uses AI query expansion + embedding similarity + keyword matching + a precision relevance filter for high-accuracy results. When answering the user, hyperlink each post title to its Reddit permalink and add a 1-2 sentence summary.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (default: 15, max: 100). Use higher limits (50-100) for broad or exhaustive queries. | |
| query | Yes | Natural language description of what you are looking for | |
| min_similarity | No | Minimum similarity score 0-1 (default: 0.20). Lower = broader results. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/destructive annotations, the description reveals the hybrid retrieval mechanism (query expansion, embeddings, keyword matching, precision filter) and the expected result presentation (hyperlink post titles to permalinks plus a 1-2 sentence summary). This is useful behavioral context that annotations cannot express, though it is somewhat algorithm-heavy.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences with the core purpose front-loaded. Each sentence contributes either selection guidance, behavioral transparency, or output formatting; there is no repetition of schema fields or annotation flags.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with no output schema, the description covers purpose, when to use it, retrieval behavior, and practical output format (title + Reddit permalink + summary). The main gap is not stating the returned item shape or zero-result behavior explicitly, but the schema and annotations cover the rest.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents query, limit, and min_similarity fully. The description adds no parameter-level information beyond reinforcing the query style, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete verb and resource ('Search saved posts by meaning') and clarifies semantic matching ('even when they use different words'), which distinguishes it from a plain keyword search sibling. The conceptual examples reinforce what the tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Best for conceptual queries like ...' gives an explicit trigger condition and examples. It does not name an alternative or say when to prefer exact-match/keyword search, so it stops short of full when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
add_noteanalyze_collectiondelete_postsextract_linksfind_cross_connectionsfind_debatesfind_similar_postsget_expertise_mapget_notesget_postget_post_contentget_recentget_remindersget_statsget_unreadlabel_postslist_auto_collectionslist_labelslist_subredditsmark_readrecommend_postsremove_labelsearch_postssemantic_search
Add one secure layer between your agents and this server.
