Weir: Reddit and X (Twitter) data

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new information with 'Free: costs no credits', a cost trait the annotations do not express.

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: the return payload first, then the use case and cost note. Nothing is padded and no sentence restates the title.

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 and no parameters, the description carries the burden of describing the return value and does so by naming the three fields. It omits edge behavior such as what happens with an invalid or expired credential, which would matter for an identity probe.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, which sets the baseline at 4. The description correctly implies no input is needed and instead spends its words describing what the call returns.

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?

It names the specific resource ('the current credential') and enumerates what comes back: account id, connection id, scopes. That is enough to separate it from the data-fetching siblings, though it does not explicitly distinguish itself from get_limits/get_usage, which cover adjacent credential concerns.

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 it to check what this connection is allowed to do' supplies a concrete situation for calling it. There is no exclusion or explicit alternative named, so an agent must infer when get_limits or get_usage is the better call.

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 read-only, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context that annotations cannot express: the call is free and consumes no credits, which matters in a metered API. It stops short of saying whether limits are cached or live.

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 of the three sentences say the same thing ('Free. Free: costs no credits.'), which is pure repetition and eats space that could have carried usage guidance. The remaining sentence is dense but front-loaded with the returned fields rather than a verb, so it reads as a label.

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 describing return values and does so adequately by listing the three quota categories. Since the tool has no inputs and a simple non-destructive read profile, there is little else an agent needs before calling it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the baseline this scores 4; there is nothing for the description to disambiguate. The description correctly implies no input is required.

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 enumerates the concrete ceilings returned (requests per minute, monitor/webhook counts, hourly-run eligibility), which is a specific resource with identifiable content. It implicitly distinguishes itself from get_identity and get_usage by naming plan-quota data, though it never states that distinction explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to call this versus the similar account-state siblings get_identity and get_usage, nor any prerequisites. The agent must infer that this is the tier-quota check from the field list 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds one genuinely new behavioral fact — it costs no credits — but says nothing about failure behavior for an invalid or deleted id, which for a fetch-by-id tool is the main unknown.

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, zero padding, with the identity of the resource front-loaded and the cost note kept secondary. Nothing here could be cut without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read, rich annotations and a fully documented schema, the description is nearly sufficient; the only gap is not-found/error behavior. No output schema exists, so it needn't describe the returned monitor shape.

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 there is only one parameter with a uuid format, so the schema carries the semantics. The description's "by id" adds no format or sourcing detail 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?

The description identifies a single saved monitor retrieved by id, which is specific enough to separate it from list_monitors (plural listing) and get_monitor_run (run-level). The verb is elided ("One saved monitor by id") rather than stated, but the resource and cardinality are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"by id" implies this is the lookup path once an id is known, and the sibling name list_monitors makes the alternative inferable, but the description never explicitly says when to use this instead. No prerequisites, no statement about what to do when the id is unknown.

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 read-only, idempotent, closed-world, non-destructive behavior, so the description adds genuinely new context: the call is free (no credits) and is intended for polling, implying a run may be observed in a not-yet-finished state. It stops short of describing error behavior for a bad monitor/run id or any eventual-consistency caveat beyond polling.

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 purpose, then returned fields, then usage and cost. No filler; every sentence carries information the agent would otherwise have to infer.

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 return payload (status, timing, found/new counts, cost), which is exactly what an agent needs to reason about the result. The remaining gap is parameter identification (monitor id vs run id), which is left partly implicit.

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 50%: `id` is documented only generically as 'Identifier of the resource' and `runId` has no description. The phrase 'one run from the monitor's history' implies `id` is the monitor identifier and `runId` selects the run, but neither parameter is explicitly disambiguated, so the description only lightly compensates.

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 ('Get one monitor run') and immediately enumerates what that single record contains: status, timing, result counts, and cost. The singular framing plus the field list makes it distinguishable from the sibling `list_monitor_runs` 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 explicit usage context: 'Poll it after `runMonitor` to see when a run finishes,' which tells the agent both the trigger and the intent (waiting for completion). It does not state when to prefer this over `list_monitor_runs` or what to do if the runId is unknown, so no full when/when-not pairing.

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 safety (readOnly, idempotent, non-destructive), and the description layers on genuinely new behavior: the cost model ('1 credit + 3 credits per comment returned'), the flattened-plus-depth/parentId result shape, and the cursor contract. The per-comment billing detail is commercially material and appears nowhere in 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?

Four short sentences, front-loaded with the core action and result shape, then sorting, then cost, then pagination. Every sentence carries a distinct, actionable fact 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?

With no output schema, the description does the necessary work of describing the return shape (flat list with depth and parentId) and the meta.nextCursor field. It omits which comment fields are returned (author, score, body) and how depth/limit interact with billing, minor gaps for a read tool whose safety profile is annotated.

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 adds a selection rule for sort ('top' for most upvoted) and clarifies the resume protocol for cursor. It says nothing extra about depth, limit, comment, or context, all of which are left to 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?

Names a specific verb and resource ('Fetch the comment tree of a Reddit post') and pins down the output shape ('flat list, each with depth and parentId'). It doesn't differentiate from near neighbours like get_subreddit_comments or get_reddit_post, so an agent must infer the distinction from the required post id.

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 operational guidance: 'Use sort=top for the most upvoted replies' and the exact pagination loop via meta.nextCursor. It never states when to prefer a sibling (get_subreddit_comments, search_reddit) or when not to use this tool, so it stops short of full 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 already declare readOnly/idempotent/openWorld, so the safety profile is covered. The description adds what the annotations cannot: a cost model of 1 credit plus 3 credits per post returned, which is meaningful pre-call context. It does not mention failure modes (deleted/private posts) or rate limits, keeping it below 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?

A single sentence with the resource and return fields front-loaded, followed immediately by the cost. Nothing is padded and nothing needs reordering.

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 field enumeration compensates well for what the caller will receive, and the credit cost covers billing behavior. Minor gaps remain around error cases and whether media/embedded content is included, but the essentials for a correct call are present.

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 id property already documents the permalink, redd.it, and t3_ accepted formats in detail. The description adds nothing about the id beyond the schema, 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 plus the exact fields returned (title, selftext, author, subreddit, score, numComments, url), which is far more precise than the title alone. It does not explicitly differentiate from near-siblings like lookup_reddit or search_reddit, so it falls short of a 5.

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 word 'one' and the required single id imply this is the by-ID retrieval path, but there is no explicit statement of when to use this versus lookup_reddit, search_reddit, or get_subreddit_posts. Usage is inferable 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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description adds genuinely new behavioral context: suspended accounts return isSuspended: true with null counters, nonexistent accounts return 404, and each call costs 1 credit plus 1 per user returned. These are exactly the operational details annotations cannot express.

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 purpose, then return fields, then edge cases and cost. Every sentence carries distinct information with no restatement of the name or title.

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: the field inventory, the suspended-account shape, and the 404 case. For a one-parameter read tool, an agent has everything needed to call it and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter with 100% schema description coverage ("Username without the `u/` prefix" plus a regex pattern), so the schema fully documents the syntax. The description never references the username argument, so it adds nothing on top of the structured field — 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 ("Get a Reddit account's public profile") and enumerates the fields returned: karma, account age, moderator/Premium status, bio, follower count. That inventory clearly separates it from siblings like get_reddit_user_comments, get_reddit_user_posts, and get_x_user, which return content or other platforms.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase "the facts that tell a real, established account from a throwaway" gives a concrete use case that orients an agent toward vetting/trust decisions rather than content retrieval. It does not name alternatives (e.g. lookup_reddit, search_reddit) or state exclusions, so it stops short of full 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?

