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

Annotations only say readOnlyHint=true and idempotentHint=true, which is safe but minimal. The description adds crucial behavior: paging via 'after' token, case-sensitivity of subreddit names, error handling for invalid timeframe/sort combos (400), and an approximate response size ('about 18 KB for 24 posts'). These go well beyond the structured 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?

Four concise sentences, each earning its place: function, output fields, sort values + critical constraint, and alternatives. The most important constraint (timeframe with sort=top) is emphasized with 'Important:'. No filler or repetition.

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 5-parameter tool with only one required, the description covers the key operational details: paging, sort options, the error case, case-sensitivity, response size, and routing to sibling tools. Since an output schema exists, it correctly avoids restating return values. An agent has everything needed to call this correctly.

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 100% with per-parameter descriptions, so baseline is 3. The description adds value by explaining the paging mechanism ('with an after token to page'), the error condition for timeframe (already in schema but reinforced), and the size estimate. It does not redundantly repeat each parameter's description but provides contextual meaning beyond the schema.

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 a clear verb-resource pair: 'Returns the post stream of one subreddit with an after token to page.' It also distinguishes itself from sibling tools by explicitly naming get_reddit_subreddit_search and get_reddit_subreddit_details for alternative uses, and ties its output fields to get_reddit_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?

Explicitly states when to use alternatives: 'To search inside the same subreddit use get_reddit_subreddit_search, and for its metadata use get_reddit_subreddit_details.' Also gives a hard constraint: 'timeframe is only accepted together with sort=top, and any other combination returns 400 rather than ignoring the parameter.' No ambiguity remains.

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