get_top_posts

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

Beyond the readOnlyHint annotation, the description adds meaningful behavior: it is read-only, works anonymously, returns a page of posts with specific fields, and provides an 'after' cursor for pagination. It also notes the credential requirement when no subreddit is provided. 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?

The description is compact and front-loaded with the core action and scope, then adds return-format and sibling differentiation in just three sentences. Every sentence contributes value with no repetition of schema details.

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 moderately simple tool with no output schema, the description provides enough context: it names the returned fields, explains pagination via 'after', notes authentication behavior, and covers alternative tools. Annotations and full schema coverage support this, leaving no major operational gap.

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 input schema covers all 4 parameters with descriptions, so the baseline is 3. The tool description adds minimal extra parameter meaning beyond restating that time_filter is a window and that omitting subreddit switches to home feed; it does not materially enrich schema semantics.

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 top-scoring posts from a subreddit...'), defines the optional home-feed target, and distinguishes itself from browse_subreddit and search_reddit. It clearly scopes the tool to the 'top' sort and is not a tautology.

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 says this is a shortcut for the 'top' sort and directs users to browse_subreddit for other sorts and search_reddit for keyword search. It also clarifies that omitting subreddit uses the authenticated home feed, giving clear when-to-use and when-not-to-use context.

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