Goes well beyond the readOnly/idempotent annotations by disclosing the ~1,000-item pagination ceiling, the per-comment credit cost model, the NSFW filtering side effect surfaced via meta.omittedNsfw, and the exact 404 semantics for missing vs suspended accounts. This is precisely the operational context annotations cannot carry.

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 action and return shape, then layers edge cases and cost/pagination notes in a compact block. Every sentence carries actionable information with no restatement of the name or title.

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 key return fields (linkTitle, linkPermalink), the pagination cursor location, and the omission metadata, and covers error states. An agent has everything needed to call and interpret results 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 baseline is 3, but the description adds real value on cursor: it explains that meta.nextCursor must be passed unchanged and is bound to the other parameters, and it clarifies that a short or empty page may be NSFW filtering rather than inactivity.

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 — listing an account's comments across every community, with the parent post fields named. It distinguishes itself implicitly from get_reddit_user_posts by resource type but never names any sibling to route against.

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 operating conditions: empty page with karma means hidden activity, nonexistent account is 404, suspended is 404 with details.reason, and it tells the agent to call again with cursor when meta.nextCursor is set. It stops short of explicitly saying when to prefer this over get_reddit_user_posts or get_reddit_comments.

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 read-only, idempotent, open-world, non-destructive, but the description adds a lot they cannot carry: hidden activity masquerading as an empty page, 404 semantics for missing vs suspended accounts (`details.reason` `suspended`), the ~1,000-item ceiling, and the credit cost model. That is exactly the supplementary context annotations cannot express.

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 purpose is front-loaded in the first clause, followed by scoping, the alternative route, then operational caveats. It runs long, but each sentence (hidden activity, 404 states, page ceiling, cost, pagination) carries distinct operational value with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter, paginated, credit-metered list tool with no output schema, the description covers the failure modes, the return-signal fields (`meta.nextCursor`, `meta.omittedNsfw`, `details.reason`), and the pagination contract — enough for an agent to call and continue correctly without guessing.

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 every parameter is already documented in the schema, so the schema carries the burden. The description only reinforces the default sort and reiterates cursor reuse in prose; it adds no syntax or format detail 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 ('List the posts an account has submitted') and adds scope ('across every community, newest first by default'), which separates it from get_reddit_post and get_subreddit_posts. It does not explicitly name get_reddit_user_comments as the complementary sibling, so the posts-vs-comments distinction rests on the name 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?

Explicitly routes the polling use case elsewhere: 'To be told when it posts, create a `reddit_user` monitor instead of polling.' That is a genuine when-not statement with a named alternative, strengthened by the pagination instruction ('When meta.nextCursor is set, call again with cursor set to it'). It stops short of contrasting with search_reddit or get_reddit_user_comments.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral information: the credit cost model (1 credit + 1 per subreddit returned), which is not expressible in annotations. It omits failure behavior for nonexistent or banned subreddits, keeping 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?

Two short sentences with no filler: returned fields first, cost second. Front-loaded and appropriately sized, though the '1 credit per subreddit returned' phrasing is slightly redundant for a single-subreddit tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A simple read-only lookup with a fully documented single parameter and no output schema; the description compensates by enumerating the returned fields and disclosing cost. Nothing critical an agent needs to call it correctly is missing, aside from error/nonexistent-subreddit behavior.

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 itself documents the accepted formats (bare name, r/name, or URL) with an example. The description adds nothing about the name parameter, so the baseline of 3 is appropriate 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?

