topgg-mcp demonstrates solid tool design with consistent naming (verb_noun pattern), comprehensive parameter descriptions, and proper schema validation via Zod. All 8 tools have clear descriptions (avg ~150 chars) and typed input schemas. However, output schemas are not documented in the visible code, responses are wrapped generically as text content without structured field definitions. Error handling is present but minimal (wrapError catches TopggApiError and generic Error, returns text only). No tool annotations (readOnlyHint/destructiveHint) despite clear risk classifications. Parameter descriptions are thorough but could benefit from constraint examples (e.g., locale codes, character limits). The project parameter is well-designed for multi-token scenarios.

• Document output schemas for all tools. E.g., get_project should specify returned fields (id, name, description, stats, etc.) with types. Use JSDoc or inline schema comments.
• Add tool annotations: mark get_project, get_votes, check_user_vote with readOnlyHint=true; mark update_project, register_commands, post_metrics, post_metrics_batch, create_announcement with destructiveHint=true.
• Enhance error handling: categorize TopggApiError by HTTP status (4xx=user-fixable, 5xx=retryable, 429=rate-limited); return structured error objects with {code, message, suggestion, retryable} instead of plain text.
• Add dry-run support to destructive tools (update_project, register_commands, post_metrics, create_announcement) via optional dry_run=true parameter. Return what would change without committing.
• Enumerate valid locale codes in update_project description or link to Top.gg docs. Specify SlashCommandSchema structure in register_commands description so LLMs understand command field requirements.