Discourse-mcp has 11 tools with consistent naming (verb_noun pattern: search_*, get_*, add_*, remove_, list_) and reasonable descriptions (avg ~80 chars). However, parameter descriptions are sparse or missing entirely. Most tools lack documented output schemas. Error handling is minimal, no recovery guidance or actionable error messages visible in source. Tool composition is sound (single responsibility), but parameter validation and constraint documentation are weak. No tool annotations (readOnlyHint/destructiveHint) despite clear risk classifications in metadata.

• Add output schema documentation to every tool. Example: 'Returns: {stories: [{id: int, title: str, points: int, url: str, comments: int}], total: int}'.
• Expand parameter descriptions with constraints and examples. E.g., 'time_range: Filter results by recency. Valid: day|week|month|year|all. Default: all.' and 'limit: Max results to return (1 - 100, default 20).'
• Implement error handling with actionable recovery messages. E.g., 'API rate limit exceeded. Retry in 60 seconds.' or 'Invalid query: must be 1 - 200 chars. Got: "<query>"'.
• Add tool annotations via FastMCP's @mcp.tool decorator or Annotated metadata. Mark read-only tools with readOnlyHint=true; mark watchlist mutations with destructiveHint=true.
• Document pagination and result limits in tool descriptions. E.g., 'Returns up to 50 results per call. Use offset/limit for pagination.' Include total_count in responses to enable agent planning.

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

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