States a specific resource (one subreddit) and verb (get metadata), and enumerates the returned fields: title, description, subscribers, over18, creation date. It does not explicitly differentiate from siblings like search_subreddits or get_subreddit_posts, but the singular 'one subreddit' framing makes the distinction inferable.

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 implied by the singular scope — fetch metadata for a known subreddit rather than search for one — but no when/when-not conditions or named alternatives (e.g., 'use search_subreddits to find a name first') are given. An agent must infer the routing from the tool name 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 cover read-only/idempotent/open-world, but the description adds critical economics ('Costs 1 credit + 3 credits per comment returned') plus a non-obvious filtering rule: NSFW is judged by the comment's post, and omissions are surfaced in meta.omittedNsfw so an empty page isn't misread as a quiet community. These are behavioral traits no structured field conveys.

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, then alternatives, then cost and pagination — a sensible ordering. The framing sentence about busy communities is slightly wordy but earns its place by motivating the monitor alternative.

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 returns and does so: each comment carries its post (`linkTitle`, `linkPermalink`), and paging/omission state lives in `meta.nextCursor` and `meta.omittedNsfw`. An agent has everything needed to call it and interpret the response.

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 all four parameters; the description reinforces the high-value ones — multi-community `+` joining, the includeNsfw default and its omission reporting, and the cursor's binding to other parameters. It adds workflow context rather than new field-level semantics, so it sits above the baseline but not at the top.

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 and resource ('Read a community's newest comments') and pins the scope ('across every post', 'newest first'). It also distinguishes itself from the search siblings by stating that Reddit's search does not search comment text at all, which differentiates it from search_reddit/search_subreddit without opening a 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 an explicit use case ('the way to find mentions inside comments') and an explicit alternative with its selecting condition: for continuous watching, create a `subreddit_comments` monitor, which also filters by keyword. It also states when to call again (when meta.nextCursor is set) and the NSFW default.

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 past the annotations: discloses the ~1,000-post pagination ceiling where `nextCursor` becomes null, the NSFW exclusion rule and its `meta.omittedNsfw` accounting, the 404 with `details.reason` for missing/private/banned/quarantined communities, and the exact cost model (1 credit + 3 per post). Idempotency and read-only status are already in annotations, so this is pure added value.

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 and the sibling comparison, then organized into cost/pagination/NSFW/error paragraphs. Dense but every sentence carries operational information an agent needs; nothing is 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 carries the return contract itself — it explains `meta.nextCursor`, `meta.omittedNsfw`, `details.reason`, and the pagination loop. For a 7-parameter listing tool with open-world scope, 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; the description still adds real meaning — that `name` accepts `popular`/`all`/`+`-joined communities and that a joined read is billed as one request, plus the sort/time interaction and the cursor's binding to the other parameters. It stops short of restating every field's constraints, which the schema already handles.

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 ('List a community's posts') plus the five orderings, and immediately distinguishes itself from search_subreddit/search_reddit by explaining that search needs a keyword and cannot express 'everything'. An agent can pick it apart from every sibling without opening a 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?

Explicit routing rule: 'Use this rather than search when the community is the filter — Reddit's search needs a query and cannot express "everything".' It also names the concrete scenarios (everything new in r/saas, this week's top in r/startups) and explains when to use the multi-community `+` form instead of multiple calls.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts: the call costs no credits and that a 402 will not clear until the reset, which materially changes retry strategy. 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?

Front-loaded and compact, but 'Free' is asserted three times ('Free.', 'Free: costs no credits') which is pure repetition. The opening 'The credit balance:' is also a fragment that reads like a field list rather than a sentence, though it survives as a spec.

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 input params and no output schema, the description carries the return-value burden and does so by enumerating every field including the free-grant reset timing and spend-pause flag. An agent knows exactly what it will learn and when to ask for it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description instead spends its words on describing the return payload, which is the useful choice 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?

Names a concrete resource (credit balance) and enumerates the exact fields returned: available spend, free grant with reset timing, tier, and paused-spend state. It does not distinguish itself from the sibling get_limits, which is the one tool an agent could plausibly confuse it with, so it falls short of a 5.

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 two explicit, actionable triggers: after a tool returns 402 (with the useful note that it is not retryable until reset) and before a large batch of calls. It stops short of naming get_limits or get_identity as alternatives, so the selection guidance is strong but not 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 readOnly, idempotent, non-destructive, and open-world behavior, but the description adds substantial context beyond them. It discloses the return shape, the 404 condition for non-Article posts, and the credit cost including per-post returned, which is exactly the kind of behavioral information an agent needs before invoking it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with what the tool returns, then moves to usage, input caveats, error behavior, and cost. Every sentence carries useful information, and there is no repetition or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, but the description adequately explains the returned content: title, cover image, Markdown body, plain text, X blocks, and images. It also covers the key error case and cost model, making the definition complete enough for an agent to 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%, so the single id parameter is already documented as accepting digits or an x.com/twitter.com status URL. The description adds meaningful semantics by emphasizing the status link/id form and warning that an x.com/i/article/ link contains a different id, which prevents a likely invocation error.

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: read a long-form X Article in full, including title, cover image, body Markdown, plain text, blocks, and images. It clearly distinguishes this from a normal post by noting that a post sharing an Article has only a link as its own text, so an agent can tell it apart from sibling tools like get_x_post or get_x_thread.

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 triggering guidance: use it for any x.com post or link that shares an Article, and pass the status link or id. It also provides important exclusions, such as x.com/i/article links containing a different id and a 404 when the post is not an Article. It does not explicitly name get_x_post as the alternative for non-Article posts, which keeps it just below the top score.

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/idempotent annotations, it discloses the failure mode (404 when the List does not exist or is private) and the billing model (1 credit + 2 credits per list returned), which no structured field conveys. That is exactly the kind of behavioral context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with purpose then return fields, then alternatives, then error/cost. The only waste is the near-duplication between 'Billed per List returned' and 'Costs 1 credit + 2 credits per list returned.'

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 enumerating the returned fields, and it covers error behavior and pricing for a single-parameter read tool. Nothing an agent needs in order to call 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% and the schema already explains that `id` is the digits after `/i/lists/` in a List URL, including the pattern. The description adds no further meaning about the parameter, 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?

Specific verb ('Get') plus specific resource ('a public X List') and an explicit statement of what metadata is returned (name, description, owner, member/follower counts). It also explicitly separates itself from get_x_list_members and get_x_list_posts, so an agent can place it among siblings without opening a 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 routes the agent onward: members via `getXListMembers`, timeline via `getXListPosts`, making clear this tool only returns List metadata. It gives no explicit 'don't use for X' exclusion or prerequisite, but for a unique single-purpose lookup the guidance is 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 already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds material context beyond them: billing ('1 credit + 1 credit per user_result returned'), result ordering by X, and cursor termination semantics. The credit cost per returned user is exactly the kind of pre-call cost signal 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?

Front-loaded with purpose and return shape, then billing, then pagination — good ordering. The final sentence ('when meta.nextCursor is set, call again with cursor set to it') is largely redundant with the earlier 'paginate with meta.nextCursor, which is null after the last page', costing a small amount of efficiency.

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 describing results and does explain the accounts plus meta.nextCursor pagination and per-result billing. It stops short of indicating what fields each returned account carries, which is the one remaining gap for an agent consuming the response.

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 id format, limit bounds, and cursor opacity/rejection behavior in more detail than the description. The description's pagination sentences add flow guidance but largely restate the cursor parameter's documented contract, 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 ('get') and precisely scoped resource ('the members of a public X List'), then clarifies the return is 'the accounts in a List, as X orders them'. This cleanly separates it from siblings like get_x_list (list metadata) and get_x_list_posts (posts in a list) without needing to name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a positive usage rationale — 'Lists are curated, so this is a quick way to find the accounts that matter on a topic' — and full pagination instructions. It does not name exclusions or point to alternative sibling tools (e.g., get_x_user_followers) when a List isn't the right source.

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 read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable details beyond annotations: billing ('1 credit + 1 credit per post returned'), page size controlled by X (no limit parameter), and pagination via meta.nextCursor. These are non-obvious behavioral traits that materially help an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose, then proceeds to return format, pagination, and cost in a logical order. Every sentence contributes essential information without repetition 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?

With no output schema, the description adequately explains the return content (recent posts, newest first) and the meta.nextCursor pagination mechanism. Combined with annotations covering safety and the full schema, an agent has everything needed to call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema itself documents id and cursor thoroughly. The description adds meaning by explaining why there is no limit parameter (X chooses page size up to ~100) and reinforces cursor usage. This goes beyond the schema in explaining the absence of a common control 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 states a specific verb and resource (get timeline of a public X List) and clarifies that it returns posts from the List's members, newest first, like the feed on X. This clearly distinguishes it from siblings like get_x_list (metadata) and get_x_list_members (member list).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use it (to get the same feed the List shows on X) and explains pagination, but it does not explicitly name alternative tools or state when not to use it. The implied usage is strong enough for an agent to choose correctly.

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, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds nontrivial behavioral context: credit cost and the special article-link behavior, which an agent would not know from 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?

Two tightly written sentences with no wasted text. The core operation is front-loaded, followed immediately by the important article caveat and cost information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description gives a useful summary of the return shape: post, author, engagement counts, plus the article field caveat. It is close to complete, though it could say more about failure or rate-limit behavior.

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 fully documented, including that an x.com or twitter.com status URL works. The description does not add further parameter semantics beyond the schema, so 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 and resource: fetching one public X post, including author and engagement counts. The singular post scope distinguishes it from sibling bulk tools such as get_x_posts and aligns with get_x_article semantics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by saying it fetches one post and explains the article edge case, but it does not explicitly say when to choose this over get_x_article, get_x_posts, or search_x. Guidance is present only indirectly.

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/idempotent safety profile, and the description adds substantial behavior on top: newest-first ordering, the meaning of an empty list, the 404 failure mode, the one-hour edit window that explains why histories are often short, and per-version billing. These are exactly the facts an agent needs to interpret results and anticipate cost.

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?

Six short sentences, front-loaded with purpose and result shape before failure and cost details. The only waste is near-duplication between 'Billed per version returned' and 'Costs 1 credit + 1 credit per post returned,' which could be merged into one clause.

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 tool with no output schema, the description covers return ordering, empty-result semantics, error behavior, and cost. Nothing material is left for the agent to guess before invoking it.

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 schema already explains that the id accepts digits or a full x.com/twitter.com status URL. The description adds nothing further about the identifier, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb and resource ('Get the edit history of an X post'), which cleanly separates it from get_x_post, get_x_thread, and get_x_quotes in the sibling list. The second sentence further pins down what is returned ('every version of an edited post, newest first, including the current one').

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear selection context: use it to reconstruct edits, and 'an empty list means the post exists and was never edited' tells the agent how to interpret a negative result. It does not explicitly say to use get_x_post for the current version instead, so the sibling routing 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses result ordering, partial-failure semantics ('listed in meta.notFound instead of failing the request'), that missing ids are not billed, and the exact billing formula. These are precisely the operational facts an agent needs before deciding to call it at volume.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with purpose, then usage, then failure behavior, then cost. 'Billed per post returned' and 'Costs 1 credit + 1 credit per post returned' overlap slightly, but the second adds the base-credit detail, so the redundancy is minor.

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, yet the description covers return ordering, the meta.notFound shape, and the cost model — covering the gaps an output schema would normally fill. For a single-parameter batch read tool, 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 already 100% (comma-separated numeric ids, 1-100, no spaces, duplicates ignored), so the schema carries most of the burden. The description still adds real meaning: returned posts follow the requested order, and unresolvable ids surface per-id in meta.notFound rather than as an error, which shapes how the agent interprets the single 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 first sentence gives a specific verb ('get'), resource ('public X posts'), and hard scope ('up to 100 ... by id'). The follow-up 'Looks up many posts in one request' implicitly separates it from the single-post sibling get_x_post and makes the batch nature unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states a clear use case — 'for hydrating ids you already hold (from a webhook, a dataset, or another response)' — which tells the agent this is a batch-hydration tool, not a discovery tool. It stops short of naming an alternative such as get_x_post for single lookups or search_x for discovery, so there are no explicit exclusions.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered structurally. The description adds genuinely new behavioral context: per-post billing ('1 credit + 1 credit per post returned') and the fact that each result embeds the quoted post. Missing is anything about error conditions or rate limits, so this is solid but not exceptional.

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 and return shape, then value proposition, then cost, then pagination — a sensible priority order. The pagination instruction is stated twice ('Paginate with meta.nextCursor' and 'When meta.nextCursor is set, call again...'), which is the one redundant element.

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, yet the description covers the key return contract (quoting posts, each with `quotedPost` embedded, `meta.nextCursor` for paging) as well as cost per call. For a single-resource, four-parameter read tool, an agent has everything needed to invoke and cost-estimate 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 id, sort, limit and cursor thoroughly. The description repeats the cursor round-trip ('call again with cursor set to it') and names meta.nextCursor, which mildly links the input to the response shape, but adds no syntax or constraints 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 ('Get posts quoting an X post') and immediately disambiguates from the nearest sibling by contrasting with replies ('discussion beyond its replies'). An agent can distinguish it from get_x_replies and get_x_post 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?

Gives a clear use case ('tracking how a post is being discussed beyond its replies') and implies the reply-thread alternative. It stops short of an explicit when-not-to-use or a named sibling to prefer, so it falls 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 already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real context beyond that: an explicit cost model (1 credit + 1 credit per returned post) and the pagination contract, which an agent needs before invoking a metered call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste. Purpose and cost come first, then the pagination instruction, so the most decision-relevant information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description only partially covers return values: it names meta.nextCursor but says nothing about the shape of a reply object. For a single-required-param read tool with a fully documented schema, that is a minor gap, but not a complete picture.

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 cursor description already explains the meta.nextCursor round-trip and the 400 rejection for mismatched cursors, so the description mostly repeats it. It adds no new meaning for sort or limit, making baseline 3 the right score 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: 'Fetch public replies to one X post.' That is enough to distinguish it from get_x_quotes or get_x_retweeters, but it never contrasts with close siblings like get_x_thread (whole conversation) or get_x_user_replies (a user's reply history), leaving overlap for an agent to resolve.

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 guidance for pagination ('When meta.nextCursor is set, call again with cursor set to it'), which is genuinely operational. It says nothing, however, about when to choose this tool over get_x_thread or get_x_user_replies, so selection guidance is only implied by the resource name.

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 annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses that X may cap retweeter lists for widely reposted posts, that like data does not exist, and the exact billing model ('1 credit + 1 credit per user_result returned'). Those are cost and completeness traits an agent cannot derive from 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?

It is front-loaded with the purpose and every sentence carries information (cap behavior, likes unavailability, billing, pagination). The pagination advice appears twice — once as 'Paginate with `meta.nextCursor`' and again in the closing sentence — which is a minor 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?

With no output schema available, the description still tells the agent what comes back ('accounts... as X lists them'), where the cursor lives in the response, that results may be truncated by X, and what each call costs. That is enough to invoke and loop the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so `id`, `limit`, and `cursor` are already fully documented, including the cursor's rejection with 400 if reused across requests. The description's pagination sentence restates what the cursor schema already says, adding no new syntax or format semantics, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb ('Get') and resource ('accounts that reposted an X post'), which is precise enough to separate it from sibling endpoints such as get_x_quotes, get_x_replies, and get_x_user_posts 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 tells the agent that pagination means calling again with `cursor` set from `meta.nextCursor`, and it rules out an adjacent use case by noting that liker data is unavailable because X made likes private. It stops short of naming alternative sibling tools (e.g. get_x_quotes) for the related-but-different question of who quoted the post.

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 annotations (readOnly/openWorld/idempotent), the description discloses the pricing model ('1 credit + 2 credits per space returned'), the 404 failure mode, and the default omission of listeners with the reason (list length and privacy of individuals). These are exactly the non-obvious traits annotations cannot express.

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 compact sentences: identity/return shape first, then the opt-in flag, then the error case, then cost. Nothing is repeated and each sentence adds a distinct fact.

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 return-shape burden itself and does so by enumerating the Space's fields and states. With only two parameters and read-only annotations already covering safety, an agent has everything needed to call it correctly and anticipate cost and 404s.

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 — the URL-derived id and the listeners enum with its privacy rationale — are already fully documented in the schema, so the description's 'Listeners are included only with listeners=true' largely restates it. Baseline 3 applies 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 opens with a specific verb+resource ('Get an X Space') and immediately defines it as 'a live audio room', then enumerates the fields returned (title, state, schedule, host, speakers, audience counts, replay availability). No sibling tool retrieves Spaces, so there is no ambiguity against the get_x_post/get_x_user/get_x_list family.

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 operational context: listeners are opt-in via `listeners=true`, a missing Space yields 404, and cost scales per Space returned. There is no sibling alternative to steer away from, so no explicit exclusion is needed; the only modest gap is the absence of a stated 'use when you have a Space id or URL' framing, which the schema's id description partly covers.

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 safety hints (read-only, idempotent, non-destructive); the description adds substantive behavior they cannot: the exact ordering of results, the truncation caveat at X's "Show more" fold, the 404 condition, and per-post billing with a concrete credit formula. These are the operational facts an agent needs before calling and no structured field carries 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?

Front-loads the purpose, then stacks return shape, argument rule, exclusion, truncation limit, error case, and cost in short declarative sentences. Every sentence contributes a distinct fact; nothing is restated from the title or annotations.

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 burden of describing return content and ordering, and it also covers the failure mode and pricing. For a single-parameter read tool, nothing an agent needs in order to call it correctly or interpret results 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 would be 3, but the description adds real meaning the schema lacks: the id may be any post in the thread, not just the head, which changes how an agent sources the argument. That is a semantic clarification beyond the schema's "post id or status URL" note.

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 ("Get the author's thread containing a post") and immediately defines the returned set: earlier posts it continues from, the post, and continuation below. It explicitly separates itself from replies by pointing to the replies tool, so an agent can distinguish it from siblings like get_x_post or get_x_replies without opening a 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 an explicit invocation rule ("Pass any post in the thread") so the agent knows it need not hunt for the root, and names the exclusion plus the alternative tool for other people's replies. That is a genuine when-to-use / when-not-to-use / alternative routing statement, the top of the scale.

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

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

The description provides critical operational behavior beyond the annotations by specifying the exact cost structure: 'Costs 1 credit + 2 credits per profile returned.' This is vital information for an agent managing resource constraints.

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 extremely concise and well-structured. The first sentence defines the resource and scope, and the second sentence provides the essential operational metadata (cost), utilizing every sentence efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite lacking an explicit output schema, the description exhaustively lists every single field returned by the API. Combined with the operational cost, this makes the tool definition maximally complete for agent invocation and planning.

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%, meaning the input schema already provides a thorough description of the 'user' parameter. The description focuses on the output data and costs, not the input semantics, making the baseline score of 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose is to fetch a 'public X profile.' It goes beyond a generic statement by listing all the specific attributes returned (name, followersCount, verified, etc.).

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 frames the tool's scope as fetching a 'public X profile,' which provides clear context on its usage boundaries. While it doesn't list usage scenarios, the scope definition is strong enough to guide agent selection.

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 read-only/idempotent annotations, it discloses the 404 error conditions and explains why a protected account yields 404 (posts and connections visible only to approved accounts). It also states the billing model, including the extra charge when a numeric id is used, which annotations cannot express.

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 return contents, then error behavior, then cost, which is a sensible ordering for an agent reading top-down. It is fairly dense and the protected-account clause reads like an inline aside, but no sentence is pure 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 compensates by enumerating exactly which fields come back: country attribution, connection to X, username-change count, and verification. Combined with the error conditions and cost model, an agent has everything needed to call it and interpret the result.

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 accepted forms of `user` (handle, numeric id, profile URL) are already documented in the schema and not repeated. The description's only real parameter insight is the billing consequence of passing a numeric id, which is a marginal addition over 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?

States a specific verb (get) and a clearly bounded resource: the 'About this account' panel contents, enumerated as country attribution, connection to X, username-change count, and identity verification. This distinguishes it from get_x_user's general profile, though the description never names that sibling explicitly, leaving the distinction implicit rather than stated.

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?

'Useful for judging whether an account is what it claims to be' gives a concrete decision context for calling it, which is more than most entries provide. It falls short of a full when/when-not rule because it never tells the agent to prefer get_x_user for ordinary profile data or to skip this call when authenticity is not in question.

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 (readOnly, idempotent, non-destructive, open-world), and the description adds substantial context beyond them: per-account billing, an extra profile-lookup charge on the first page only, empty results for non-Verified Organizations, 404 for missing or protected accounts, and a rationale for why protected accounts are hidden. That is exactly the kind of cost and failure-mode disclosure annotations cannot carry.

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, then return semantics, error cases, and pagination in a logical order. The billing information is mildly duplicated ('Billed per account returned' followed by the full credit breakdown), costing a little density but each statement still carries actionable detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still tells the agent what comes back, how to detect more pages via meta.nextCursor, which error conditions to expect, and the full cost model. Nothing an agent needs to call and paginate this tool 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 would be 3; the description adds meaning beyond the schema by explaining that the first page pays for a profile lookup to resolve `{user}` while later pages carry the account in the cursor, which tells the agent why `cursor` must be reused unchanged. It does not elaborate on `limit` behavior beyond what the schema 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?

States a specific verb and resource ('Get an organisation's affiliated X accounts') and immediately defines the resource: accounts a Verified Organization lists as affiliated, such as employees, products, or regional accounts. That definition is enough to separate it in practice from followers/following siblings, though no sibling is named explicitly, which keeps it at 4 rather than 5.

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 operational guidance for pagination ('When meta.nextCursor is set, call again with cursor set to it') and explains when results are empty (non-Verified Organizations). It does not say when to prefer this over adjacent siblings such as get_x_user_followers or get_x_users, so usage is implied rather than directed.

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 past the annotations: ordering semantics ('mostly most recent first, though X can place some accounts out of that order'), server-chosen page size (~70), the 404 conditions including protected accounts, and the full billing formula including the extra first-page profile lookup. These are non-obvious traits an agent cannot derive from readOnlyHint/idempotentHint.

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 what it returns and the ordering caveat, then pagination, then errors and cost — a sensible order. There is minor redundancy: 'Billed per account returned' is restated in more detail in the credit formula two sentences later.

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?

Covers pagination, error cases, and cost thoroughly, which is most of what an agent needs for a read-only paged endpoint with no output schema. It never names the fields present on each returned follower account, which an agent may want when deciding whether this tool alone suffices.

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 value: it clarifies that no limit parameter exists because X sets the page size, and ties `cursor` to `meta.nextCursor` and the end-of-results null condition. It does not add format detail for `user` beyond what the schema already documents.

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 and resource ('Get an X account's followers') and implicitly contrasts with the sibling get_x_user_following by naming the direction of the edge. An agent can distinguish it from list-members and search-x-users tools 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?

Gives clear operational guidance for when to call again ('When meta.nextCursor is set, call again with cursor set to it') and explains why there is no `limit`. It stops short of explicitly naming alternatives such as get_x_user_following or search_x_users, so the sibling routing is inferred from the tool name 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?

Annotations only cover safety (readOnly, idempotent, non-destructive); the description goes well beyond by disclosing ordering ('mostly most recent first, though X can place some accounts out of that order'), a fixed page size of about 70, the absence of a limit parameter, 404/protected-account semantics, and a detailed billing model. This is exactly the behavioral context the annotations cannot carry.

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 purpose, then ordering, pagination, errors, and cost in a sensible sequence with no filler. Minor redundancy: pagination via meta.nextCursor is stated early and restated in the closing sentence, and 'Billed per account returned' is partially repeated by the itemized credit formula.

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 explain ordering and the meta.nextCursor field plus the cost per returned profile, which is enough to drive a pagination loop. It does not describe the shape of each returned account object, which is the one remaining gap for a tool with no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3 and the schema already documents both parameters including the 400 on a foreign cursor. The description adds genuine meaning: there is deliberately no limit parameter, and the account is resolved on the first page but carried inside the cursor on later pages, which explains why cursor cannot be reused across requests.

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 sentence names a specific verb and resource and fixes the direction of the relationship ('the accounts an X account follows'), which reads as distinct from the get_x_user_followers sibling. It never names that sibling explicitly, so the agent must infer the contrast rather than being routed.

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 context is concrete: paginate whenever meta.nextCursor is set, pass it back as cursor, and expect a 404 for nonexistent or protected accounts. What is missing is selection guidance against alternatives (followers, search_x_users, get_x_users) for when an agent should choose this tool over them.

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, idempotent, and non-destructive, but the description adds substantial context beyond them: the per-post billing model, the extra profile lookup billed only on the first page, the 404/privacy behavior for protected accounts, and the empty-list behavior for non-Premium accounts. This is exactly the kind of operational detail an agent needs before invoking a billed, paginated read.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and scope, then moves through edge cases, billing, and pagination in a logical order. It is somewhat dense — the billing sentence is long — but each clause carries operational information an agent would otherwise lack.

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, yet the description explains that the return is a list of featured posts, how pagination works via meta.nextCursor, what happens on missing/protected accounts, and how billing accrues. For a read-only, paginated, metered tool, nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage the baseline is 3, but the description adds meaning beyond the schema for the cursor: later pages 'carry the account in the cursor and do not' incur the lookup charge, and the agent must call again with cursor set to meta.nextCursor. It also clarifies that the first page resolves the {user} argument at extra cost, which the schema alone 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?

The description states a specific verb and resource — 'Get the posts an X account highlights' — and immediately explains the scope: 'Returns the profile's Highlights tab: posts the account chose to feature.' This differentiates it from siblings like get_x_user_posts and get_x_posts without the agent needing to inspect 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?

It gives clear contextual guidance: only Premium accounts can highlight so the list is empty otherwise, a 404 occurs for nonexistent or protected accounts, and pagination is driven by meta.nextCursor. It does not explicitly name alternative tools such as get_x_user_posts for a general timeline, but the 'featured' distinction makes the right choice obvious.

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 annotations: it discloses the 404 conditions (nonexistent or protected account), explains what protected means for visibility, and gives a full billing model including the one-time profile lookup on the first page only. The pagination contract and credit formula are exactly the kind of operational detail annotations cannot carry.

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, then error conditions, then cost, then pagination — a sensible ordering with no filler. Minor redundancy: 'Billed per post returned' is immediately restated by the fuller credit formula.

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 3-parameter read tool with no output schema, the description covers everything an agent needs: what is returned, where media URLs live, failure modes, cost, and how to page. Nothing material is left to inference.

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 real meaning about the user/cursor relationship: the first page resolves {user} and bills a lookup, while later pages carry the account in the cursor. That explains why both parameters coexist in a way the schema alone does not.

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 (get an account's posts with media) and immediately narrows the scope to the Media tab: own posts carrying photos, videos, or GIFs, newest first. That distinguishes it cleanly from siblings like get_x_user_posts and get_x_user_replies without needing to open 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?

Usage context is clear from the Media-tab framing and the explicit pagination instruction ('when meta.nextCursor is set, call again with cursor set to it'). It does not, however, name an alternative sibling for the unfiltered case (e.g., get_x_user_posts for all posts), so the when-not guidance 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 already cover readOnly/idempotent/non-destructive/openWorld, so the safety profile is free. The description adds the one thing annotations cannot: a concrete credit cost model (1 + 2 per profile + 1 per post), which materially affects call decisions for an agent with budget concerns. It does not mention rate limits or error surfaces beyond what the cursor schema already notes.

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, purpose front-loaded, no filler. Minor friction: '2 credits per profile returned' reads oddly for a single-account endpoint and briefly invites confusion about whether multiple profiles can come back.

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 return-shape duty and partially discharges it by referencing meta.nextCursor and pagination. Cost and paging are covered; what is still missing is whether the returned posts include replies, reposts, or media-only items, which matters given the sibling tools that specialise in those.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline would be 3. The description goes one step further by naming the output field `meta.nextCursor` and tying it to the `cursor` input — useful because there is no output schema, so the agent otherwise would not know what to feed back. The `limit` and `user` semantics are left entirely to 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?

States a specific verb and resource ('Fetch recent posts from one public X account') plus ordering ('newest first'), which is enough to distinguish it from search_x or get_x_post. It does not, however, disambiguate against close siblings like get_x_user_replies or get_x_user_media, leaving the agent to infer whether replies/retweets are included.

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 pagination loop is spelled out explicitly ('When meta.nextCursor is set, call again with cursor set to it'), which is real when-to-use guidance. But there is no guidance on when to pick this over get_x_user_replies, get_x_user_media, or search_x — the most likely sibling confusions for this endpoint.

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 annotations (which already declare a safe read), the description discloses ordering and pinning behaviour, the protected-account visibility rule behind a 404, and a detailed credit model including the extra per-page profile lookup on the first page only. That is exactly the kind of cost and failure context 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?

Purpose and ordering are front-loaded, then error semantics, then billing, then pagination — a sensible order with no filler sentences. The billing information is slightly redundant, since 'Billed per post returned' is restated in the full credit breakdown.

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 tells the agent what comes back (ordered posts with pinned post first), how to continue paging via meta.nextCursor, what a 404 means, and what each call costs. Nothing needed to invoke or iterate this tool 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 user, limit, and cursor are already fully documented, including cursor reuse rules. The description adds little parameter-level detail beyond noting that the cursor carries the account forward on later pages, which is a marginal extension over 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?

The description gives a specific verb and resource and then pins down the exact result set: 'Returns the profile's Replies tab: the account's posts together with its replies to others.' That definition lets an agent distinguish it from get_x_user_posts (posts only) and get_x_replies (replies to a single post) 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?

It gives concrete operational guidance: paginate by re-calling with meta.nextCursor as the cursor, and expect a 404 when the account is missing or protected. It stops short of naming sibling alternatives for posts-only or thread retrieval, so the agent must infer those choices from the result-set definition.

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 past the readOnly/idempotent annotations: result ordering, the meta.notFound behavior for suspended/deactivated/unknown ids, the no-charge rule for those, and the exact price model (1 credit + 2 credits per profile). Those are the cost and failure-mode facts an agent cannot get from annotations or 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?

Five short sentences, front-loaded with what it does and the primary use case, then ordering, then failure handling, then billing. Nothing is redundant with the schema or the annotations.

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, and the description compensates by disclosing the one return detail that matters (order preserved, misses in meta.notFound). For a single-parameter read tool with full annotations, no gaps remain that would cause a mis-call.

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 `ids` description already covers comma-separated, 1-100, no spaces, duplicates ignored. The prose only restates the id cardinality and adds ordering semantics, so per the high-coverage baseline this sits at 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get up to 100 public X profiles by id') with the cardinality limit baked into the first clause. That immediately separates it from the single-profile get_x_user and the name-based search_x_users without the agent opening a 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 an explicit use case — 'hydrating ids you already hold, such as post authors or followers' — which implies the boundary against search_x_users and get_x_user. It stops short of explicitly naming those alternatives or stating when not to use it, so it is clear context rather than a full routing rule.

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, idempotent, non-destructive, open-world, so the safety profile is covered. The description goes well beyond them by disclosing the 404 conditions (nonexistent or protected account and why protected accounts are invisible), the per-account billing, and the extra first-page profile-lookup charge. It stops short of describing the returned payload's fields, which keeps it off 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?

Purpose and the likely-empty caveat are front-loaded, followed by failure modes, then cost, then pagination — a sensible order. The cost sentence is dense with repeated credit figures, but each clause carries operational information an agent needs before calling.

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 tells the agent what to expect back (profiles plus meta.nextCursor) and how to continue pagination. Failure modes, cost, and pagination are all covered for a three-parameter read tool, leaving nothing material unstated.

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 genuine meaning: `user` is resolved via a billed profile lookup on the first page, and `cursor` carries the resolved account so later pages skip that charge. That cost-coupled behavior of the cursor parameter is not visible in 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?

States a specific verb and resource — the creators an X account pays to subscribe to — and adds the qualifying condition that hidden subscriptions are omitted. This is distinguishable from adjacent siblings like get_x_user_following or get_x_user_affiliates 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?

It sets expectations ("Often empty") and explains when to call again with the cursor, which is real usage guidance. However, it never routes the agent between this tool and alternatives such as get_x_user_following or get_x_user_affiliates, so the choice is left to inference from the tool name.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact: reads consume no credits. However it repeats that fact twice and says nothing about result volume, whether an empty monitor returns an empty list, or whether results accumulate across runs.

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 short and front-loads the core fact (what is returned, ordering). But the second and third sentences say the same thing ("Reading results is free" / "Free: costs no credits"), so one of three sentences is pure duplication and the freed space could have carried the run-vs-monitor id clarification.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter read tool with full schema coverage, complete annotations and no output schema, the definition is minimally viable. It still leaves an agent guessing whether the id refers to a monitor or a run, and how results relate to list_monitor_runs, which is the one question a caller of this tool actually has.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both id and limit documented inline (including default 25 and max 100), so the baseline of 3 applies. The description adds nothing beyond the schema about the id parameter — notably it does not clarify that the id is a monitor id rather than a run id, which is the main ambiguity for this tool.

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 identifies the resource returned ("items a monitor has found") and the ordering (newest first), which lets an agent distinguish it from monitor-definition tools like list_monitors or get_monitor. It lacks an explicit verb (list/get) and never names the closest siblings, list_monitor_runs or get_monitor_run, so the differentiation is only partial.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to call this versus list_monitor_runs (runs vs. items) or get_monitor_run, and no prerequisites such as needing a monitor id that has already completed a run. The only guidance offered is a cost note ("Reading results is free"), which is pricing information rather than usage selection guidance.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description's main value is disclosing that runs are free and cost no credits, plus the general content of each run. It does not discuss pagination or ordering, but it adds meaningful cost and payload context 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 compact sentences with the payload summary front-loaded and the cost note second. Every phrase contributes useful information with no wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description appropriately characterizes the returned run data as timing, findings, and cost. Combined with rich annotations and a simple two-parameter schema, it is nearly complete, though it could mention result ordering or pagination behavior.

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 and limit parameters are already fully documented in the schema. The description adds no parameter-specific syntax or constraints, which is acceptable given the schema's completeness but warrants the baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource as a monitor's recent runs and summarizes the returned fields: when each ran, what it found, and cost. It does not explicitly contrast with the singular sibling get_monitor_run, so sibling differentiation is only implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this versus get_monitor_run or list_monitor_results. The word 'recent' weakly implies a listing use case, but no alternatives or exclusions are 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 already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds information the annotations do not carry: the operation is free/costs no credits, and it discloses what each returned record contains. It does not mention result-set size limits or ordering, which is the remaining gap.

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 clauses with zero filler: the first front-loads what the tool returns, the second front-loads the cost characteristic. Nothing is repeated from the schema or annotations.

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 zero-required-param read with full annotation coverage and no output schema, the description supplies the two things structured fields cannot: the shape of each returned record and the credit cost. Only pagination behavior across the limit boundary is unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With a single optional parameter and 100% schema description coverage, the schema fully documents 'limit' (min 1, max 100, default 25). The description adds nothing about paging or how to enumerate beyond 100 monitors, 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?

Names the resource (the account's saved monitors) and enumerates the per-item fields returned — what it watches, schedule, status, last run — so an agent knows this is an inventory listing. It is implicitly distinct from get_monitor (single) and list_monitor_runs/results, but never names those siblings explicitly, so differentiation is left to inference.

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 by the plural, inventory-style phrasing; there is no explicit statement of when to call this versus get_monitor for one monitor or list_monitor_runs for execution history. An agent can infer the role from the name, but the description does no routing work.

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 substantial context beyond annotations: missing items surface in `meta.missing` with specific id formats, NSFW content is not filtered, and the credit cost model is broken out per item type. These are exactly the non-obvious behaviors an agent needs before calling.

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 batch capability, then return semantics, then cost. Dense but each sentence carries information; the cost breakdown is longer than ideal but operationally relevant.

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 does explain the failure surface (meta.missing) and the cost model. It could say more about the shape of returned post/comment objects, but for a batch getter the essential calling information is present.

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 accepted formats (ids, t3_/t1_ fullnames, URLs, permalinks) are already documented per-parameter. The description reinforces this with 'Accepts the links people actually paste' and the share-link refusal, but adds little 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?

States a specific verb (fetch) and precise resources with caps (up to 100 posts/comments, 100 communities) in one call. This clearly distinguishes it from single-item siblings like get_reddit_post or get_reddit_comments and from search_reddit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Current state of items you already know about... in one request instead of one per item' tells the agent this is a batch-hydration tool for known ids/links, which implicitly excludes discovery use cases handled by search_reddit. It stops short of explicitly naming the alternative tools.

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

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

Annotations already cover safety (readOnly, non-destructive, idempotent, open world), and the description still adds genuinely new behavior: a cost model ('1 credit + 3 credits per post returned'), field names and an edge case ('score (can be negative)'), and the pagination contract with meta.nextCursor. That is exactly the kind of context annotations cannot express.

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 tight sentences covering purpose, use cases, return shape, cost, and pagination, with the purpose and exclusion front-loaded. No sentence is redundant with the annotations or 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?

Even without an output schema, the description enumerates the returned fields and the meta fields that drive paging and NSFW omission, discloses per-result pricing, and routes to the X equivalent. An agent has everything needed to call this correctly and interpret the response.

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 earns above that by tying limit to economics ('you pay per result' is in the schema, but '3 credits per post returned' here makes the tradeoff explicit) and by clarifying subreddit is 'without r/'. Sort/time/includeNsfw semantics are left entirely to the schema, which is acceptable given full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search public Reddit posts by keyword') plus the scope modifier ('optionally inside one subreddit'). It also explicitly names the cross-platform sibling it is not ('Reddit only: search X separately with search_x'), so an agent can route without opening a 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 ('opinions, complaints, recommendations and launch feedback') and an explicit exclusion with the alternative ('search X separately with search_x'), plus pagination guidance via meta.nextCursor. It does not, however, distinguish itself from the Reddit-side lookalikes (search_subreddit, get_subreddit_posts), which is the one routing ambiguity left open.

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 read-only, idempotent, non-destructive, open-world behavior. The description adds valuable context beyond that: a concrete cost model ("1 credit + 3 credits per post returned") and pagination continuation behavior via meta.nextCursor. It does not cover auth expectations or result ordering defaults, but the core operational traits are disclosed.

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: purpose first, the search_reddit comparison and use condition second, then cost and pagination. No wasted clauses, and the most important scoping information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only search tool with rich annotations, 100% schema coverage, and no output schema, the description supplies the missing operational details an agent needs: cost implications and cursor-based pagination. Nothing essential to correct invocation 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 every parameter is already documented in the schema. The description only adds a high-level "Same fields as search_reddit" reference and pagination guidance, not per-parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ("Search public posts inside one subreddit") and explicitly scopes it against siblings by saying it uses the same fields as search_reddit but applies when the community is already known. An agent can distinguish this from search_reddit and search_subreddits immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit decision rule: use this when the subreddit is known, implying search_reddit when it is not. It also instructs exactly what to do for pagination ("When meta.nextCursor is set, call again with cursor set to it"), leaving nothing 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely new behavior: a cost model ('1 credit + 1 credit per subreddit returned') and the pagination contract ('When meta.nextCursor is set, call again with cursor set to it'). It stops short of describing result ordering or what an empty result looks like, but the costly/stateful aspects are disclosed.

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 purpose, then routes to the alternative, then covers cost and pagination. Every sentence carries information, though the cost and cursor sentences are dense and could be split for scanability.

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 carries the return-value burden; it names member counts, `meta.nextCursor`, and the pagination model, which covers what an agent needs to loop correctly. Cost and pagination are covered, but the shape of individual result items is only partially implied.

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 earns above that by spelling out the concrete pagination loop with `cursor`, which the schema only describes abstractly as opaque and bound to other params. It adds nothing on `sort`, `limit`, or `includeNsfw`, but those are fully documented in 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?

States a specific verb and resource ('Find communities by name or topic') and clarifies the matching surface ('name or description matches') plus what comes back ('member counts'). It separates itself from in-community post search, but never distinguishes itself from the sibling `search_reddit` / `search_subreddit` / `lookup_reddit` tools, so one ambiguity remains.

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 ('find where a topic is discussed before reading or watching those communities') and names the condition that should route elsewhere ('To search *posts* inside one community, use ... instead'). There is no guidance on when to prefer it over `search_reddit`, but the primary workflow is 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 already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered; the description earns credit for adding the cost model ("1 credit + 1 credit per post returned") and pagination protocol ("When meta.nextCursor is set, call again with cursor set to it"). It also warns that count fields can be null, which prevents a null-vs-zero misreading. Rate limits and failure modes beyond cursors are not covered.

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 dense sentences that are front-loaded with purpose, then constraints, then return shape, then cost, then pagination — a sensible order for a 25-parameter tool. Every clause carries an operational fact; nothing restates the title or annotations.

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 text, author object, count fields (with nullability), createdAt and url. Combined with the cost and cursor-resume instructions, an agent has enough to call this correctly and loop through pages without further reference.

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 88%, so the baseline is 3 and the schema already explains most filters. The description adds real meaning the schema cannot express per-parameter: the cross-field requirement that one of six seed parameters must be supplied, plus the naming of the filter families an agent should consider (fromUsers, mentions, hashtags, language, minLikes, since/until, onlyOriginal).

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 plus resource ("Search public X (Twitter) posts") and immediately names the sibling it is not ("X only: search Reddit separately with search_reddit"). An agent can separate it from search_reddit, get_x_posts and search_x_users 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?

States a hard precondition ("at least one of query, phrase, hashtags, fromUsers, toUsers or mentions is required") and routes to the alternative platform tool, which is exactly the kind of when/when-not context that matters here. It stops short of saying when to prefer this over get_x_user_posts or get_x_posts for known-account timelines, so it is not a 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?

Goes well beyond the readOnly/idempotent/openWorld annotations by disclosing billing ('1 credit + 1 credit per user_result returned') and pagination mechanics. It does not cover rate limits, auth requirements, or error behavior beyond what the schema already states for cursors, 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?

Front-loaded with purpose and use case, then cost and pagination — a sensible order. The final sentence about calling again with cursor partially restates both the opening pagination sentence and the schema's cursor description, which is mild 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?

With no output schema, the description usefully names the return channel (meta.nextCursor) and the per-result billing model. It does not describe what fields a returned account carries, leaving a small gap, but an agent has enough to invoke and paginate 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 query, limit, and cursor are already fully documented. The description adds only the ranking semantics of the query and the fact that results are billed per account; it does not enrich individual parameter meanings beyond 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 and resource (search X accounts) plus a precise scope: name, username, or bio matching, ranked by X's people search. It also implicitly distinguishes itself from the lookup siblings by framing its job as converting a person/brand name into a username before calling 'the other account endpoints'.

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 use case ('turn a person or brand name into a username before calling the other account endpoints'), which is strong routing guidance against get_x_user/get_x_users. It does not explicitly state when not to use it (e.g., for direct handle lookups), so it stops short of full exclusion guidance.

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