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

Beyond the readOnly/openWorld annotations it discloses credit costs, that repeat requests may re-purchase data, that upvote_ratio and subreddit_subscribers come back null, and that pagination uses an after token. The cost text is internally contradictory ('at least 10 Nexscope credits' vs '1 credit per request'), which undercuts an otherwise strong disclosure.

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

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

The core facts are front-loaded, but the tail is bloated with duplicated marketing copy: the upvote_ratio/null caveat appears twice, and the pasted pricing block repeats and contradicts itself. Several sentences do not earn their place and dilute the parameter guidance.

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

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

With no output schema, the field inventories for post and comment results are genuinely necessary and present. Cost behavior, pagination, and the null-field caveats round it out. Only the cursor/after naming gap and the ambiguous pricing keep it from full marks.

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 only 33%, but the description compensates well: it explains filter values and the default, which sort modes work for comments, that timeframe is post-only, and what trim does. The one mismatch is that it calls the pagination parameter an 'after token' while the schema names it 'cursor', which could confuse an agent.

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 opening sentence states a specific verb and resource ('Searches across all of Reddit for posts or comments'), and the filter description clarifies the two search modes. An agent can immediately tell this apart from the detail-oriented siblings like social_reddit_post_detail or social_reddit_subreddit_search.

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 routing guidance: set filter to posts or comments, sort options differ per mode ('Comment searches support relevance, new, and top sorting'), and timeframe only applies to post searches. It also names the escape hatch for missing data ('pass the post URL to /v1/reddit/post'). It stops short of explicit when-not-to-use framing or naming sibling tools directly.

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