The server registers 4 tools with explicit schemas and descriptions visible in internal/mcp/tools.go. Tool naming follows verb_noun convention (send_notification, check_messages, list_history, mark_read). All tools have descriptions between 100-150 characters. Input schemas are properly structured with JSON Schema format, type definitions, and descriptions for all parameters. However, there are significant gaps: (1) output schemas are NOT documented, the code defines SendNotificationOutput and other structs but these are never declared in the MCP tool registration, leaving LLMs without knowledge of return fields; (2) parameter descriptions lack constraint details (e.g., 'priority' says '-2 (lowest) to 2 (highest)' in the tool def but should also include validation guidance); (3) no error handling guidance, LLMs do not know what to do if the Pushover API is unreachable or credentials fail; (4) no idempotency or retry guidance for the write operation (send_notification); (5) resource composition is minimal, tools do not explicitly guide multi-step workflows (e.g., 'check messages, then optionally mark_read'). The server is functional but lacks production-grade documentation and error recovery patterns.

• Add output schema documentation to all 4 tools. Explicitly declare return fields (message, title, device, priority, request_id, receipt, logged, warning for send_notification; etc.). Use JSON Schema format similar to input schemas. This enables LLMs to plan downstream operations and extract required IDs for chaining.
• Enhance error handling in tool handlers. Wrap Pushover API errors and database errors with actionable recovery hints. E.g., 'Pushover API unreachable. Retry in 10 seconds or check network connectivity.' Return structured error objects with error_code, message, and suggestion fields.
• Add explicit WRITE/REVERSIBLE risk flags to tool descriptions. Prepend 'send_notification' description with '[WRITE] Sends notification to external service, cannot be undone.' Prepend 'mark_read' with '[REVERSIBLE] Deletes unread messages, action cannot be reversed.' This signals to LLMs to ask for confirmation before executing.
• Specify valid values and formats for constrained parameters. For 'sound', list valid Pushover sound IDs or state that any string is accepted and invalid values will error. For 'since', document that it accepts ISO 8601, RFC 3339, or natural language (e.g., 'yesterday', '1 week ago') and provide 2 - 3 examples.
• Document pagination and result limits. In 'check_messages' and 'list_history' descriptions, explicitly state: 'Returns up to [limit] results (default 20, max 100). Use limit parameter to control result size. For very large histories, use the since filter to narrow the date range.'