search_subreddits

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable caveats about data freshness ('subscriber counts lag reality') and warns against reporting placeholder values. However, the second caveat about score/num_comments appears misplaced for a subreddit search tool, causing some confusion.

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 concise and front-loaded with purpose, but the second caveat about posts/comments is tangential and detracts from focus. Still, the core message is clear and efficiently stated.

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 13 parameters and no output schema, the description covers the purpose and important data-freshness caveats, but does not describe return format (markdown default) or additional behavior. The misplaced caveat slightly reduces completeness, but overall it is adequate for basic usage.

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 every parameter is already documented in the schema. The tool description only maps high-level criteria (name, prefix, subscribers, age) to parameters but does not add new meaning beyond the schema, which serves as the 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 states 'Find subreddits by name, prefix, subscriber count or age' with a specific verb and resource, clearly distinguishing it from sibling tools that search posts or comments. This makes the tool's purpose immediately clear.

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 for subreddit lookups vs. posts/comments, but does not explicitly say 'use this instead of search_posts/search_comments'. The context from sibling names provides implicit guidance, but there are no stated exclusions or alternatives.

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