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

Annotations only say readOnly/non-destructive; the description adds the non-obvious fact that this call is unmetered and never consumes a credit, plus the 402 error semantics and the presence of a top-up URL in error responses. That is behavior an agent cannot get from structured fields.

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?

Front-loaded with the core purpose and the cost caveat, and most sentences earn their place by covering the 402 workflow. Slight redundancy between 'not metered' and 'never costs a credit' costs it a point.

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, the description names both return values (balance, usage totals) and supplies the error-handling context for 402. Nothing an agent needs to invoke or interpret this call 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?

Zero parameters, so there is nothing to mis-specify and the baseline is 4. The description correctly implies a no-argument call without adding noise about nonexistent inputs.

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 resource and outcome: returns the account's remaining credit balance and usage totals. Clearly distinguishable from every sibling, which are Reddit data-fetching tools, not account/billing introspection.

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 when-to-use guidance: call it before running something expensive, use it to check whether a planned batch fits the balance, and call it after a 402 to report remaining credit. It even explains what a 402 from another tool implies, which is the alternative signal an agent needs.

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 readOnly/openWorld annotations, the description discloses a non-obvious behavioral trait: the result is not always one-to-one with the request, and it explains the meta fields (listing_status, truncated, missing_fullnames) and which one to branch on. This is exactly the kind of partial-failure detail an agent cannot get from 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?

Front-loads the core behavior (bulk fetch in one call), then the usage cue, then the return shape and meta-branching, ending with a concrete example. Every sentence carries distinct information with no padding.

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, the description still names the returned fields (title, author, score, comment count, permalink) and the meta envelope, and it flags the caveat that responses may be partial. Nothing an agent needs to call and interpret this correctly 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% and the single parameter already documents the t3_ format and the 100 cap, so the schema carries the load. The description's inline example is mildly reinforcing but adds no syntax or constraint beyond what the schema 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?

States a specific verb+resource (bulk-fetch posts) with a clear scope constraint (by t3_ fullnames, up to 100) and explicitly contrasts it with a per-post request pattern. It is distinguishable from siblings like reddit_post or reddit_subreddit_posts because it is keyed on ids, not listings.

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?

Tells the agent to pass fullnames 'you already have from a search or listing to hydrate them', which gives clear context for when this tool applies. It implies the batching alternative to per-post calls but does not name a specific sibling (e.g. reddit_post) as the single-id fallback, so it stops short of explicit when-not 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 declare read-only, non-destructive, open-world reads, and the description adds rich behavioral context beyond that: the premium fan-out cost model, the best-effort nature (deleted or deeply-nested comments may be missed, meta.truncated flag), the pagination depth semantics of the opaque after cursor, and the possibility Reddit stops serving a listing early. This is above-and-beyond disclosure for a read 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?

Front-loads the core value proposition and the sibling differentiation well, but the body is a dense run-on with many clauses and an example tacked on the end. Every sentence carries information, yet the structure could be tightened into clearer sections without losing content.

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?

Complete for a 9-parameter premium search tool with no output schema: it describes the return payload fields (body, score, author, permalink, parent post), the pagination and truncation semantics, the cost model, and the alternate author-grouping mode. Nothing an agent needs to call it correctly 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%, so the baseline is 3, but the description adds meaning the schema cannot express at a glance: that limit sets parent POSTS expanded, not comments returned, and that after carries paging depth a hand-written fullname would lose. It also explains group_by='author' research mode and max_comments keeping top-scored comments, which clarifies intent behind the parameter names.

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 and resource ('returns the ACTUAL comments whose body matches your keyword'), and explicitly distinguishes itself from the sibling reddit_search_comments by explaining that the sibling returns parent posts while this fetches comment trees. An agent can pick between the two without opening either 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?

Clearly names the alternative (reddit_search_comments) and the condition that selects this tool ('so you get first-hand opinions and answers directly'). It also describes the pagination workflow with the after cursor. It stops short of naming when NOT to use this premium call or which sibling to prefer for author research, though group_by='author' is described.

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 non-destructive, but the description goes well beyond them: it enumerates the possible status values (new, triaged, shipped, declined), discloses the response text field, explains that updated_at only moves when the team acts, states the call is free, and documents the 404 condition when the id is not on this account.

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?

Front-loaded with the core action and tightly packed with useful detail, but the single long parenthetical-laden sentence is dense. Nothing is wasted, though the structure could be easier to scan.

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, the description carries the burden of explaining return values, and it does so by naming the status values, response text, and updated_at semantics, plus the error case. Nothing an agent needs to call it correctly 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% and the single id parameter is fully described in the schema, including the 'not a local draft id' caveat. The description restates the same sourcing information, so it adds little beyond what the schema already provides; 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?

States a specific verb (check the status) and a specific resource (a feedback report this account sent earlier), and identifies the source of the id via reddit_feedback_send. An agent can distinguish it from reddit_feedback_send and reddit_feedback_list without opening 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?

Clear context for when it applies: after sending a report, using the server id returned by the 'send' action. It does not explicitly name reddit_feedback_list as the alternative for enumerating reports, so there is no resolved when-to-use-vs-alternative routing.

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?

