discord-mcp has 13 tools with consistent naming (verb_noun pattern: get_, list_, send_, edit_, delete_, pin_, add_, remove_). All tools have descriptions (avg 65 chars, baseline 194 chars, below target). Input schemas are present and properly typed for all tools. However, parameter descriptions are minimal (e.g., 'Server ID', 'Channel ID') and lack context about constraints, formats, or when to use each tool. Output schemas are not documented, LLMs cannot predict response structure. Error handling exists (McpError with ErrorCode) but lacks recovery guidance. No tool annotations (readOnlyHint, destructiveHint) despite clear risk stratification (READ_ONLY, WRITE, REVERSIBLE, DESTRUCTIVE). Missing pagination guidance for list_* tools and get_messages.

• Document output schemas for all tools. For list_* tools, specify: returns array of objects with fields [id, name, ...], total count, and pagination cursor. For get_messages, document the formatMessage() output structure (id, author, content, timestamp, attachments, embeds, reactions, pinned, thread).
• Expand parameter descriptions to 50 - 100 chars with format/constraint guidance. E.g., 'limit: Number of messages to fetch (1 - 100, default 20). Use with before/after to paginate through history.' for get_messages.
• Add tool annotations to the ListToolsRequestSchema response. Mark send_message, send_embed, edit_message, delete_message, pin_message, add_reaction, remove_reaction with appropriate destructiveHint or idempotentHint flags so agents understand safety properties.
• Enhance error messages with recovery guidance. When a channel_id is invalid, catch the 404 and return: 'Channel not found. Call list_channels(guild_id) to see available channels.' This enables agents to self-correct without dead-ending.
• Add dependency hints to tool descriptions. E.g., 'get_guild_info: If you only have a server name, call list_guilds() first to find the guild_id.' This guides multi-step planning and reduces wasted calls.