Discord-mcp defines 8 tools with explicit schemas and descriptions. Naming follows verb_noun convention (list, create, edit, delete, send, read). Descriptions are present but brief (avg 45 chars, below 194-char baseline). All tools have input schemas with types and descriptions. However, output schemas are not documented, LLMs cannot predict return structure. Parameter descriptions lack format constraints (e.g., 'limit: number' should specify 'max 100'). No error handling guidance. No tool annotations (readOnlyHint, destructiveHint). Risk classification exists in metadata but not exposed to LLM. Missing idempotency and retry guidance for write operations.

• Document output schemas for all tools. Example: 'Returns {id: string, name: string, type: string, parentId: string|null, position: number}' for channels/list. This enables agents to chain operations.
• Add tool annotations to tool definitions. Mark channels/delete and messages/send with destructiveHint=true; mark server/list and messages/read with readOnlyHint=true. Use MCP SDK's tool annotation API.
• Add format constraints to numeric parameters. For messages/read limit, specify '1-100 (default 20)'. For channels/edit slowmode, specify '0-21600 seconds (0 disables)'.
• Implement error recovery guidance. Replace 'Guild not found' with 'Guild not found. Verify guild_id is correct. Call server/list to see available servers.' This guides agent self-correction.
• Add a confirmation step for destructive operations. Implement channels/delete_confirm(channel_id, reason) → {confirmed: boolean, message: string} before actual deletion. Or return {status: 'pending_confirmation', action_id: '...'} and require a separate confirm_action(action_id) call.