The ZigBee2MQTT MCP server has 10 tools with complete JSON Schema definitions and descriptions visible in src/mcp-server.ts. Strengths: all tools follow verb_noun naming (list_*, get_*, send_*, find_*); all have non-empty descriptions (average ~120 chars); all input schemas are properly structured with required fields marked. Weaknesses: descriptions are generic and lack WHEN/WHY guidance for LLM tool selection; the critical send_command tool accepts 'command' as an untyped object with only an example in description, not a schema, this invites hallucinated payloads; parameters lack format constraints (e.g., 'days' in get_recent_devices is unbounded); output schemas are not documented anywhere in the visible code; no error handling guidance; no mention of idempotency or safety properties; no pagination strategy documented for list_devices (could return unbounded results); command parameter in send_command lacks enum or structured constraint. Most tools are READ_ONLY which is good, but send_command (WRITE) has weak input validation story. The server shows competent basic structure but lacks the depth of LLM-facing guidance that production tools require.

• Replace 'command' parameter type 'object' with a structured schema. Document valid command keys per device capability (e.g., {"state": "ON"|"OFF"} for on_off devices, {"brightness": 0-254} for dimmable lights). Use pattern constraints or enums.
• Document output schemas for all 10 tools. Specify returned fields, types, and structure. E.g., list_devices returns [{name: string, ieee_address: string, model: string, status: string, ...}]. Include example output.
• Add pagination to list_devices and find_devices. Accept 'limit' (default 20, max 100) and 'offset' or 'cursor' parameters. Return total_count or next_cursor so LLM knows whether more results exist.
• Expand descriptions to 50-200 chars with explicit WHEN/WHY guidance. Example: get_device_info: 'Fetch all fields, capabilities, and endpoints for a single device. Use when you need detailed spec; prefer get_device_state for just current values (e.g., on/off, brightness).'
• Add bounds and enums. E.g., days: {type: 'number', description: 'Days to look back (1-365)', minimum: 1, maximum: 365, default: 7}.
• Add error recovery guidance to tool descriptions. E.g., 'If device not found, call find_devices() to search by name or model.' This teaches LLM self-correction patterns.
• Document send_command idempotency and side effects. E.g., 'Sending {"state": "ON"} twice is safe (idempotent). Sending {"brightness": +10} twice may increase brightness twice (not idempotent).'
• Add permission/scope declarations. E.g., send_command requires 'write:zigbee'; all read tools require 'read:zigbee'. Enables least-privilege agent config.

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

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