The Reddit Browser MCP server defines 9 read-only tools with consistent verb_noun naming (search_reddit, get_subreddit_info, get_top_posts, etc.). All tools have descriptions and basic input schemas with type definitions. However, the implementation shows critical gaps: (1) Output schemas are completely undocumented, no return types, field lists, or structure guidance are visible in the source. (2) Parameter descriptions, while present, often lack specificity, many refer to 'default' or 'max' values without explaining what the tool actually returns or when to use it vs. alternatives. (3) Error handling is missing, no guidance on what happens on invalid input, rate limiting, or authentication failure. (4) No tool annotations (readOnlyHint, idempotentHint) despite all tools being read-only. (5) The descriptions are generic and do not mention prerequisites or use cases. Example: 'search_reddit' has a 3-sentence description but does not explain what fields are returned, how results are ranked, or what happens if no matches exist. Per-tool analysis: 6 tools score 55 - 65 (basic schema + weak description), 3 tools score 45 - 55 (schema present but minimal context). Average: 58.

• Add explicit output schema documentation to every tool. For each tool, document the return type (object, array of objects), field names, types, and what data each field contains. Example for search_reddit: 'Returns: Array of post objects, each with id (string), title (string), author (string), score (integer), created_utc (ISO 8601 timestamp), subreddit (string), url (string). Maximum 100 posts per call.'
• Add readOnlyHint and idempotentHint annotations to all 9 tools. Since all are read-only, annotate each tool in the MCP protocol layer as idempotent and read-only so agents know they can safely retry without side effects.
• Enhance parameter descriptions with use-case context. Replace 'Number of results to return (default: 10, max: 100)' with 'Maximum number of posts to return per call. Use 10-20 for quick summaries, 50-100 for comprehensive research. Results ordered by relevance (search) or recency/popularity (browse).'
• Document error scenarios in tool descriptions. Add a note like: 'Errors: Returns 404 if subreddit does not exist; returns 429 if rate-limited (retry after 60 seconds); authentication fails if Reddit credentials are expired (server will refresh automatically).'
• Implement pagination uniformly. All browse tools (get_top_posts, get_hot_posts, get_new_posts) should accept both limit and after/before cursor parameters to enable stateless pagination across large result sets.
• Add context-switching hints in tool descriptions. Document which tool to use for different intents: 'Use search_reddit to find posts by keyword. Use get_top_posts for most-upvoted content in a subreddit. Use get_hot_posts for trending content right now. Use get_new_posts for latest content regardless of votes.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry