Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds value beyond readOnlyHint=true annotation by clarifying it 'works anonymously', explaining time_filter only applies to top/controversial, describing return shape, and noting the after cursor. Strong context beyond annotations.

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, information-dense, purpose front-loaded, every clause earns its place. Covers tool purpose, behavioral notes, return shape, and alternatives without redundancy.

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 5 optional params (0 required), full schema descriptions, and rich annotations, the description covers all essential context: default behavior, pagination, auth model, and edge cases. Nothing material 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 coverage is 100% with good per-param descriptions, earning a baseline 3. Description adds cross-parameter semantics (omit subreddit → home feed, time_filter interaction with sort) and describes pagination behavior not in 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?

Uses a specific verb (browse) plus resource (subreddit or home feed) with concrete sort orders. Explicitly differentiates from siblings by naming get_top_posts and search_reddit as alternatives with different purposes.

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?

States when to use this tool ('by sort order', 'by feed order') and explicitly directs to get_top_posts as a shortcut and search_reddit for keyword-based lookup. Clear when/alternatives guidance.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare non-idempotent and openWorld, but description adds critical context: requires REDDIT_USERNAME/PASSWORD, is mutating (confirmed by readOnlyHint=false), and returns id/URL. Warns of account bans without safe mode, which is valuable beyond annotations.

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?

Well-structured with clear sentences, but somewhat long. Front-loaded with action and key caveats. The warning about spam detection is useful but could be shortened without losing value.

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 mutating, non-idempotent tool with no output schema, the description covers prerequisites, return values, and risks. It compensates for missing output schema by stating the returned id and URL. Adequately complete for an agent to use 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?

Schema coverage is 100%, so baseline is 3. Description adds meaning by linking content to is_self, explaining flair requirements, and mentioning that title cannot be edited later. Does not repeat every parameter but reinforces key usage constraints.

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?

Clearly states it creates a text or link post in a subreddit, with explicit verb and resource. Distinguishes from siblings like delete_post and edit_post by describing the publish action and the distinction between self/link 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?

Provides explicit when-to-use guidance: check get_subreddit_rules and get_post_flairs first for required flairs or content restrictions. Also warns against rapid posting due to spam detection, aligning with the openWorldHint and non-idempotent annotations.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already state destructive and idempotent, and the description reinforces that without requiring long original. It also adds critical beyond-annotation details: the required REDDIT_USERNAME and REDDIT_PASSWORD, the authorization/ownership limitation, and the subtle detail that the comment id persists after the content is removed. No contradiction with annotations.

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 four tight sentences with no wasted words. It front-loading the most important facts, following with limitations, and closes with the risk warning. Each sentence serves a clear 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 single-parameter, no-output-schema deletion tool, the description covers all necessary areas: purpose, scope, auth, idempotency, permanence, and alternative. The annotations and sibling context complete the picture sufficiently, so the description is fully complete.

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 only parameter, thing id, is fully documented in the schema at 100% coverage, including the accepted format and automatic 't1_' prefix. The tool description adds no extra symbol-flavor meaning beyond that comprehensive schema, so baseline 3 is appropriate because the schema carries the load.

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 'Permanently delete one of your own comments,' using a strong verb-resource pair and the scope. It further differentiates from the sibling delete simple by explicitly saying 'use delete_post for posts,' making its purpose distinct.

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 gives clear when-to-use guidance for deleting a comment the authenticated account owns, when-not-to-use by excluding posts and comments authored by others, and names the alternative delete_post for posts. This covers the key decision boundary.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds detail beyond the annotations: irreversibility warning, idempotent no-op behavior, auth requirements, ownership restriction, and the fact that the post id remains. This enriches behavioral understanding and aligns with the annotations (destructiveHint=true, idempotentHint=true).

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?

Every sentence earns its place: main action, safety characteristics, prerequisites, scope, alternative, and warning. The description is dense but not redundant, and the core action is front-loaded.

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 delete operation, the description covers purpose, safety, idempotency, auth, ownership, irreversibility, and differentiation from the comment-deletion sibling. Combined with strong annotations, no critical gap remains.

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 already documents thing_id thoroughly, including accepted formats and the automated t3_ prefix. The description adds no parameter-specific semantics beyond referencing 'the post you name,' so baseline 3 applies due to high 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?