Goes well beyond the readOnly/destructive/openWorld annotations: states cost ('free per call, never metered'), the exact return shape, keyset paging semantics and why it is repeat/skip-safe, that a foreign cursor yields 400 (never an empty page), and that an empty account yields an empty list with 200, not an error.

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 key value proposition (recovering a lost id) is front-loaded and most sentences carry distinct payload, but the description is long and the return/paging mechanics could be tightened without loss.

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, yet the description supplies the return shape and paging contract in prose, plus the sibling-differentiation an agent needs. Nothing essential to a correct call 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% and the schema descriptions are unusually rich, so the description's 'filter by status or type, page with the cursor' adds little beyond what the schema already documents. Baseline 3 is correct when the schema does the heavy lifting.

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 and resource (list this account's SENT feedback reports, newest first, with status), and explicitly distinguishes itself from the sibling reddit_feedback_send action="list" (unsent local drafts). An agent can route without opening the 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?

Gives concrete when-to-use triggers (recover a lost id that was returned only once, answer 'did that report land', 'has the team looked'), states when to filter/paginate, and names the alternative tool plus the condition that selects it. Nothing is left to inference.

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 give readOnlyHint=false, destructiveHint=false, openWorldHint=true; the description adds substantial context beyond that: drafting is local and 'sends nothing, needs no confirmation', sending posts to POST /feedback, is free/not metered, and returns a server id checkable via reddit_feedback_get. It also discloses the auto-attach of the last failing call and auto-filled evidence fields.

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?

It is front-loaded with the core draft-then-send concept and organized into clear WHEN/FORMAT/REVIEW blocks, so it scans well. It runs long and some content (the four-bullet detail format) is duplicated from the schema, costing the top score.

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 7-parameter, multi-action, nested-object tool with no output schema, the description covers the full lifecycle: when to draft, the report format, how review/send/discard work, and what sending returns. Nothing an agent needs to invoke it correctly appears to be 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%, so the schema already documents every parameter and the enum values; the baseline would be 3. The description nonetheless adds meaning: the four labelled bullets for 'details', the fact that only user-named ids may be sent, and the auto-fill behaviour for omitted evidence fields. It reinforces rather than merely repeats 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 states a specific verb and resource ('Report a product problem or gap in redditapis.com to its team') and distinguishes itself from its siblings (reddit_feedback_list, reddit_feedback_get) by centering the draft/send workflow. An agent can tell what this tool is for without opening the 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 'WHEN TO DRAFT' block gives explicit trigger conditions (failed call that is not 401/402/429, uncovered request, wrong/empty field, user frustration), an explicit exclusion list, and a cadence rule ('one draft per distinct issue, never twice'). The REVIEW block names the alternatives (list/send/discard) and the condition that selects each.

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 mark this read-only and open-world, but the description adds substantial behavioral context beyond them: the session/cookie auth requirement, why unauthenticated calls 400 rather than degrade, cursor instability across retries from truncated listings, and the listing_status semantics (complete/truncated/unknown) with a rule against reporting partial data as final.

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?

Front-loaded with the tool's purpose and its uniqueness before prerequisites and caveats. It is on the long side, but nearly every sentence carries non-obvious operational information, so little is wasted.

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, yet the description covers return shape parity with reddit_subreddit_posts, pagination behavior, listing completeness reporting, and the auth prerequisite. Nothing an agent needs to invoke or interpret it correctly 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%, so the baseline is 3; the description still earns credit by warning that the opaque `after` cursor must be passed back exactly (hand-written fullnames lose paging depth) and providing a concrete invocation example (sort='best' limit=25).

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?

Specific verb+resource (read your own Reddit home feed) with immediate scope clarification ('the front page your subscriptions produce'). It explicitly distinguishes itself from sibling read tools that use a shared account pool, so an agent can tell it apart without opening the 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?

States the exact precondition (POST /api/reddit/login on the REST API first, passing reddit_session and loid) and the failure mode if skipped (400, deliberately). It also names the alternative for public community feeds, reddit_subreddit_posts, removing all inference.

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 declare create semantics (readOnlyHint=false, openWorldHint=true, destructiveHint=false), so the description carries the load and does so richly: forward-looking only with no backfill, baseline_item_id as the start point, slot/entitlement accounting, and a full catalog of failure codes with HTTP statuses (402/501/400). It also states the success return value includes the monitor `id`.

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 size is broadly justified by 17 parameters and complex entitlement rules, and the core purpose is front-loaded. However, the dense run-on error-code chain and repeated plan/sitewide caveats make it a wall of text that could be broken into a structured list.

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, so the description must cover returns — and it does by naming the created monitor with its `id` plus the full error surface. Combined with the annotations and the exhaustive schema, an agent has everything needed to invoke this 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 the baseline is 3 and the schema already documents all 17 parameters in depth. The description adds cross-parameter meaning beyond the schema — the q/subreddit anchoring rule, the webhook_ids default-vs-restrict behavior, and slot counting semantics — though much of the per-parameter detail is duplicated in schema 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?

States a specific verb and resource ('Create a new Reddit monitor') plus the watched surface (subreddits or all of Reddit) and match kinds (posts/comments via `kind`). It explicitly routes the agent to sibling tools (reddit_monitor_webhook_create, reddit_monitor_list), so it is distinguishable without opening another 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?

Gives explicit conditions: omit `subreddit` and set `q` for a sitewide keyword monitor, pass `webhook_ids` to target specific webhooks, omit it for the all-webhooks default. It also spells out when a plan is required, when the free entitlement suffices, and requires a free monitor slot before calling. Alternatives and prerequisites are fully named.

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 cover the read-only/open-world safety profile, and the description adds substantial behavior beyond that: the semantics of 'dead' vs 'suppressed' (with both suppressed reasons and the note that stale_item is not a fault and cannot be recovered by retry), the deterministic non-ML nature of the enrichment fields, and the pagination contract. This is real disclosure the annotations do not 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?

Front-loads the core definition and keeps every sentence informational, but the enrichment paragraph is dense and slightly redundant ('not a model's confidence' and 'NONE of them is a machine-learning or LLM call' restate the same point). Efficient for the amount of information conveyed, though not maximally tight.

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?

There is no output schema, so the description carries the full burden of describing return values, and it does so by documenting the payload.items[].enrichment shape (relevance.score, sentiment.polarity/label, intent.tag) alongside pagination and status semantics. Nothing an agent needs to call and interpret this correctly 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%, so the baseline is 3, but the description adds meaning on top: it re-emphasizes the id-omission aggregation rule and expands thestatus semantics (retrying cannot recover a stale_item, no plan limit was involved) beyond what the schema states. The enrichment detail is output-oriented rather than parameter-oriented, so it does not push this higher.

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 resource and scope ('the actual Reddit posts a monitor's webhook has received (or attempted), newest first') and explicitly distinguishes its output from 'how many', naming reddit_monitor_health as the counts-oriented sibling. An agent can route between the two without reading 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?

Gives explicit when-to-use framing ('what did I actually get sent' vs. counts) and names the alternative tool by name, plus states the aggregation behavior when id is omitted. The conditions that select this tool over its sibling are spelled out rather than inferred.

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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds deep operational context beyond that: stale withhold behavior, what complete does and does not establish, tri-state null semantics, and the fact that a never-polled feed writes nothing to the poll log. It stops short of describing output shape or pagination, but the behavioral disclosures are unusually 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 definition is a dense wall of capitalized warnings and nested caveats that repeatedly restate the same exclusion (three separate 'do not report healthy on unknown/partial/live' variants). The field taxonomy is useful but the prose is roughly 5-10x the necessary length for a single-parameter read tool, and front-loading is sacrificed to exhaustiveness.

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 health-check tool with one parameter and no output schema, the description carries the full burden of interpreting the returned fields, and it does so completely: every status enum is defined (complete/degraded/partial/unknown, live/degraded/unknown), every counter's meaning is explained, and the tri-state null semantics are explicitly stated.

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?

Only one parameter (id), schema coverage is 100%, and the schema already points at reddit_monitor_add and reddit_monitor_list as sources. The description adds no parameter-level detail, so baseline sits at 4 for a single-parameter tool with fully documented 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?

Opens with a specific verb+resource and a precise scope: per-monitor health covering active state, cadence, last match, and 24h delivery counts. The taxonomy of returned fields (coverage_24h, stream_liveness, cadence, gaps) is laid out exhausively, which distinguishes it sharply from reddit_monitor_list and reddit_monitor_deliveries without opening those 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?

Gives explicit when/when-not guidance throughout: do not report healthy on unknown/partial status, do not report healthy unless stream_liveness.status is live, read stream_liveness first, read freshness_reading before quoting. It also explains the diagnostic hierarchy (stream_liveness before coverage_24h) and names the fix path (set cadence_s).

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 this a safe read, and the description adds substantial non-derivable behavior: a lapsed subscription yields an empty/paused list rather than an error, and the null semantics of webhook_ids (default = deliver to every active webhook) are spelled out with an explicit warning not to misread it as 'no destination'.

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 core purpose is front-loaded and every sentence carries information, but the capitalized warning about webhook_ids is longer and more emphatic than strictly needed, and the return-shape detail arrives before the alternative-tool pointer.

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, the description carries the full burden of describing the return payload (per-monitor filter/active state/cadence plus the {used, total, tier} slots object) and it does so, alongside the caveat an agent would otherwise get wrong about null delivery targets.

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?

Zero parameters, so there is no parameter semantics to clarify — baseline 4 applies. The description instead spends its budget on the shape and meaning of returned fields, which is appropriate for a no-arg call.

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 and resource ('List every monitor on the caller's account') and enumerates the returned fields (filter, active state, cadence, slots), which distinguishes it from siblings like reddit_monitor_health and reddit_monitor_deliveries without opening 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?

Explains the access condition (reading your own list never requires an active plan), which removes a real gate for the agent, and routes the agent to reddit_monitor_deliveries when it needs resolved delivery targets. It lacks an explicit when-not-to-use statement, but the context provided is concrete.

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?

Goes well beyond the destructiveHint/readOnlyHint annotations by disclosing that there is no undo, that matching stops immediately, that the slot is freed for reuse, that the monitor disappears from reddit_monitor_list, that past deliveries are NOT erased and remain queryable forever, and the 404 monitor_not_found error condition. This is exactly the kind of side-effect and downstream-state detail a destructive tool needs.

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?

Front-loaded with the single-sentence action ('Delete a monitor'), followed by consequence sentences that each carry distinct information (undo, slot, list visibility, data retention, error case). No filler 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 one-parameter destructive mutation with no output schema, the description covers reversibility, immediate effects, downstream data retention, cross-tool visibility, and the error path. Nothing an agent needs to invoke it correctly or predict its side effects 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 id parameter is already documented (source: add response or list). The description adds value by specifying the failure semantics of the id ('404 monitor_not_found if the id does not exist or is not yours'), clarifying ownership scoping that the schema does not convey.

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 ('Delete a monitor') with a clearly named resource and immediately distinguishes its effect from siblings by calling out reddit_monitor_list (slot disappears) and reddit_monitor_deliveries (past data persists). An agent can tell this apart from reddit_monitor_update or reddit_monitor_add without opening 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 richly describes the consequences of deleting but never states when to choose this over an alternative such as reddit_monitor_update (e.g. to pause rather than remove). Usage is implied by the delete semantics and the 'no undo' framing, so it lands at minimum-viable-plus rather than explicit 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 only declare readOnlyHint=false, destructiveHint=false and openWorldHint=true; the description goes well beyond them by disclosing the replace-not-merge semantics (whole filter and webhook_ids replaced wholesale), what an empty array does (clears to 'every active webhook'), and the exact failure modes (404 monitor_not_found, 400 webhook_not_found). 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 mutation list is front-loaded, then the critical replace-semantics caveat, then error codes. Dense but every sentence carries distinct information; only slight redundancy in restating the replace rule for both filters and webhook_ids.

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 18 parameters, no output schema and no nested objects, the description supplies exactly what's missing: replacement semantics, defaults on omission, and the two error codes. Nothing an agent needs to invoke this update correctly is absent.

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 per-field docs already carry the baseline. The description still adds update-specific meaning the schema alone doesn't foreground: that any filter field replaces the whole filter, that subreddit AND kind must be resupplied, and that omitting webhook_ids leaves targeting untouched. This is genuine added value over the field docs.

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?

Opens with a specific verb+resource ('Update an existing monitor') and then enumerates every mutation axis (active, cadence_s, kind, filter, webhook_ids) with the field name that controls each. An agent can distinguish this from reddit_monitor_add/create and reddit_monitor_remove purely from the first sentence.

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 tells the agent when to pass filter fields versus not ('Omit all filter/webhook_ids fields to change only active/cadence_s') and warns that omitting `kind` reverts to posts-only. It does not explicitly route to a sibling for the create/delete cases, but the update-only conditions are clear.

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 declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds crucial behavior: the signing secret is shown once and never again, the URL is re-validated with a fresh DNS check at every delivery, and an active plan is required. 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?

Four sentences, each carrying distinct information: purpose, prerequisite, secret handling, and validation. Front-loaded with the core action and no wasted words.

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, so the description correctly explains the critical return value (the one-time secret) and the operational constraints (plan required, HTTPS only, re-validation). Together with the rich schema, an agent has everything needed to call it safely.

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 parameters are well described in the schema. The description adds one URL-related behavior—HTTPS only and re-validation at every delivery—which meaningfully supplements the schema's creation-time 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?

States a specific verb ('Register') and resource ('delivery target for monitors'), and distinguishes from sibling reddit_monitor_webhook_list by noting the secret is never returned there. An agent can identify it as the webhook-creation tool without opening the 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?

Adds a clear prerequisite—an active monitoring plan—and explains why (a webhook with no plan could never receive anything). It doesn't name alternative tools like webhook_test or delete, but the context for when this tool applies is explicit.

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 destructiveHint=true already covering the safety profile, the description adds substantial context: the deletion is permanent and irreversible, it does NOT cascade to monitors (which will fail to deliver until repointed), and it returns 404 webhook_not_found for nonexistent or foreign ids. This is exactly the non-obvious behavior an agent needs.

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 tight sentences, front-loaded with the action, then the side-effect warning, then the error condition. Every sentence carries unique information with no 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?

For a single-parameter destructive tool with no output schema, the description covers the mutation's permanence, its non-cascading effect on dependent monitors, and the failure mode. Nothing essential for correct invocation 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% and the schema already documents the id's origin, so baseline is 3; the description adds value by disclosing the 404-not-found condition when the id does not exist or is not owned by the caller, which is meaningful semantic detail about the id parameter.

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 ("Permanently delete a webhook"), making the operation unmistakable. It does not explicitly contrast with the close siblings reddit_monitor_webhook_create/list/test, so it falls just 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?

It explains the operational consequences of deleting but gives no when-to-use guidance, no prerequisites, and no explicit routing to alternatives such as repointing a monitor or using the webhook test/list tools. The agent must infer usage from context alone.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description still adds genuinely useful behavioral context beyond the annotations: the secret is never returned and is only shown once at creation, which prevents an agent from hunting for it or expecting it in the response.

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 short sentences with no filler; the primary behavior (list all webhooks for the caller) is front-loaded and the caveat about the secret follows immediately. Every clause 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 zero-parameter, read-only listing tool with no output schema, the description covers what an agent must know before calling: scope (caller's account) and the one surprising field behavior (no secret returned). Return-shape details like pagination or webhook object fields are unaddressed, which is a minor gap for a simple list operation.

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, so there is nothing to disambiguate and the baseline is 4. No parameter-level information is needed or missing.

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') plus resource ('every webhook registered on the caller's account'), so it is immediately clear what the tool returns. It names reddit_monitor_webhook_create only to explain where the signing secret comes from, not to route the agent between list/create/delete/test siblings, so sibling differentiation is implied rather than explicit.

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?

Usage is only implied: an agent can infer 'call this to see existing webhooks,' but there is no statement of when to prefer this over reddit_monitor_webhook_test or reddit_monitor_deliveries, and no prerequisites or conditions are given. It notes the secret is available at creation time, which is useful context but not routing 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 only cover the safety profile (readOnly=false, destructive=false, openWorld=true); the description adds the rate limit (10/min), the payload-formatting behavior driven by the webhook's kind, the rich failure shape (`reason`, `status`, `hint`, `detail`), and two specific error outcomes (404 webhook_not_found, webhook_url_rejected). It even explains why `hint` should be surfaced over `reason`.

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?

Purpose is front-loaded, followed by payload behavior and then failure semantics in a logical order. It is dense and long, but nearly every sentence carries actionable information, so little is wasted.

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, the description takes on the burden of documenting return values and does so thoroughly: success formatting plus the full failure contract (reason/status/hint/detail and named error codes). An agent has everything needed to call and interpret this 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?

Schema coverage is 100% and the schema already documents the `id` parameter including where it comes from (create or list), so the description adds essentially no extra meaning beyond what the schema 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?

The first clause states a specific verb and resource ('Send a one-off test delivery to a registered webhook') and its purpose ('confirm it's wired up correctly'), which cleanly separates it from siblings like reddit_monitor_webhook_create and reddit_monitor_webhook_delete.

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 clear context for use: run it before waiting for a real match to verify wiring. It doesn't explicitly name an alternative or a when-not condition, but the pre-flight framing makes the intended usage 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 destructiveHint=false, so safety is covered. The description adds behavioral context about return fields and the exact id format (base-36, no 't3_' prefix), which goes beyond the annotations and helps the agent know what 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?

The description is three sentences, front-loaded with the core purpose, then return details, then usage example. Every sentence earns its place 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 simple single-read tool with one parameter and no output schema, the description is fully complete. It explains what the tool returns, when to use it, and the exact id format, making it self-sufficient 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?

The schema covers 100% of the parameter details (base-36 id, no prefix, required). The description repeats this information and adds an example, but does not meaningfully extend beyond what the schema already provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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 specific verb 'fetch' and resource 'a single Reddit post by its id', and lists the returned fields. It distinguishes itself from siblings by specifying 'single post' and noting the id input, which separates it from subreddit listings and searches.

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 'Use when you already have a post id and want its details', providing clear context for when to use this tool. It does not mention when not to use it or alternative tools, but the usage condition is specific and actionable enough.

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 destructiveHint=false, establishing the safety profile. The description augments this by disclosing the return format (post plus threaded comments with author, body, score, replies) and pagination via an 'after' cursor. It does not discuss rate limits or auth, but the provided context goes beyond annotation basics.

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, front-loaded with the core purpose, followed by return details and usage context. No filler or redundancy; every sentence 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 single-parameter read-only tool with no output schema, the description covers what it returns, the pagination cursor, and the proper triggering context. It is self-sufficient for an agent to select and invoke it 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% since 'permalink' has a clear description with an example. The description additionally tells the agent to 'Pass the post's permalink from a prior result,' which adds provenance guidance beyond the schema's static definition.

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 ('Fetch a single post and its comment tree by permalink') with specific resource and scope. It distinguishes itself from sibling tools like 'reddit_post' or 'reddit_search_comments' by specifying it returns the full comment tree, not just the post or search results.

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 context for when to use the tool: 'Use after finding a post via search/listing to read the full discussion.' It implies a workflow but does not explicitly state when not to use it or mention alternative tools, so it falls short of the full 5.

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 destructiveHint=false, so safety is covered. The description goes well beyond them: it discloses the two-call mechanism (post fetch + one page of author submitted listing), names the returned fields (verdict, reason, confident flag), defines the verdict enum, warns it deliberately never reports the cause of invisibility, and states the billing ($0.004 dual read). It does not discuss rate limits or failure/timeout behavior, which keeps it from a 5.

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?

Front-loads the motivating question, then the methodology, then the return shape and caveats. Six dense sentences, no filler, every sentence 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 one-param tool with no output schema, the description carries the return-value burden it would otherwise lack: it names each returned field and explains the undecidable verdict and the deliberate omission of a cause. Nothing an agent needs to interpret results or decide to call it 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?

Only one parameter and schema coverage is 100%, so the schema already documents the base36 id and t3_ prefix handling. The description adds no id-format detail, but with a single fully-documented parameter the baseline is 4; the lack of extra param context is not a meaningful gap here.

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, unusual purpose (determine post visibility by cross-checking the post against the author's submitted listing) and immediately distinguishes itself from the sibling reddit_by_id by explaining why fetching the post alone does not answer the question. An agent can tell exactly what this tool is for without opening the 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?

Explicitly frames the question it answers and why the obvious alternative (fetch by id) is insufficient, plus states what the result values mean and that undecidable is a legitimate outcome. The only mild gap is not naming which sibling to use for the two underlying reads, but the routing logic is otherwise complete.

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 destructiveHint=false, so safety is covered. The description adds a non-obvious behavioral trait that the schema alone doesn't surface: filters are applied to the returned page rather than server-side, which is why a `meta` object with page-completeness counts is returned, and why you must paginate with `after` to filter more. That pre-empts a real misinterpretation of filtered results.

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?

Front-loaded with purpose, scope, and return shape, then usage, then the filtering caveat, then a compact example. Dense but every clause earns its place; the filtering/meta explanation is the only part that runs long, and it is warranted.

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, the description compensates by naming returned fields, the cursor, and the `meta`/page-completeness concept behind filtered results. For a 19-parameter read tool on an open-world source, that is sufficient for an agent to call it and interpret the response 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 carries full parameter meaning (enums, ranges, filter semantics, cursor guidance). The description only summarizes the filter families (min/max score, comment count, media type, post flags, re-sort), adding no syntax or default detail beyond what the schema provides. 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?

States a specific verb and resource ('Search Reddit posts') and immediately disambiguates scope ('across all of Reddit or within one subreddit'). It also enumerates what the result contains (author, score, comments, permalink, after cursor), letting an agent distinguish it from reddit_search_comments or reddit_search_communities without opening either 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?

Gives concrete use cases ('topic/keyword research, brand monitoring, or finding discussions') and explains the scope selector ('Scope to a community with `subreddit`'). It stops short of naming the sibling search tools (comments, media, communities) as alternatives, so the when-not-to-use routing is left implicit.

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 cover safety (readOnly, non-destructive, openWorld); the description adds the crucial behavioral fact that Reddit does not expose which comment matched or its text, so the payload is posts rather than comment bodies. That is non-obvious return-shape behavior an agent would otherwise get wrong.

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?

Front-loaded with the surprising behavior first, then usage, then routing, then example. Slightly redundant in restating the posts-not-comments point twice ('returns the PARENT POSTS' and 'this returns posts, not comment bodies'), but each block still 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?

With no output schema, the description must convey the return shape, and it does (post title, selftext, score, comment count). Combined with the routing to reddit_deep_comment_search, an agent has everything needed to call and interpret 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?

Schema description coverage is 100%, including detailed semantics for t, sort, after, and limit, so the schema carries the parameter burden. The description only adds a usage example (q='best mechanical keyboard' sort='top'), which is marginal 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?

States a specific verb+resource (search Reddit by comment text) and immediately disambiguates the counterintuitive semantics: results are parent posts, not comments. It names both related siblings (reddit_search via 'plain post-title search', reddit_deep_comment_search) so an agent can distinguish it without opening other 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?

Gives an explicit use case ('surface threads where a topic comes up in the replies that plain post-title search would miss') and an explicit alternative for the adjacent need ('For the actual comment bodies, use reddit_deep_comment_search'). This is exactly the when/when-not/alternative structure.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds the return payload shape (title, subscriber count, description, NSFW flag), but says nothing about rate limits, auth requirements, or the truncation/pagination caveats that the schema's `after` param carries.

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 short sentences, front-loaded with purpose, then return shape, then usage, then a one-line example. No sentence is redundant and nothing is buried.

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, the description usefully enumerates the returned fields, and the safety profile is covered by annotations while pagination/truncation behavior lives in the schema. It does not mention the `limit`/paging model at all, which is the one detail an agent might want summarized in prose.

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 four parameters are already documented in detail, including the enum for `nsfw` and the extensive `after` cursor semantics. The description only adds an illustrative q value, 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?

States a specific verb and resource ('Search for subreddits (communities) by name or topic') and disambiguates it from post-oriented siblings by naming the returned fields and positioning it as a discovery step before listing or searching posts. The example query makes the operation concrete.

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 clear situational guidance ('Use to discover where a topic is discussed before listing or searching its posts') that tells the agent when this tool is the right entry point versus post search. It stops short of naming explicit alternatives or stating when NOT to use it, so it is clear context rather than full routing logic.

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 readOnly, openWorld, and non-destructive, so safety is covered. The description adds the return shape (media URL/type, author, score, post url), useful since there is no output schema, but says nothing about auth or rate limits.

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 short sentences, front-loaded with purpose, followed by a param hint and an example. Efficient with no filler, though the example could be slightly more representative.

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, the description helpfully enumerates the returned fields, and schema coverage handles all input nuance. Given annotations cover safety, the description is complete enough, missing only cross-tool routing guidance.

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 seven parameters, including the rich `after` and `t` guidance, are already documented in the schema. The description only restates `kind` usage, adding no meaning beyond structured data. 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?

States a specific verb (search) plus resource (Reddit posts) and scope (filtered to media), so an agent can distinguish it from a generic `reddit_search`. It doesn't explicitly name the sibling it is not, but the media-only scope is clear enough.

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 a concrete invocation example (q='aurora borealis' kind='image') and hints to use `kind` to narrow, which implies when to use it. However, it never states when to prefer this over `reddit_search` or `reddit_subreddit_posts`, leaving that routing to inference.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds the return shape (username, karma, account age), which is useful given there is no output schema, but it says nothing about pagination, rate limits or result completeness — behavior that only lives in the `after` schema text, not the description.

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 short sentences, zero padding, and the core purpose plus return shape are front-loaded ahead of the usage hint and example.

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 endpoint with full annotation coverage and a fully documented schema, the description supplies purpose, return fields and usage context. Only the pagination/truncation caveats expected of a search tool are absent from the description (they live in the schema instead).

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 q, nsfw, after and limit in depth (including Reddit search syntax and cursor semantics). The description only adds a trivial example (q='spez') and 'by name or keyword', 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?

States a specific verb and resource ('Search for Reddit users by name or keyword') and names the returned fields, which cleanly separates it from generic siblings like reddit_search, reddit_search_comments and reddit_search_communities. An agent can tell what this returns without opening the 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?

Gives concrete when-to-use guidance ('find a person's handle before fetching their profile or comments'), implicitly routing to reddit_user_profile / reddit_user_comments. It does not explicitly name those alternatives or state when NOT to use it, so it falls just short of the top band.

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 mark this as read-only and non-destructive. The description adds context by specifying it returns public metadata and lists the fields, which goes beyond the annotations. It does not contradict them.

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, front-loaded with the action, and each sentence contributes value: purpose, return fields, and usage guidance. 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 simple read-only metadata tool with one well-documented parameter, the description fully covers purpose, usage, and return values. The lack of an output schema is compensated by listing the returned fields.

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 parameter is fully described in the schema (e.g., 'WITHOUT the r/ prefix'). The description adds an example ('name='python'') that reinforces this, but provides no new semantic information.

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: 'Fetch a subreddit's public metadata by name.' It clearly distinguishes this from sibling tools that deal with posts, comments, or searches, and it enumerates the exact fields returned.

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 context: 'Use it to size or vet a community before listing or searching its posts.' This indicates when to use the tool, though it does not explicitly name alternative tools or state when not to use 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?

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false), but the description adds real behavioral value: it enumerates returned fields and flags the streaming/polling model with an `after` cursor, which the annotations do not convey. Some nuance (truncation semantics) lives in the schema rather than here, keeping it short of a 5.

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 tight sentences, front-loaded with the core purpose and scope before the return details and the example. No filler and nothing redundant.

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, the description correctly enumerates the returned fields (body, author, score, subreddit, parent link, timestamp, cursor) and the polling model, so an agent knows what it gets back. The main omitted detail is rate-limit/pagination-truncation guidance, which is instead delegated to the schema's `after` description.

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 both `name` and `after` are already documented in depth in the schema itself. The description only adds an example value ('name=python') and mentions the `after` cursor, so it does not meaningfully exceed the schema baseline.

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 ('Stream'), resource ('NEWEST comments'), and scope ('across an entire subreddit'), then explicitly distinguishes itself from the sibling case ('not one post's thread'). It also names the underlying feed (/r/<name>/comments), so an agent can route correctly without opening the 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?

Gives clear usage context ('Poll it to catch new comments in a community as they are posted') and excludes the single-post case, which implicitly routes to reddit_post_comments. It stops short of naming alternative sibling tools or stating when a different tool (e.g. reddit_search_comments) is preferable.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by naming the underlying endpoint (/about/moderators) and detailing the return fields (name, id, mod_permissions, etc.), including the meaning of 'added'.

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: two sentences and an example. It front-loads the main purpose and each sentence adds value — endpoint, return structure, usage, and example. No wasted words.

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 covers the purpose, usage context, return format, and parameter example. The schema and annotations fill in the remaining safety and parameter details, making it 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 input schema already fully describes the 'name' parameter (required, no r/ prefix, path parameter). The description's example 'name='python'' reinforces the format but does not add new semantic information 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 clearly states the action ('Fetch a subreddit's moderator team') and the specific resource (subreddit by name). It explicitly distinguishes this tool from siblings like reddit_subreddit_about or reddit_subreddit_rules by focusing on moderator team data.

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 a clear use case: 'Use it to see who moderates a community.' However, it does not explicitly mention alternatives or when not to use it, which would have made the guidance more complete.

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 cover readOnly/openWorld, but the description adds substantial non-obvious behavior: the `listing_status` semantics (complete/truncated/unknown) with explicit instructions not to report unknown as end-of-data, and pagination cursor behavior. This is exactly the kind of context annotations can't 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?

Front-loaded with the core purpose, then structured into purpose, return-value/status explanation, usage guidance, and an example. Zero filler despite covering a lot of ground.

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 no output schema and complex pagination/status semantics, the description is complete: it explains the return fields, the status meanings, and the correct action on incomplete data. An agent has everything needed to call it 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 already 100%, so the schema documents all params. The description adds an example (subreddit='programming' sort='top' t='week') and reiterates the cursor's opaque nature, giving slightly more than the schema alone—marginal but useful reinforcement.

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 (list) and resource (posts in a subreddit) and scopes it via sort order. It's clearly distinct from siblings like reddit_subreddit_top, reddit_subreddit_comments, and reddit_search, and even provides an example call.

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 clear usage context: read a community's feed with various sorts, and explicit guidance to 'widen across sorts, timeframes or search' when data is incomplete, which routes to alternative strategies. It doesn't name specific sibling tools as alternatives, but the condition to switch is spelled out.

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 destructiveHint=false, and the description aligns with these. It adds valuable context about the return structure (rules and site_rules lists) and the data source (/r/<name>/about/rules), going beyond 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 two sentences plus an example, front-loaded with the main purpose. Every sentence contributes: purpose, return details, use case, and example. No redundancy or wasted words.

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, the description thoroughly explains return values (rules list with specific fields and site_rules list). It also includes usage context and an example, making the tool fully understood for a simple read-only fetch.

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 a clear description for the 'name' parameter. The tool description reinforces the format (WITHOUT r/ prefix) and provides an example (name='python'), adding practical clarity 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 clearly states 'Fetch a subreddit's posting rules by name' with a specific verb and resource. It distinguishes from sibling tools like reddit_subreddit_about and reddit_subreddit_moderators by focusing on posting rules, not general info or moderators.

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 a clear use context: 'Use it to check a community's rules before posting or commenting.' It doesn't mention when not to use or alternative tools, but the primary use case is explicitly stated.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return shape (subreddits list with name, title, subscriber count, description, type, NSFW flag) and the presence of an `after` paging cursor — details not present in any structured field, since there is no 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?

Three tight sentences, front-loaded with the browse scope, then return shape, then the disambiguating alternative. No filler and no repetition of the schema's pagination essay.

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, the description carries the return-value burden and does so by enumerating the returned fields and the paging cursor. Combined with annotations covering safety and a schema that exhaustively documents both parameters, an agent has everything needed to call this 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% and the `after` field's schema text is unusually rich (cursor opacity, truncation semantics, listing_status handling), so the schema does the heavy lifting. The description only restates that an `after` cursor exists for paging, adding no syntax or format detail beyond the schema — the baseline 3 for fully documented parameters.

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 (Browse) and resource (Reddit's default front-page set of subreddits) with a clear scope qualifier ('default front-page set, no keyword needed'). It also names the sibling it is not — reddit_search_communities — so an agent can route between them without opening either 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?

Explicitly gives the selection rule against reddit_search_communities ('use reddit_search_communities instead to SEARCH communities by keyword'). It does not, however, distinguish this tool from the closely related reddit_subreddits_popular and reddit_subreddits_new siblings, which an agent could easily confuse.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds value beyond that by enumerating the returned `subreddits` fields (name, title, subscriber count, description, type, NSFW flag) and the `after` paging cursor, giving the agent useful output-shape 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?

Three sentences, each earning its place: purpose/scope front-loaded, then return contents, then the search-vs-browse distinction. No redundancy 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?

With no output schema, the description correctly carries the return-value burden by naming the fields and the paging cursor. Combined with the rich schema and annotations, an agent has everything needed to select and invoke the 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?

Schema description coverage is 100% and both parameters are documented in depth there (the cursor semantics and the 1-100 limit clamp). The description adds nothing parameter-specific beyond what the schema already provides, 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?

States a specific verb and resource ('Browse the newest subreddits, the communities most recently created') and contrasts itself against the keyword-search sibling by name. An agent can distinguish it from search and browse-by-recency alternatives without opening the 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?

Explicitly says 'no keyword needed' and routes to reddit_search_communities for keyword search, giving a clear when-to-use condition and alternative. It does not address the closely related browsing siblings (reddit_subreddits_popular, reddit_subreddits_default), so the routing guidance is good but not exhaustive.

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, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: it names the returned fields and the `after` cursor for paging. It omits the partial-data/listing_status caveat that the schema carries, so it is strong but not exhaustive.

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, front-loaded with purpose and scope, then return shape, then the disambiguation instruction. No filler and nothing redundant with the schema.

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?

Read-only browse tool with zero required params, full schema coverage, and no output schema — so the description's own summary of the return payload and paging cursor fills the remaining gap. Nothing an agent needs to call it correctly 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 explains `after` (including the cursor-stability warning and listing_status semantics) and `limit` thoroughly. The description only echoes "an `after` cursor for paging" and adds no format or usage detail beyond it — baseline 3 is correct when the schema does all the work.

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?

Specific verb+resource ("Browse the most-subscribed, trending subreddits"), plus the scope qualifier "no keyword needed" and an explicit contrast with reddit_search_communities. An agent can distinguish this popularity-browse tool from the keyword-search sibling without opening either 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?

States the selection condition clearly: use this to browse by popularity, use reddit_search_communities to search by keyword. It does not, however, distinguish itself from the other listing siblings (reddit_subreddits_new, reddit_subreddits_default, reddit_subreddit_top), which an agent choosing among browse endpoints would also need.

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 establish the safe read-only, open-world profile, so the bar is lower. The description adds valuable return-shape information (score, author, comments, permalink) and notes the `after` cursor, which is useful since no output schema exists. It does not itself carry the pagination/truncation caveats, but those are thoroughly covered in the schema's `after` description.

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 short sentences, front-loaded with the operation and scope, followed by the return shape and a concrete example. The second sentence is mildly redundant with the first but does sharpen what 'TOP' means; overall there is very little 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 low-complexity filtered-listing tool with full schema coverage and annotations, the description covers purpose, scope, return fields, and an example. The only gap is sibling differentiation against reddit_subreddit_posts, which an agent would have to resolve from names 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%, so baseline is 3: name, t, after, and limit are all documented in the schema with formats, ranges, and cursor semantics. The description's inline example (name='science', t='month') reinforces the calling convention but adds no semantics beyond what the 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?

Names a specific verb (get) and resource (top posts of a subreddit) and defines the scope as the highest-scoring posts in a time window, which is meaningfully different from a generic listing. It stops short of naming the sibling it competes with (reddit_subreddit_posts), so an agent must infer the sort-based distinction from the 'TOP' wording alone.

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?

'Shorthand for the highest-scoring posts of a community' implies the use case, and the t parameter context makes the time-window intent clear. However, there is no explicit when-to-use or when-not-to-use guidance versus reddit_subreddit_posts, reddit_home_feed, or reddit_subreddit_comments, so the routing decision is left to inference.

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 destructiveHint=false, so the safety profile is known. The description adds value by detailing the return object (content_md, content_html, may_revise, revision fields) and noting multi-segment pages, which goes beyond the schema and 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 sentences, front-loaded with the primary action, and each sentence adds distinct information (function, return format, usage guidance, example). No wasted words or redundancy with the schema.

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 no output schema, the description thoroughly covers return values, usage context, and an example. It is complete enough for an agent to select and invoke correctly 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?

Schema description coverage is 100%, so the baseline is 3. The description enhances this by providing a concrete example (name='python', page='index') and reiterating the multi-segment possibility, adding practical usage context beyond the schema definitions.

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 fetches a subreddit's wiki page by name and page, using the specific verb 'Fetch' and identifying the resource as a wiki page. It distinguishes from siblings like reddit_subreddit_rules by covering general wiki content (rules, FAQ, config/sidebar) and provides a concrete example.

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 states 'Use it to read a community's wiki, such as its rules or FAQ', giving clear context for when to use. It does not name alternatives or provide exclusions (e.g., for rules specifically), but the purpose is well-scoped and the example clarifies usage.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds return fields and an after cursor, but it does not disclose pagination termination caveats or listing_status behavior beyond what the schema's after parameter already says.

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 and front-loaded: it states the operation, return fields, usage context, and a compact example. Every sentence contributes useful information without 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 read-only listing tool with full parameter descriptions and annotations, the description is largely complete: it covers purpose, usage, return basics, and pagination cursor presence. It omits the critical listing_status caveat, but that detail is captured in the schema's after parameter description.

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 four parameters are already fully documented, including the important after cursor semantics. The description adds only a small example using name and sort, so the 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 and resource: "List a Reddit user's recent comments." This clearly distinguishes it from broader search tools and from user-post listings by resource scope, but it does not explicitly name sibling alternatives such as reddit_user_submitted or reddit_search_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?

It gives clear usage context: "Use to understand what a redditor talks about or to gather their opinions." This tells the agent when the tool is useful, but it does not include exclusions or explicitly compare against alternative comment-search 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 only declare readOnly/openWorld/no-destructive; the description adds substantial behavior beyond them: private owner-only data, the 403 failure mode, the out-of-band POST /api/reddit/login prerequisite for session cookies, and the mixed post/comment listing tagged by `kind`. These are exactly the traits an agent needs and cannot get from 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?

Purpose is front-loaded in the first sentence, followed by the critical privacy/auth caveat, then supplementary detail. Every sentence earns its place 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?

There is no output schema, but the description explains the return shape (mixed post/comment items tagged `kind`) and fully covers the auth prerequisite and failure mode. For an 8-parameter private-data tool, the agent has everything needed to call it 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 all eight parameters including enums, pagination cursor and limits. The description reinforces the auth-related params (reddit_session/loid, name matching the account) and gives an example, but adds little beyond the schema, so 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?

States a specific verb ('List') and resource ('posts and comments a Reddit account has received an award/gold on'), which cleanly distinguishes it from sibling content-list tools like reddit_user_saved, reddit_user_upvoted and reddit_user_submitted. An agent can identify the tool without opening the 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?

Gives a strong precondition: the data is PRIVATE and you must be logged in as `name` or it returns 403, with the concrete example name='spez' that must match the logged-in account. It doesn't frame when-not-to-use or name an alternative, but the owner-only constraint effectively scopes usage.

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 declare it a safe, open-world read; the description adds the critical behavioral fact that the data is private and owner-scoped, that a wrong account yields 403, that the listing is heterogeneous (each item tagged `kind`), and that session cookies must come from an out-of-band REST login. That is substantial context beyond the structured fields.

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?

Front-loaded with the operation and its privacy constraint, then prerequisites and the example. Efficient overall, though the login-cookie instruction is restated from the schema descriptions, so a sentence is partly redundant.

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, the description supplies what's needed: the mixed post/comment return shape and its `kind` tag, the authentication prerequisite, and the 403 failure mode. Combined with the schema's pagination guidance, an agent has everything required to call this 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% and each parameter is richly documented (including the `after` cursor and `listing_status` semantics), so the schema does the heavy lifting. The description only echoes that cookies come from login and that `name` must match the logged-in account, adding little beyond the schema; 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?

States a specific verb ('List'), resource ('posts and comments'), and precise scope ('a Reddit account has HIDDEN'), which cleanly separates it from siblings like reddit_user_saved and reddit_user_upvoted. An agent can distinguish it without opening the 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?

Gives explicit preconditions: must be logged in as `name` or the call returns 403, and requires a prior POST /api/reddit/login on the REST API (which is not an MCP tool). It does not explicitly name alternative tools to use when the data isn't hidden, but the context for correct invocation is 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 indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by detailing the return contents (username, id, karma, account age, flags, avatar) and providing an example, which goes beyond 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 two sentences plus an example, front-loaded with the verb and resource, and contains no filler. Every sentence 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 one parameter and no output schema, the description provides a complete picture: what it does, what it returns, and an example. It appropriately scopes itself against numerous sibling tools, making it self-contained.

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 provides 100% coverage with a clear description of the 'name' parameter including the 'u/' prefix constraint and path parameter status. The description only adds a redundant example ('spez'), so it does not significantly enhance parameter understanding 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 clearly states a specific verb and resource: 'Fetch a Reddit user's public profile by username.' It distinguishes itself from sibling tools by focusing on profile metadata (karma, account age, flags) rather than posts or comments, and provides an explicit use case: 'vet or summarize a redditor.'

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 a clear use case ('Use to vet or summarize a redditor'), implying when this tool is appropriate. It does not explicitly name alternatives like reddit_user_comments or reddit_user_submitted, but the distinction between 'profile' and 'activity' is clear enough.

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 declare readOnly/openWorld/non-destructive; the description goes well beyond by disclosing the private-data nature, the 403 auth failure mode, the required out-of-band REST login, the mixed post/comment listing tagged by `kind`, and — most valuably — the `listing_status` complete/truncated/unknown semantics and the warning not to present partial data as final.

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?

Purpose and the critical privacy/auth constraint are front-loaded, and the pagination caveat is tight and actionable. It is on the long side, with some auth detail that duplicates the schema, but each sentence carries operational weight.

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 an 8-param read with no output schema, the description covers the essentials: auth prerequisites, 403 behavior, mixed result typing via `kind`, and truncation status. It stops short of describing item payload fields, but the privacy and pagination guidance make it operationally sufficient.

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 every parameter including auth cookies, sort, t, limit, and after. The description largely restates this (name must match the logged-in account, session/loid required) and adds only a minor example, 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?

States a precise verb and resource ('List the posts and comments a Reddit account has SAVED'), and the emphasized SAVED scope cleanly separates it from sibling tools like reddit_user_upvoted, reddit_user_hidden, and reddit_user_submitted without needing to name them. An agent immediately knows which listing this retrieves.

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 real usage context: it must be the owning account, requires POST /api/reddit/login first, and returns 403 otherwise. It also guides pagination usage and how to react to truncated results. It does not explicitly name an alternative sibling tool or state when-not-to-use, so it stops short of a 5.

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 cover the safety profile (readOnly, openWorld, non-destructive), so the description is free to add functional detail: it enumerates returned fields (title, author, score, comment count, permalink) and mentions the `after` cursor, which matters because there is no output schema. It doesn't restate the truncation caveat beyond pointing at the cursor, but the schema's `after` description already carries that.

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 short sentences, front-loaded with the verb and resource, then the sibling distinction, then an example. No filler and nothing buried.

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, the description usefully names the returned fields and the pagination cursor, which is exactly what an agent needs to interpret responses. It could go slightly further on how the `listing_status` field affects downstream reporting, but that detail lives in the schema param.

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 `t`, `name`, `sort`, `after` and `limit` are all documented in the schema itself. The description only adds a single example (`name='spez' sort='top'`), which is a baseline-level supplement rather than new semantic content.

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 precise verb+resource (list a user's submitted POSTS) and explicitly positions itself against the sibling reddit_user_comments as 'the sibling of reddit_user_comments'. An agent can distinguish the two without opening either 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?

'Use to see what a redditor posts, not just what they comment on' gives a clear selection condition versus the comment-listing sibling, reinforced by a concrete example call. It stops short of naming other alternatives (e.g. reddit_search, reddit_subreddit_posts) or when not to use 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?

Annotations already cover readOnly/destructive/openWorld, and the description still adds substantial behavior: 403 if the cookies don't belong to `name`, the mixed post/comment listing tagged by `kind`, the out-of-band login step required before calling, and the `listing_status` truncation semantics with an explicit warning not to report truncated data as complete.

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?

Front-loads the one-line purpose, then adds only the caveats an agent needs (auth, mixed kinds, pagination). It is dense but each sentence carries operational weight; the auth/pagination guidance is slightly compressed into a single long paragraph rather than clearly separated.

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, open-world tool with no output schema, the description covers the riskiest unknowns: who may call it, how to authenticate, what the item kinds are, and how to interpret end-of-pagination via listing_status. Nothing essential to calling it correctly 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 already 100%, so the baseline is 3, but the description ties the parameters together into an auth story (reddit_session/loid must come from the same login as `name`, csrf only needed for writes) and reinforces why mismatched `name` yields 403. It adds framing value beyond the per-field schema text without re-documenting enums.

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 and resource ('List the posts and comments a Reddit account has UPVOTED'), and the upvoted scope cleanly separates it from siblings like reddit_user_saved, reddit_user_hidden, and reddit_user_submitted. An agent can route to it without opening any other 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?

Gives a clear precondition ('you must be logged in as `name`') and points at the required session args, plus a worked example (name='spez'). It does not explicitly compare against the other user-listing siblings, so the alternative-selection guidance is implied rather than stated.

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 genuinely non-obvious context beyond the annotations: the endpoint is a POST even though it is a read (ids in the body because 100 do not fit in a URL), and it is cost-equivalent to a read with no state change on Reddit. This resolves the apparent conflict an agent would see between the HTTP method and the readOnlyHint 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?

Front-loaded with the core purpose and the batch limit, and every sentence carries information. The parenthetical about ids in the body and the 'costs the same as any other read' clause partly restate the readOnly/non-destructive annotation, making it slightly longer than needed.

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, so the description supplies the return shape: one row per id, in submission order, each with a status. Combined with the batch limit, format flexibility, and the read-nature clarification, an agent has everything needed to call it 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 the id format, the 1–100 bounds, and bare-vs-t1_ fullname mixing. The description restates the bare/fullname interchangeability and adds a concrete example, but adds no semantics the schema lacks; 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?

States a specific verb and resource with precise scope: existence/visibility checking for a batch of comment ids up to 100. It is immediately distinguishable from reddit_search_comments, reddit_by_id, and reddit_post_visibility because it operates on known ids and returns status rather than content.

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 concrete when-to-use framing: distinguishing 'deleted by author' from 'removed by moderator' from 'still there', and re-checking previously posted or collected comments. It contrasts against 'a normal comment fetch' implicitly but never names the sibling tool (e.g. reddit_search_comments or reddit_by_id) an agent should prefer for content retrieval.

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