Simple Notify MCP provides 8 tools with generally clear purposes and reasonable descriptions. However, there are significant gaps in parameter documentation, missing output schema documentation, and inconsistent schema completeness. Tool naming is action-verb based (notify, speak, status, setup_web_*) which is good. Descriptions are present but vary in quality, some lack operational detail. Parameter schemas are defined using Zod with type constraints and enums where appropriate, but descriptions for individual parameters are sparse in the visible source. No tool annotation hints (readOnlyHint/destructiveHint/idempotentHint) are present. Error handling exists but lacks recovery guidance. The composition is reasonable (each tool has one clear job), but output schemas are not documented for LLM consumption.

• Document output schemas for all tools. Create a mapping of what each tool returns (e.g., 'status returns {version, hasTts, hasTelegram, missingConfig, ttsProvider, ttsJobs, telegramUpdateOffset, telegramMediaUpdateOffset}') and include this in tool descriptions or a separate schema document.
• Add tool annotation hints via the MCP SDK. Mark notify, notify_photo, speak, setup_web_start, setup_web_stop as destructiveHint: true (they modify external state). Mark notify_read and notify_read_media with a custom annotation explaining that advanceCursor=true has side effects.
• Enhance error responses with recovery guidance. Instead of errorResponse(err), return structured errors like {isError: true, content: [{type: 'text', text: '<error message>. <actionable next step>'}]}. E.g., 'Telegram not configured. Call setup_web_start to set up credentials.'
• Add detailed parameter descriptions to 'speak' tool explaining TTS provider behavior (provider selected from config, falls back to system TTS, playback is queued).
• Document the status tool's output fields explicitly in its description: returns server version, TTS availability, Telegram configuration state, job counts, and cursor positions.
• Clarify the advanceCursor behavior in notify_read and notify_read_media descriptions: 'If true (default), advances the internal offset so subsequent calls fetch new updates. If false, fetches the same updates again, useful for peeking without committing.'
• Consider adding a 'get_tts_providers' discovery tool. Currently agents cannot know which TTS providers are available without calling status. A dedicated discovery tool would follow the pattern of list_* tools.