ha-mcp defines 9 tools with consistent naming (verb_noun pattern: ha_get_*, ha_call_*, ha_list_*) and reasonable descriptions (avg ~120 chars). All tools have input schemas with Zod validation. However, parameter descriptions are minimal (often single phrases like 'Entity identifier'), output schemas are undocumented (responses wrapped in generic text content), and error handling lacks recovery guidance. No tool annotations (readOnlyHint/destructiveHint). Schemas are present but sparse, most parameters lack format/range constraints. This is solid for a domain-specific tool but falls short of production-grade patterns.

• Document output schemas for all tools. Example: ha_get_states returns [{entity_id: string, state: string, name?: string}, ...]. Include field types, required vs optional, and pagination info if applicable.
• Expand parameter descriptions to include format, range, and valid values. E.g. 'domain: Service domain (string, e.g. light, climate, automation; see ha_get_config for loaded components)' instead of just 'Service domain (e.g. 'light', 'climate')'.
• Add tool annotations: mark ha_call_service with destructiveHint=true; mark all ha_get_* and ha_list_* with readOnlyHint=true. This signals to agents which operations are safe to retry.
• Implement early input validation with actionable error messages. Validate domain/area/entity_id against HA state before calling REST API. Return 'Invalid domain: got "foo", must be one of: light, sensor, climate, ...' to enable LLM self-correction.
• Enhance error responses with recovery guidance. E.g. 'Entity not found: light.kitchen_lights. Try ha_get_states(domain="light") to list available lights.' This guides agents toward recovery without extra discovery calls.