deCONZ MCP provides 23 tools with consistent naming (verb_noun pattern: get_*, set_*, create_*, delete_*, rename_*) and complete input schemas. All tools have descriptions (avg ~80 chars, within baseline 34-392). However, output schemas are undocumented, responses are not formally specified, forcing LLMs to infer structure. Parameter descriptions are minimal (often 1-2 sentences) and lack actionable constraints (ranges, enums, formats). Error handling is absent from tool definitions. No tool annotations (readOnlyHint, destructiveHint) despite clear risk stratification (READ_ONLY, WRITE, DESTRUCTIVE). Missing idempotency guidance for retry-safe operations.

• Add output schema documentation to every tool. For get_lights, specify: returns array of {light_id: string, name: string, state: {on: boolean, bri: 0-254, ...}, type: string, ...}. Include field types and ranges.
• Implement tool annotations: mark get_* tools with readOnlyHint=true; mark delete_* and set_* tools with destructiveHint=true or idempotentHint=true as appropriate. This enables agents to reason about safety.
• Add parameter constraints to descriptions. E.g. 'bri: Brightness (0-254, integer)' and 'effect: Light effect (enum: colorloop, none)'. Replace free-form descriptions with formal constraints.
• Document error scenarios and recovery paths. E.g. 'If light_id is invalid, returns 404 with message "Light not found". Try get_lights() to list valid IDs.' This guides agent retry logic.
• Add pagination support to list tools: accept limit (default 20, max 100) and offset parameters; return total_count and next_offset in response. Document in tool descriptions.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry