search_reddit

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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