Search Reddit

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

With no annotations provided, the description must disclose behavior. It notes that search is literal keyword matching, which is helpful to avoid semantic overreach, and it mentions that results are structured JSON. It does not disclose pagination, rate limits, or how the time/sort filters interact. While it adds some value, the absence of edge-case details prevents a higher score.

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

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

The description is two sentences, with the purpose and return format front-loaded. Every clause adds value, and there is no fluff. The guidance about literal search is brief but useful.

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?

The tool has 11 parameters, some complex (searchComments, includeCommentThreads). The description covers the overall function and the core behavior of returning matching posts. However, it does not explain how time and sort interplay, nor does it warn about the multiplicative behavior of includeCommentThreads beyond the schema's note. Since there is no output schema, a bit more detail on the response structure would be useful, but the description already lists the fields in the JSON, so the score is good.

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 64%, leaving several parameters (sort, time, maxPosts, includeNsfw, maxCommentsPerPost) undocumented in the schema. The description explicitly explains that queries are literal and short, and it confirms that returning JSON includes the listed fields. This compensates for the missing schema descriptions, but not all undocumented parameters are explicitly explained in the description (e.g., sort/time are not explained), keeping it from a 5.

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 starts with a specific verb ('search') and a clear resource ('Reddit'), and specifies that it returns structured JSON with a list of fields. It also distinguishes from siblings by mentioning 'keyword search' versus their likely scraping functions. This is clear and differentiates the tool from scrape_reddit_urls and scrape_subreddit.

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 lists concrete use cases (brand monitoring, lead generation, etc.) and explains that search is literal, so short terms are better than sentences. It also limits to searching inside one subreddit, which aligns with the subreddit parameter)Skip. However, it does not explicitly contrast with the sibling scraping tools, but the use cases and keyword nature implicitly suggest when to use this tool over scraping.

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