States the exact action: 'Permanently delete one of your own posts.' It uses a specific verb+resource, and differentiates from sibling delete_comment by explicitly noting 'use delete_comment for comments.'

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 clear when-to-use guidance: works only on self-authored posts, requires credentials, and excludes comments with an explicit alternative. This tells the agent both the prerequisites and the boundary of applicability.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations include destructiveHint=true and idempotentHint=true; the description reinforces and expands on these by stating 'Mutating and idempotent (same text → same result); it overwrites the previous content' and 'Adds an "edited" marker.' It also discloses potential spam detection risk, which is beyond the annotations. No contradiction.

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, each earning its place: purpose, usage constraints/alternatives, and a warning. Front-loaded with the core action, no redundant phrasing.

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 2-parameter mutating tool with annotations and no output schema, the description covers purpose, side effects (overwrite, edited marker), prerequisites, alternative tools, and risk mitigation. It is fully self-contained for an agent to select and invoke the 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?

Schema description coverage is 100%, with both new_text and thing_id well described in the schema. The tool description adds no new parameter-level detail beyond what is already in the schema (e.g., it repeats 'overwrites' and 'comments you authored' but doesn't add syntax or format details). 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 opens with 'Replace the text of one of your own comments,' which is a specific verb (replace) and resource (one of your own comments). It clearly distinguishes from sibling tools by explicitly mentioning reply_to_post for new comments and edit_post for 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?

Provides explicit guidance: 'Use reply_to_post to add a new comment, or edit_post for posts' names alternatives. It also states prerequisites ('works only on comments you authored', 'Requires REDDIT_USERNAME and REDDIT_PASSWORD') and a warning about rapid edits with a mitigation (REDDIT_SAFE_MODE).

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide idempotentHint, destructiveHint, and readOnlyHint=false. The description adds meaning beyond these: it states the overwrite behavior explicitly, mentions the 'edited' marker, requires REDDIT_USERNAME/PASSWORD credentials, and warns about spam detection. No contradiction with annotations; rather, it enriches them with operational 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 sentences but packs: purpose, mutability, idempotency, credential requirements, scope, marker side-effect, alternative tools, and a safety warning. Every clause earns its place; no fluff. Information density is high while remaining readable.

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 mutating tool with no output schema, the description covers all essential operational aspects: what it does, prerequisites (credentials), constraints (self posts only), side effects (overwrite, marker), and risk (spam detection). The absence of output schema is acceptable since mutation result is straightforward. Complete guidance for an agent to invoke 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?

Schema coverage is 100% with detailed descriptions for both parameters (new_text explains overwrite and markdown support; thing_id explains format and ownership constraint). The description adds little beyond the schema—it reiterates overwrite and self-post constraint but introduces no new per-parameter semantics. Baseline 3 is appropriate given the schema's thoroughness.

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 specific verb+resource: 'Replace the body text of one of your own self-text posts.' It clearly scopes to self-text posts, distinguishes from edit_comment and create_post, and clarifies that titles and link posts cannot be edited. This is fully differentiated from siblings.

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?

Explicitly names alternatives: 'Use create_post to make a new post, or edit_comment for comments.' Also states conditions for use (self posts only, authored by you) and warns about rapid edits triggering spam detection, with a mitigation (REDDIT_SAFE_MODE). This gives clear when/when-not/alternatives guidance.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description adds real behavioral context: it requires REDDIT_USERNAME/REDDIT_PASSWORD, fails in anonymous mode, and always returns the logged-in account regardless of any misleading expectations about arbitrary users. This meaningfully expands on the annotations.

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 compact sentences: what the tool returns, its access requirements, and explicit guidance versus alternatives. Every sentence provides distinct value without 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 zero-parameter, read-only profile retrieval tool, the description is complete: it covers purpose, content, prerequisites, failure mode, and scope limitations. No output schema exists, but the description names the main returned data (karma, account age, status flags), which 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 input schema has zero parameters and is fully covered by the description's statement that the profile belongs to the authenticated account. With no params to document, the description naturally explains why no input is needed, meeting the baseline for parameter clarity.

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 identifies the tool as returning the authenticated user's own profile and lists key contents (karma, account age, status flags), which distinguishes it from the sibling get_user_info. It also explicitly states what the tool does not do, making its scope unambiguous.

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 instead of get_user_info when the current account is needed, and warns against using it for other users. It also provides the critical usage condition: requires user credentials and fails in anonymous mode.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint, and the description adds context beyond that by stating 'works anonymously' and by describing the returned shape: 'author, body excerpt, score, link.' This gives behavior insight without overstating side effects. It slightly misses possible failure modes or volume limits, but the combination with annotations is strong.

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, each earning its place: the first says what it does, the second gives the data flow and return fields, and the third states the prerequisite and key constraint. It is front-loaded and free of redundant phrasing.

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?

Despite having no output schema, the description discloses the return fields, identifies the dependency on get_post_comments, explains the 'more' node source, and asserts anonymity and read-only behavior. Given the small parameter count and rich annotations, the description satisfies all important context an agent needs.

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 already have clear descriptions, so the baseline is 3. The description reinforces that comment_ids must come from a 'more' node and says 'do NOT invent ids,' adding practical workflow context but no new parameter format or type details 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 opens with a specific verb and resource: 'Expand truncated ‘load more comments’ stubs in a thread.' This clearly distinguishes the tool from get_post_comments, as this one fetches hidden comments from 'more' nodes while get_post_comments surfaces the thread and its stubs. The scope is fully defined.

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 gives explicit usage guidance: call get_post_comments first to obtain the thread and 'more' node ids, then pass those ids here. It also warns against inventing ids and notes that it works anonymously and read-only, which helps an agent decide when to invoke this tool.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, but the description adds meaningful behavioral context: credentials are required, the result is interleaved posts/comments in newest-first order, and pagination uses an `after` cursor. No contradiction with annotations exists.

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 short, front-loaded with the purpose, and every sentence contributes useful information — scope, credentials, return behavior, and explicit sibling alternatives. No redundant or vague wording.

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?

No output schema exists, but the description communicates the essential return semantics: up to `limit` items, posts and comments interleaved, newest first, with an `after` cursor. It could arguably describe item fields in more detail, but for this tool the provided context is reasonably complete.

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 `limit` and `after` already well-described. The description reinforces their meaning by mentioning the pagination cursor and item limit, but it does not add substantive parameter semantics beyond what the schema already provides.

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 specifies a concrete action and scope: fetching the authenticated user's own recent activity, interleaving posts and comments, newest first. It also explicitly distinguishes this from get_my_saved, get_user_posts, get_user_comments, and get_post_comments.

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 when-to-use guidance: use get_my_saved for saved items, get_user_posts/get_user_comments when targeting another user, and do NOT use this tool for a specific post's thread — use get_post_comments instead.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only mark readOnlyHint/openWorldHint; the description adds critical details: required user credentials (REDDIT_USERNAME/REDDIT_PASSWORD), pagination behavior ('Returns up to limit items plus an after cursor'), and privacy context ('saved items are private'). This goes far beyond the annotations and fully discloses the tool's behavior.

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?

Every sentence earns its place: purpose, credential requirement, pagination output, and a clear distinction from a sibling tool with an explicit cross-usage warning. No redundant phrasing 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?

For a two-parameter read-only tool with no output schema, the description covers purpose, auth, pagination, alternative tools, and edge-case privacy constraints. It answers all likely agent questions and leaves nothing structurally ambiguous.

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 fully documents each parameter. The description mentions `limit` and `after` in a pagination context, reinforcing their purpose, but doesn't add new syntax or formatting details beyond what the schema already provides—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?

Description explicitly states 'Get the authenticated user's saved posts and comments (private to the account)', naming the resource and scope. It distinguishes from siblings by pointing to 'get_my_overview' for authored activity and clearly stating the lack of cross-user access, eliminating ambiguity.

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 when-to-use ('Get the authenticated user's saved posts/comments'), an alternative ('Use get_my_overview for your authored activity'), and when-not-to-use ('Do NOT use this for another user'). It even covers the auth prerequisite, offering complete guidance.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite readOnlyHint and openWorldHint annotations, the description adds meaningful context: it is read-only (consistent) and 'works anonymously', and reveals that long threads are truncated with 'load more' stubs. This goes beyond annotations and desribes the tool's behavior clearly.

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 compact, front-loaded with the main purpose, and each sentence adds value: purpose, sort options, read-only, truncation behavior, and alternative tools. No redundant text.

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?

Although no output schema is provided, the description summarizes what is returned (post header, threaded comments with author badges, score, body, nesting depth, limit) and explains truncation behavior. This is sufficient for an agent to understand the tool's capabilities and expected output.

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 already covers all parameters with 100% coverage, so baseline is 3. The description adds extra value by clarifying that post_id can include a t3_ prefix, and that limit may still result in truncation due to threading. This goes above the schema's basic descriptions.

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 explicitly states 'Get the comment thread for a post (by post id + subreddit)' and enumerates sort options. It distinguishes from sibling get_reddit_post by noting that tool is for 'just the post body, not the thread', ensuring clear 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?

Provides explicit guidance on when to use this tool (to fetch a comment thread) and when not (use get_reddit_post for post body). Also mentions get_more_comments for expanding truncated threads, giving a clear alternative path for further data.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description discloses that user credentials are required, that anonymous access may 403 or return empty, and that many subreddits expose flairs only to members. This adds meaningful behavioral context not present in the annotations.

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 and well-structured: it states the purpose, adds important auth/behavioral caveats, explains how to use the output, and points to the alternative tool. Every sentence earns its place with no 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 simple one-parameter list tool with no output schema, the description is complete: it explains what is returned, how to use it, when it may fail, and which sibling tool covers the related use case. The annotations and schema cover the remaining context.

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 fully documents the single parameter subreddit_name, including the r/ prefix guidance. The description does not add additional parameter-level meaning, 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 the tool lists a subreddit's selectable link flairs, including the exact returned fields (flair text + flair_id). It also distinguishes itself from the sibling get_subreddit_rules by explicitly directing users there for posting rules.

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 explains when to use this tool: to obtain flairs for create_post, and tells the user to pass the returned flair_id/flair_text to create_post. It also names get_subreddit_rules as the alternative for posting rules, providing clear usage context.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation covers safety, but the description adds further useful behavior: 'works anonymously', 'Read-only', and 'Returns the post only' — a scope constraint that proactively avoids confusion with nested comments. It also discloses the kind of content included (title, score, engagement analysis). Nothing contradicts annotations; it clearly adds context beyond the structured metadata.

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 whole description is two sentences that pack in the resource, return fields, behavioral boundaries, and alternatives, with zero filler. Information is front-loaded ('Get a single post') and every clause adds either purpose or usage guidance.

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 no output schema available, the description compensates by listing the return fields (title, author, content, score, upvote ratio, comment count, flairs/flags, engagement analysis). It provides input constraints, alternative routing, and clear exclusion details, making the tool self-contained for AI decision-making.

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% and both parameter descriptions already provide complete meaning (including 'Base36 post id', the t3_ prefix, and the r/ prefix rules). The description re-references 'subreddit + post id' but does not add extra semantics beyond what the schema already contains, 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 uses the specific verb 'Get' and identifies the exact resource ('a single post by subreddit + post id'), then enumerates the returned content. It explicitly distinguishes from sibling tools by naming get_post_comments for comments and browse_subreddit/get_top_posts for listing, making its 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?

Provides explicit when-to-use guidance and clear directives against misuse: 'use get_post_comments for its comment thread', 'Do NOT use this to list a subreddit's posts (use browse_subreddit / get_top_posts)', and 'do not use to find posts by keyword (use search_reddit)'. This fully steers the agent toward correct alternatives.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds meaningful context beyond the annotations: 'Read-only; works anonymously' and clarifies that it returns metadata about the community itself. It doesn't deeply cover edge cases or errors, but for a simple read-only metadata tool the behavioral expectations are well communicated.

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 deliver purpose, return content, usage boundaries, and alternatives with no filler. The description is front-loaded with the core action and richly informative without being bloated.

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?

Despite having no output schema, the description enumerates the main return fields and clearly scopes the tool's behavior. It also gives enough contextual boundaries to prevent misuse with other sibling tools, making it complete for a single-parameter read-only tool.

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 already fully describes the single parameter, including the r/ prefix convention and example. The description adds no additional parameter-level meaning, but with 100% 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 uses a specific verb and resource: 'Get a subreddit's profile' followed by a detailed list of returned fields (title, description, subscriber counts, creation date, flags, URLs). It also distinguishes itself from siblings by stating it returns community metadata and not posts or rules.

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 tells when to use this tool vs alternatives: use browse_subreddit/get_top_posts for posts, get_subreddit_rules for rules, and search_reddit with type='sr' for finding subreddits by topic. This is clear, actionable guidance with named sibling tools.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, and the description reinforces 'Read-only' while adding 'works anonymously'. It also discloses the return behavior (rules list or a note when none exist) and the practical consequence of avoiding auto-removal, which goes beyond what annotations provide.

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 sentences, each earning its place: purpose, read-only/anonymous, return behavior, usage context, and alternative tool. It's front-loaded with the key action and free of 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 one-parameter tool with no output schema, the description is complete: it explains what the tool returns, when to use it, that it's read-only and anonymous, and how it relates to create_post and get_post_flairs. No gaps remain.

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 fully describes the only parameter (subreddit_name, no r/ prefix, with example). Since schema coverage is 100%, the description doesn't need to add param-level detail; it stays at the tool-level purpose. 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 verb 'Get' and the resource 'a subreddit's posting rules', and even breaks down what each rule includes (name, scope, description). It also distinguishes itself from sibling tools by explicitly pointing to get_post_flairs for flairs, making it unambiguous.

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 gives explicit when-to-use guidance: 'Call this before create_post to check requirements and avoid auto-removal.' It also names the alternative tool for flairs, providing a clear decision context versus siblings.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description adds meaningful behavior: it is read-only, works anonymously, returns a page of posts with specific fields, and provides an 'after' cursor for pagination. It also notes the credential requirement when no subreddit is provided. No contradiction with annotations.

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 compact and front-loaded with the core action and scope, then adds return-format and sibling differentiation in just three sentences. Every sentence contributes value with no repetition of 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 moderately simple tool with no output schema, the description provides enough context: it names the returned fields, explains pagination via 'after', notes authentication behavior, and covers alternative tools. Annotations and full schema coverage support this, leaving no major operational 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 input schema covers all 4 parameters with descriptions, so the baseline is 3. The tool description adds minimal extra parameter meaning beyond restating that time_filter is a window and that omitting subreddit switches to home feed; it does not materially enrich schema semantics.

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 the top-scoring posts from a subreddit...'), defines the optional home-feed target, and distinguishes itself from browse_subreddit and search_reddit. It clearly scopes the tool to the 'top' sort and is not a tautology.

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 this is a shortcut for the 'top' sort and directs users to browse_subreddit for other sorts and search_reddit for keyword search. It also clarifies that omitting subreddit uses the authenticated home feed, giving clear when-to-use and when-not-to-use context.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description adds valuable behavioral context beyond the readOnlyHint and openWorldHint annotations: it explains the cached, time-varying nature of results and that it works anonymously. No contradiction with annotations.

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 focused sentences: the first states the purpose and behavior, the second gives alternative guidance. No filler, front-loaded and efficient.

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, read-only tool with no output schema, the description fully conveys what it returns (a list of subreddit names), its dynamic nature, and its constraints. It is complete 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?

With zero parameters, the description correctly notes 'no parameters,' which covers the empty schema. The baseline of 4 is appropriate since there is nothing to add semantically.

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?

Description clearly states the tool gets currently trending subreddits, using a specific verb and resource, and distinguishes itself from search_reddit by contrasting trend-based vs keyword-based retrieval.

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?

Explicitly states it works anonymously and is read-only, and provides a clear alternative ('use search_reddit with type='sr'') for keyword-based needs, making the when-to-use decision unambiguous.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only; works anonymously,' adding behavioral context beyond the structured annotations. It also discloses pagination behavior via the 'after' cursor and describes the returned fields, though it does not go deep into rate limits or edge cases.

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 three sentences with no filler. It front-loads the core purpose, then adds usage boundaries and return-value context, every sentence earning 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?

Despite lacking an output schema, the description lists the key returned fields and explains pagination with the 'after' cursor. It also covers usage context, safety, and operational details, making it complete enough for an agent to invoke the tool correctly without additional tools.

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 fully documents all five parameters. The description adds a high-level mention of sort and time filtering but does not provide meaningful extra semantics beyond the schema's own detailed parameter descriptions.

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 retrieves comments made by a specific user, names the supported sort and time options, and explicitly distinguishes itself from get_user_posts and get_post_comments. The verb, resource, and scope are all immediately identifiable.

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?

Explicit guidance is given: use get_user_posts for submissions, get_user_info for karma/profile stats, and get_post_comments for reading a single post's thread. It also states a clear 'do NOT use' condition, which helps an agent select correctly among many similar sibling tools.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds context: 'Read-only; works in anonymous mode' and 'Returns profile stats only', which reinforces the read-only nature and clarifies scope. No contradiction. Slight deduction because it doesn't mention rate limits or potential errors, but the annotation coverage is good.

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 compact, front-loaded with the core purpose, and every sentence adds value: what it returns, read-only nature, sibling tool differentiation, and limitation. No fluff or repetition.

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 one parameter, the description is complete. It covers purpose, scope, limitations, and alternatives. No output schema exists, but the description lists the return contents (karma, account age, status flags, activity analysis) sufficiently. The tool is simple enough that this is fully 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?

Schema description coverage is 100% and the single parameter 'username' is well-described with format example ('spez', not 'u/spez'). The description adds context about what the parameter represents (target user) and what it does not include (private fields). Baseline 3 for high coverage, +1 for the explicit format guidance.

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 purpose: 'Get a public profile for any Reddit user' with specific data points (karma, account age, status flags, activity analysis). It distinguishes from siblings by explicitly naming get_user_posts/get_user_comments for content and get_me for authenticated account.

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 when-to-use and when-not-to-use guidance: 'use get_user_posts / get_user_comments for their actual content' and 'Use get_me instead for your own authenticated account'. Also clarifies the limitation: 'do NOT expect private fields here'.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint, and the description reinforces this with 'Read-only' and 'works anonymously.' It also adds meaningful context by listing the returned post fields and describing the 'after' pagination cursor, which is not visible in annotations or the output schema.

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 compact, front-loaded with the core purpose, and every sentence earns its place by adding purpose, behavioral context, or usage alternatives. It avoids redundant restating of schema details and remains highly scannable.

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 five parameters and no output schema, the description provides a complete operational picture: what it returns, how paging works, its authentication posture, and how it fits among sibling tools. This is sufficient for an agent to select and invoke the tool correctly without further 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 schema description coverage is 100%, so every parameter is already documented in the schema itself. The tool description adds useful context around sort and pagination but does not need to compensate for missing schema detail; therefore, a 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 tool gets posts submitted by a specific user and identifies the resource and supported sort/time-filter capabilities. It also distinguishes itself from sibling tools like get_user_comments and get_user_info, making its purpose unambiguous.

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 guidance on when to use this tool versus alternatives: use get_user_comments for comments, get_user_info for profile stats, and search_reddit or browse_subreddit for subreddit searching. This direct exclusionary guidance is strong and actionable.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses mutation and non-idempotency, explicitly noting 'each call adds a new comment', which goes beyond the annotations. It also adds credential requirements, the thing-id format needed for parent identification, the return value, and a warning about spam detection—all valuable behavioral context beyond what annotations provide.

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 core purpose and each subsequent sentence carries meaningful operational or safety information. Despite being longer than minimal, there is no filler; every sentence earns its place by covering credentials, reply mechanics, alternatives, and a spam-detection warning.

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 mutating tool with no output schema, the description is unusually complete: it states the return value, explains parent-id formats for both posts and comments, gives the authentication requirement, and warns about rate limiting. This gives the agent enough context to select, invoke, and interpret the result 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?

Schema description coverage is 100%, so the schema already documents post_id and content thoroughly. The description reinforces the t3_/t1_ prefix semantics and the nesting behavior, but it does not add substantial new parameter-level details beyond what the input schema already states.

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 'Post a reply to an existing post or comment', using a specific verb and resource that clearly defines the action. It also distinguishes itself from siblings like create_post and edit_comment by explicitly mentioning top-level and nested replies and referencing edit_comment as the alternative for changing an existing reply.

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 explicitly says 'Use edit_comment to change a reply you already posted', giving a direct alternative. It also clarifies when to use this tool (for both top-level and nested replies) and warns about spam detection and REDDIT_SAFE_MODE, which helps the agent decide when and how to invoke it.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description states 'Read-only; works anonymously' which complements the readOnlyHint annotation by adding the anonymity detail — useful behavioral context, since the agent might otherwise assume auth is required to see different results. It also discloses the return shape ('page of results... plus an `after` cursor for paging') and the fact that results are paginated. The main deduction: the description doesn't explicitly call out rate limiting, but combined with annotations, this is a well-covered 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?

At ~120 words, every sentence serves a purpose. The first sentence establishes the core function, the second states the read-only anonymous nature, the third summarizes the return shape plus pagination, and the final sentence provides explicit alternatives with a decision rule. No fluff, no redundancy — a model example of tight, informative prose.

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 search tool with 7 params, 3 enums, no output schema, and no nested objects, this description covers everything an agent needs: what it searches, how to paginate (after cursor), what the response shape is, the read-only anonymous nature, and the explicit distinction from sibling tools. The tool is self-contained — an agent could confidently select and call it correctly based on this description alone.

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 required param 'query' is described), and the sort parameter's description adds substantial semantic guidance: 'Prefer 'relevance'... for finding posts about a topic. Use 'top'/'hot' only for what's currently popular...' — this goes beyond enumerating values to explain which to prefer when. The description makes the best use of enums explicit. Slight deduction: while the description mentions 'optionally scoped to one subreddit', it doesn't force the agent to think about auth/rate-limit implications of anonymous access.

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 'Search Reddit for posts — or subreddits/users via `type`' — a specific verb+resource+scope pairing that immediately distinguishes it from sibling tools like browse_subreddit, get_top_posts, and list-only feed tools. It explicitly states what object types are searched (posts, subreddits, users), the optional subreddit scoping, and the sorting/filtering dimensions, all in the first sentence. This leaves no ambiguity about what action the tool performs.

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 states when to use this tool versus alternatives: 'Use this to find content by keyword; use browse_subreddit / get_top_posts to list a known subreddit's feed instead.' This directly names sibling alternatives and explains the decision boundary (keyword search vs. browsing a known feed). The sort parameter description further refines when to use 'top'/'hot' vs 'relevance', which serves as usage guidance embedded in the schema.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description reinforces annotations (readOnlyHint=true/openWorld=false) by stating it is read-only and side-effect-free. Adds value by disclosing no API calls are made, it returns server version and local client state, and that a failed write-access check predicts failures of listed sibling tools. No annotation contradiction found.

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?

Eminently functional, front-loaded description. It is a bit long but every sentence adds a key fact; no padding. Organized into what-it-returns, when-to-use, and exclusions.

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?

No output schema, but the description states precisely the return values (server version, client init, OAuth presence, write configure). No sibling write tools to distinguish since it is a diagnostic. No nested input params. For a zero-param check tool, this is complete.

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?

No parameters exist, a baseline of 4 is given per rubric. Schema is empty but with 100% description coverage; no parameter documentation 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?

States a specific verb+resource: 'Health check for the Reddit MCP server.' Clear read-only diagnosis tool. Distinguishes from siblings by noting it inspects only local configuration and never contacts Reddit.

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?

Gives explicit when-to-use: 'Use this first to diagnose setup/authorization issues.' Explicitly excludes checking Reddit status or connectivity, and notes write tools will fail if write access is absent.

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