tools.json

[
  {
    "name": "ha_call_addon_api",
    "title": "Call Add-on API",
    "description": "Call an add-on's HTTP or WebSocket API.\n\nSends requests directly to add-on containers. Use `websocket=true` for\nstreaming endpoints (e.g., ESPHome compile/validate). Use `port` to bypass\nNginx IP restrictions on community add-ons. Use ha_get_addon(slug=\"...\")\nto discover available ports and endpoints.\n\n**Examples:**\n- HTTP: ha_call_addon_api(slug=\"...\", path=\"/api/events\")\n- Direct port: ha_call_addon_api(slug=\"...\", path=\"/flows\", port=1880)\n- WebSocket: ha_call_addon_api(slug=\"...\", path=\"/validate\", port=6052, websocket=true, body={\"type\": \"spawn\", \"configuration\": \"device.yaml\"})",
    "inputSchema": {
      "properties": {
        "slug": {
          "type": "Annotated[str, Field(description=\"Add-on slug (e.g., 'a0d7b954_nodered', 'ccab4aaf_frigate'). Use ha_get_addon() to find installed add-on slugs.\")]"
        },
        "path": {
          "type": "Annotated[str, Field(description=\"API path relative to the add-on root (e.g., '/flows', '/api/events', '/api/stats').\")]"
        },
        "method": {
          "type": "Annotated[str, Field(description='HTTP method: GET, POST, PUT, DELETE, PATCH. Defaults to GET.', default='GET')]",
          "default": "GET"
        },
        "body": {
          "type": "Annotated[dict[str, Any] | str | None, Field(description='Request body for POST/PUT/PATCH. Pass a JSON object or JSON string.', default=None)]",
          "default": null
        },
        "debug": {
          "type": "Annotated[bool, Field(description='Include diagnostic info (request URL, headers sent, response headers). Default: false.', default=False)]",
          "default": false
        },
        "port": {
          "type": "Annotated[int | None, Field(description=\"Connect to this port instead of the Ingress port. Use ha_get_addon(slug='...') to find available ports.\", default=None)]",
          "default": null
        },
        "offset": {
          "type": "Annotated[int, Field(description='HTTP only. Skip this many items in a JSON array response. Default: 0.', default=0)]",
          "default": 0
        },
        "limit": {
          "type": "Annotated[int | None, Field(description='HTTP only. Return at most this many items from a JSON array response (e.g., limit=20).', default=None)]",
          "default": null
        },
        "websocket": {
          "type": "Annotated[bool, Field(description=\"Use WebSocket instead of HTTP. For streaming endpoints (e.g., ESPHome /compile, /validate). Sends 'body' as initial message, collects responses. Default: false.\", default=False)]",
          "default": false
        },
        "wait_for_close": {
          "type": "Annotated[bool, Field(description='WebSocket only. True: wait for server to close (for compile/validate). False: return after first response batch (for quick commands). Default: true.', default=True)]",
          "default": true
        }
      },
      "required": [
        "slug",
        "path"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": false,
      "readOnlyHint": false
    },
    "tags": [
      "Add-ons"
    ],
    "source_file": "tools_addons.py"
  },
  {
    "name": "ha_get_addon",
    "title": "Get Add-ons",
    "description": "Get Home Assistant add-ons - list installed, available, or get details for one.\n\nThis tool retrieves add-on information based on the parameters:\n- slug provided: Returns detailed info for a single add-on (ingress, ports, options, state)\n- source='installed' (default): Lists currently installed add-ons\n- source='available': Lists add-ons available in the add-on store\n\n**Note:** This tool only works with Home Assistant OS or Supervised installations.\n\n**SINGLE ADD-ON (slug provided):**\nReturns comprehensive details including ingress entry, ports, options, and state.\nUseful for discovering what APIs an add-on exposes before calling ha_call_addon_api.\n\n**INSTALLED ADD-ONS (source='installed'):**\nReturns add-ons with version, state (started/stopped), and update availability.\n- include_stats: Optionally include CPU/memory usage statistics\n\n**AVAILABLE ADD-ONS (source='available'):**\nReturns add-ons from official and custom repositories that can be installed.\n- repository: Filter by repository slug (e.g., 'core', 'community')\n- query: Search by name or description (case-insensitive)\n\n**Example Usage:**\n- List installed add-ons: ha_get_addon()\n- Get Node-RED details: ha_get_addon(slug=\"a0d7b954_nodered\")\n- List with resource usage: ha_get_addon(include_stats=True)\n- List available add-ons: ha_get_addon(source=\"available\")\n- Search for MQTT: ha_get_addon(source=\"available\", query=\"mqtt\")",
    "inputSchema": {
      "properties": {
        "source": {
          "type": "Annotated[str | None, Field(description=\"Add-on source: 'installed' (default) for currently installed add-ons, 'available' for add-ons in the store that can be installed.\", default=None)]",
          "default": null
        },
        "slug": {
          "type": "Annotated[str | None, Field(description=\"Add-on slug for detailed info (e.g., 'a0d7b954_nodered'). Omit to list all add-ons.\", default=None)]",
          "default": null
        },
        "include_stats": {
          "type": "Annotated[bool, Field(description=\"Include CPU/memory usage statistics (only for source='installed')\", default=False)]",
          "default": false
        },
        "repository": {
          "type": "Annotated[str | None, Field(description=\"Filter by repository slug, e.g., 'core', 'community' (only for source='available')\", default=None)]",
          "default": null
        },
        "query": {
          "type": "Annotated[str | None, Field(description=\"Search filter for add-on names/descriptions (only for source='available')\", default=None)]",
          "default": null
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Add-ons"
    ],
    "source_file": "tools_addons.py"
  },
  {
    "name": "ha_config_list_areas",
    "title": "List Areas",
    "description": "List all Home Assistant areas (rooms).\n\nReturns area ID, name, icon, floor assignment, aliases, and picture URL.",
    "inputSchema": {},
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Areas & Floors"
    ],
    "source_file": "tools_areas.py"
  },
  {
    "name": "ha_config_list_floors",
    "title": "List Floors",
    "description": "List all Home Assistant floors.\n\nReturns floor ID, name, icon, level (0=ground, 1=first, -1=basement), and aliases.",
    "inputSchema": {},
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Areas & Floors"
    ],
    "source_file": "tools_areas.py"
  },
  {
    "name": "ha_config_remove_area",
    "title": "Remove Area",
    "description": "Delete a Home Assistant area.\n\nEntities and devices in the area are not deleted, just unassigned.\nMay break automations referencing this area.",
    "inputSchema": {
      "properties": {
        "area_id": {
          "type": "Annotated[str, Field(description='Area ID to delete (use ha_config_list_areas to find IDs)')]"
        }
      },
      "required": [
        "area_id"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": true
    },
    "tags": [
      "Areas & Floors"
    ],
    "source_file": "tools_areas.py"
  },
  {
    "name": "ha_config_remove_floor",
    "title": "Remove Floor",
    "description": "Delete a Home Assistant floor.\n\nAreas on this floor are not deleted, just unassigned.\nMay break automations referencing this floor.",
    "inputSchema": {
      "properties": {
        "floor_id": {
          "type": "Annotated[str, Field(description='Floor ID to delete (use ha_config_list_floors to find IDs)')]"
        }
      },
      "required": [
        "floor_id"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": true
    },
    "tags": [
      "Areas & Floors"
    ],
    "source_file": "tools_areas.py"
  },
  {
    "name": "ha_config_set_area",
    "title": "Create or Update Area",
    "description": "Create or update a Home Assistant area (room).\n\nProvide name only to create a new area. Provide area_id to update existing.\nAreas organize entities by physical location for room-based control.",
    "inputSchema": {
      "properties": {
        "name": {
          "type": "Annotated[str | None, Field(description=\"Name for the area (required for create, optional for update, e.g., 'Living Room', 'Kitchen')\", default=None)]",
          "default": null
        },
        "area_id": {
          "type": "Annotated[str | None, Field(description='Area ID to update (omit to create new area, use ha_config_list_areas to find IDs)', default=None)]",
          "default": null
        },
        "floor_id": {
          "type": "Annotated[str | None, Field(description='Floor ID to assign this area to (use ha_config_list_floors to find IDs, empty string to remove)', default=None)]",
          "default": null
        },
        "icon": {
          "type": "Annotated[str | None, Field(description=\"Material Design Icon (e.g., 'mdi:sofa', 'mdi:bed', empty string to remove)\", default=None)]",
          "default": null
        },
        "aliases": {
          "type": "Annotated[str | list[str] | None, Field(description=\"Alternative names for voice assistant recognition (e.g., ['lounge', 'family room'], empty list to clear)\", default=None)]",
          "default": null
        },
        "picture": {
          "type": "Annotated[str | None, Field(description='URL to a picture representing the area (empty string to remove)', default=None)]",
          "default": null
        }
      }
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Areas & Floors"
    ],
    "source_file": "tools_areas.py"
  },
  {
    "name": "ha_config_set_floor",
    "title": "Create or Update Floor",
    "description": "Create or update a Home Assistant floor.\n\nProvide name only to create a new floor. Provide floor_id to update existing.\nFloors organize areas into vertical levels for building-wide control.",
    "inputSchema": {
      "properties": {
        "name": {
          "type": "Annotated[str | None, Field(description=\"Name for the floor (required for create, optional for update, e.g., 'Ground Floor', 'Basement')\", default=None)]",
          "default": null
        },
        "floor_id": {
          "type": "Annotated[str | None, Field(description='Floor ID to update (omit to create new floor, use ha_config_list_floors to find IDs)', default=None)]",
          "default": null
        },
        "level": {
          "type": "Annotated[int | None, Field(description='Numeric level for ordering (0=ground, 1=first, -1=basement, etc.)', default=None)]",
          "default": null
        },
        "icon": {
          "type": "Annotated[str | None, Field(description=\"Material Design Icon (e.g., 'mdi:home-floor-1', 'mdi:home-floor-b', empty string to remove)\", default=None)]",
          "default": null
        },
        "aliases": {
          "type": "Annotated[str | list[str] | None, Field(description=\"Alternative names for voice assistant recognition (e.g., ['downstairs', 'main level'], empty list to clear)\", default=None)]",
          "default": null
        }
      }
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Areas & Floors"
    ],
    "source_file": "tools_areas.py"
  },
  {
    "name": "ha_config_get_automation",
    "title": "Get Automation Config",
    "description": "Retrieve Home Assistant automation configuration.\n\nReturns the complete configuration including triggers, conditions, actions, and mode settings.\n\nEXAMPLES:\n- Get automation: ha_config_get_automation(\"automation.morning_routine\")\n- Get by unique_id: ha_config_get_automation(\"my_unique_automation_id\")\n\nFor comprehensive automation documentation, use ha_get_skill_home_assistant_best_practices.",
    "inputSchema": {
      "properties": {
        "identifier": {
          "type": "Annotated[str, Field(description=\"Automation entity_id (e.g., 'automation.morning_routine') or unique_id\")]"
        }
      },
      "required": [
        "identifier"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Automations"
    ],
    "source_file": "tools_config_automations.py"
  },
  {
    "name": "ha_config_remove_automation",
    "title": "Remove Automation",
    "description": "Delete a Home Assistant automation.\n\nEXAMPLES:\n- Delete automation: ha_config_remove_automation(\"automation.old_automation\")\n- Delete by unique_id: ha_config_remove_automation(\"my_unique_id\")\n\n**WARNING:** Deleting an automation removes it permanently from your Home Assistant configuration.",
    "inputSchema": {
      "properties": {
        "identifier": {
          "type": "Annotated[str, Field(description=\"Automation entity_id (e.g., 'automation.old_automation') or unique_id to delete\")]"
        },
        "wait": {
          "type": "Annotated[bool | str, Field(description='Wait for automation to be fully removed before returning. Default: True.', default=True)]",
          "default": true
        }
      },
      "required": [
        "identifier"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": true
    },
    "tags": [
      "Automations"
    ],
    "source_file": "tools_config_automations.py"
  },
  {
    "name": "ha_config_set_automation",
    "title": "Create or Update Automation",
    "description": "Create or update a Home Assistant automation.\n\nCreates a new automation (if identifier omitted) or updates existing automation with provided configuration.\n\nAUTOMATION TYPES:\n\n1. Regular Automations - Define triggers and actions directly\n2. Blueprint Automations - Use pre-built templates with customizable inputs\n\nREQUIRED FIELDS (Regular Automations):\n- alias: Human-readable automation name\n- trigger: List of trigger conditions (time, state, event, etc.)\n- action: List of actions to execute\n\nREQUIRED FIELDS (Blueprint Automations):\n- alias: Human-readable automation name\n- use_blueprint: Blueprint configuration\n  - path: Blueprint file path (e.g., \"motion_light.yaml\")\n  - input: Dictionary of input values for the blueprint\n\nOPTIONAL CONFIG FIELDS (Regular Automations):\n- description: Detailed description of the user's intent (RECOMMENDED: helps safely modify implementation later)\n- category: Category ID for organization (use ha_config_get_category to list, ha_config_set_category to create)\n- condition: Additional conditions that must be met\n- mode: 'single' (default), 'restart', 'queued', 'parallel'\n- max: Maximum concurrent executions (for queued/parallel modes)\n- initial_state: Whether automation starts enabled (true/false)\n- variables: Variables for use in automation\n\nBASIC EXAMPLES:\n\nSimple time-based automation:\nha_config_set_automation({\n    \"alias\": \"Morning Lights\",\n    \"description\": \"Turn on bedroom lights at 7 AM to help wake up\",\n    \"trigger\": [{\"platform\": \"time\", \"at\": \"07:00:00\"}],\n    \"action\": [{\"service\": \"light.turn_on\", \"target\": {\"area_id\": \"bedroom\"}}]\n})\n\nMotion-activated lighting with condition:\nha_config_set_automation({\n    \"alias\": \"Motion Light\",\n    \"trigger\": [{\"platform\": \"state\", \"entity_id\": \"binary_sensor.motion\", \"to\": \"on\"}],\n    \"condition\": [{\"condition\": \"sun\", \"after\": \"sunset\"}],\n    \"action\": [\n        {\"service\": \"light.turn_on\", \"target\": {\"entity_id\": \"light.hallway\"}},\n        {\"delay\": {\"minutes\": 5}},\n        {\"service\": \"light.turn_off\", \"target\": {\"entity_id\": \"light.hallway\"}}\n    ],\n    \"mode\": \"restart\"\n})\n\nUpdate existing automation:\nha_config_set_automation(\n    identifier=\"automation.morning_routine\",\n    config={\n        \"alias\": \"Updated Morning Routine\",\n        \"trigger\": [{\"platform\": \"time\", \"at\": \"06:30:00\"}],\n        \"action\": [\n            {\"service\": \"light.turn_on\", \"target\": {\"area_id\": \"bedroom\"}},\n            {\"service\": \"climate.set_temperature\", \"target\": {\"entity_id\": \"climate.bedroom\"}, \"data\": {\"temperature\": 22}}\n        ]\n    }\n)\n\nBLUEPRINT AUTOMATION EXAMPLES:\n\nCreate automation from blueprint:\nha_config_set_automation({\n    \"alias\": \"Motion Light Kitchen\",\n    \"use_blueprint\": {\n        \"path\": \"homeassistant/motion_light.yaml\",\n        \"input\": {\n            \"motion_entity\": \"binary_sensor.kitchen_motion\",\n            \"light_target\": {\"entity_id\": \"light.kitchen\"},\n            \"no_motion_wait\": 120\n        }\n    }\n})\n\nUpdate blueprint automation inputs:\nha_config_set_automation(\n    identifier=\"automation.motion_light_kitchen\",\n    config={\n        \"alias\": \"Motion Light Kitchen\",\n        \"use_blueprint\": {\n            \"path\": \"homeassistant/motion_light.yaml\",\n            \"input\": {\n                \"motion_entity\": \"binary_sensor.kitchen_motion\",\n                \"light_target\": {\"entity_id\": \"light.kitchen\"},\n                \"no_motion_wait\": 300\n            }\n        }\n    }\n})\n\nPREFER NATIVE SOLUTIONS OVER TEMPLATES:\nBefore using template triggers/conditions/actions, check if a native option exists:\n- Use `condition: state` with `state: [list]` instead of template for multiple states\n- Use `condition: state` with `attribute:` instead of template for attribute checks\n- Use `condition: numeric_state` instead of template for number comparisons\n- Use `wait_for_trigger` instead of `wait_template` when waiting for state changes\n- Use `choose` action instead of template-based service names\n\nTRIGGER TYPES: time, time_pattern, sun, state, numeric_state, event, device, zone, template, and more\nCONDITION TYPES: state, numeric_state, time, sun, template, device, zone, and more\nACTION TYPES: service calls, delays, wait_for_trigger, wait_template, if/then/else, choose, repeat, parallel\n\nFor comprehensive automation documentation with all trigger/condition/action types and advanced examples:\n- Use: ha_get_skill_home_assistant_best_practices\n- Or visit: https://www.home-assistant.io/docs/automation/\n\nTROUBLESHOOTING:\n- Use ha_get_state() to verify entity_ids exist\n- Use ha_search_entities() to find correct entity_ids\n- Use ha_eval_template() to test Jinja2 templates before using in automations\n- Use ha_search_entities(domain_filter='automation') to find existing automations",
    "inputSchema": {
      "properties": {
        "config": {
          "type": "Annotated[str | dict[str, Any], Field(description=\"Complete automation configuration with required fields: 'alias', 'trigger', 'action'. Optional: 'description', 'condition', 'mode', 'max', 'initial_state', 'variables'\")]"
        },
        "identifier": {
          "type": "Annotated[str | None, Field(description='Automation entity_id or unique_id for updates. Omit to create new automation with generated unique_id.', default=None)]",
          "default": null
        },
        "category": {
          "type": "Annotated[str | None, Field(description=\"Category ID to assign to this automation. Use ha_config_get_category(scope='automation') to list available categories, or ha_config_set_category() to create one.\", default=None)]",
          "default": null
        },
        "wait": {
          "type": "Annotated[bool | str, Field(description='Wait for automation to be queryable before returning. Default: True. Set to False for bulk operations.', default=True)]",
          "default": true
        }
      },
      "required": [
        "config"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Automations"
    ],
    "source_file": "tools_config_automations.py"
  },
  {
    "name": "ha_get_blueprint",
    "title": "Get Blueprint",
    "description": "Get blueprint information - list all blueprints or get details for a specific one.\n\nWithout a path: Lists all installed blueprints for the specified domain.\nWith a path: Retrieves full blueprint configuration including inputs, triggers,\nconditions, and actions.\n\nEXAMPLES:\n- List all automation blueprints: ha_get_blueprint(domain=\"automation\")\n- List script blueprints: ha_get_blueprint(domain=\"script\")\n- Get specific blueprint: ha_get_blueprint(path=\"homeassistant/motion_light.yaml\", domain=\"automation\")\n\nRETURNS (when listing):\n- List of blueprints with path, name, and domain information\n- Count of blueprints found\n\nRETURNS (when getting specific blueprint):\n- Blueprint metadata (name, description, author, source_url)\n- Input definitions with selectors and defaults\n- Blueprint configuration (triggers, conditions, actions for automations; sequence for scripts)",
    "inputSchema": {
      "properties": {
        "path": {
          "type": "Annotated[str | None, Field(description=\"Blueprint path to get details for (e.g., 'homeassistant/motion_light.yaml'). If omitted, lists all blueprints in the domain.\", default=None)]",
          "default": null
        },
        "domain": {
          "type": "Annotated[str, Field(description=\"Blueprint domain: 'automation' or 'script'\", default='automation')]",
          "default": "automation"
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Blueprints"
    ],
    "source_file": "tools_blueprints.py"
  },
  {
    "name": "ha_import_blueprint",
    "title": "Import Blueprint",
    "description": "Import a blueprint from a URL.\n\nImports a blueprint from GitHub, Home Assistant Community forums,\nor any direct URL to a blueprint YAML file.\n\nEXAMPLES:\n- Import from GitHub: ha_import_blueprint(\"https://github.com/user/repo/blob/main/blueprint.yaml\")\n- Import from HA Community: ha_import_blueprint(\"https://community.home-assistant.io/t/motion-light/123456\")\n- Import direct YAML: ha_import_blueprint(\"https://example.com/my-blueprint.yaml\")\n\nSUPPORTED SOURCES:\n- GitHub repository URLs (will be converted to raw URLs)\n- Home Assistant Community forum posts with blueprint code\n- Direct URLs to YAML blueprint files\n\nRETURNS:\n- Import result with the blueprint path where it was saved\n- Blueprint metadata (name, domain, description)\n- Error details if import fails",
    "inputSchema": {
      "properties": {
        "url": {
          "type": "Annotated[str, Field(description='URL to import blueprint from (GitHub, Home Assistant Community, or direct YAML URL)')]"
        }
      },
      "required": [
        "url"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Blueprints"
    ],
    "source_file": "tools_blueprints.py"
  },
  {
    "name": "ha_config_get_calendar_events",
    "title": "Get Calendar Events",
    "description": "Retrieve calendar events from a calendar entity.\n\nRetrieves calendar events within a specified time range.\n\n**Parameters:**\n- entity_id: Calendar entity ID (e.g., 'calendar.family')\n- start: Start datetime in ISO format (default: now)\n- end: End datetime in ISO format (default: 7 days from start)\n- max_results: Maximum number of events to return (default: 20)\n\n**Example Usage:**\n```python\n# Get events for the next week\nevents = ha_config_get_calendar_events(\"calendar.family\")\n\n# Get events for a specific date range\nevents = ha_config_get_calendar_events(\n    \"calendar.work\",\n    start=\"2024-01-01T00:00:00\",\n    end=\"2024-01-31T23:59:59\"\n)\n```\n\n**Note:** To find calendar entities, use ha_search_entities(query='calendar', domain_filter='calendar')\n\n**Returns:**\n- List of calendar events with summary, start, end, description, location",
    "inputSchema": {
      "properties": {
        "entity_id": {
          "type": "Annotated[str, Field(description=\"Calendar entity ID (e.g., 'calendar.family')\")]"
        },
        "start": {
          "type": "Annotated[str | None, Field(description='Start datetime in ISO format (default: now)', default=None)]",
          "default": null
        },
        "end": {
          "type": "Annotated[str | None, Field(description='End datetime in ISO format (default: 7 days from start)', default=None)]",
          "default": null
        },
        "max_results": {
          "type": "Annotated[int, Field(description='Maximum number of events to return', default=20)]",
          "default": 20
        }
      },
      "required": [
        "entity_id"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Calendar"
    ],
    "source_file": "tools_calendar.py"
  },
  {
    "name": "ha_config_remove_calendar_event",
    "title": "Remove Calendar Event",
    "description": "Delete an event from a calendar.\n\nDeletes a calendar event using the calendar.delete_event service.\n\n**Parameters:**\n- entity_id: Calendar entity ID (e.g., 'calendar.family')\n- uid: Unique identifier of the event to delete\n- recurrence_id: Optional recurrence ID for recurring events\n- recurrence_range: Optional recurrence range ('THIS_AND_FUTURE' to delete this and future occurrences)\n\n**Example Usage:**\n```python\n# Delete a single event\nresult = ha_config_remove_calendar_event(\n    \"calendar.family\",\n    uid=\"event-12345\"\n)\n\n# Delete a recurring event instance and future occurrences\nresult = ha_config_remove_calendar_event(\n    \"calendar.work\",\n    uid=\"recurring-event-67890\",\n    recurrence_id=\"20240115T100000\",\n    recurrence_range=\"THIS_AND_FUTURE\"\n)\n```\n\n**Note:**\nTo get the event UID, first use ha_config_get_calendar_events() to list events.\nThe UID is returned in each event's data.\n\n**Returns:**\n- Success status and deletion confirmation",
    "inputSchema": {
      "properties": {
        "entity_id": {
          "type": "Annotated[str, Field(description=\"Calendar entity ID (e.g., 'calendar.family')\")]"
        },
        "uid": {
          "type": "Annotated[str, Field(description='Unique identifier of the event to delete')]"
        },
        "recurrence_id": {
          "type": "Annotated[str | None, Field(description='Optional recurrence ID for recurring events', default=None)]",
          "default": null
        },
        "recurrence_range": {
          "type": "Annotated[str | None, Field(description=\"Optional recurrence range ('THIS_AND_FUTURE' to delete this and future occurrences)\", default=None)]",
          "default": null
        }
      },
      "required": [
        "entity_id",
        "uid"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": true
    },
    "tags": [
      "Calendar"
    ],
    "source_file": "tools_calendar.py"
  },
  {
    "name": "ha_config_set_calendar_event",
    "title": "Create or Update Calendar Event",
    "description": "Create a new event in a calendar.\n\nCreates a calendar event using the calendar.create_event service.\n\n**Parameters:**\n- entity_id: Calendar entity ID (e.g., 'calendar.family')\n- summary: Event title/summary\n- start: Event start datetime in ISO format\n- end: Event end datetime in ISO format\n- description: Optional event description\n- location: Optional event location\n\n**Example Usage:**\n```python\n# Create a simple event\nresult = ha_config_set_calendar_event(\n    \"calendar.family\",\n    summary=\"Doctor appointment\",\n    start=\"2024-01-15T14:00:00\",\n    end=\"2024-01-15T15:00:00\"\n)\n\n# Create an event with details\nresult = ha_config_set_calendar_event(\n    \"calendar.work\",\n    summary=\"Team meeting\",\n    start=\"2024-01-16T10:00:00\",\n    end=\"2024-01-16T11:00:00\",\n    description=\"Weekly sync meeting\",\n    location=\"Conference Room A\"\n)\n```\n\n**Returns:**\n- Success status and event details",
    "inputSchema": {
      "properties": {
        "entity_id": {
          "type": "Annotated[str, Field(description=\"Calendar entity ID (e.g., 'calendar.family')\")]"
        },
        "summary": {
          "type": "Annotated[str, Field(description='Event title/summary')]"
        },
        "start": {
          "type": "Annotated[str, Field(description='Event start datetime in ISO format')]"
        },
        "end": {
          "type": "Annotated[str, Field(description='Event end datetime in ISO format')]"
        },
        "description": {
          "type": "Annotated[str | None, Field(description='Optional event description', default=None)]",
          "default": null
        },
        "location": {
          "type": "Annotated[str | None, Field(description='Optional event location', default=None)]",
          "default": null
        }
      },
      "required": [
        "entity_id",
        "summary",
        "start",
        "end"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Calendar"
    ],
    "source_file": "tools_calendar.py"
  },
  {
    "name": "ha_get_camera_image",
    "title": "Get Camera Image",
    "description": "Retrieve a snapshot image from a Home Assistant camera entity.\n\nThis tool fetches the current camera image and returns it directly for visual\nanalysis. Use this when you need to see what a camera is currently viewing.\n\n**Parameters:**\n- entity_id: Camera entity ID (e.g., 'camera.front_door', 'camera.living_room')\n- width: Optional width to resize the image (reduces token usage for large images)\n- height: Optional height to resize the image\n\n**Use Cases:**\n- Security checks: \"Is someone at the front door?\"\n- Pet monitoring: \"Is my dog still on the couch?\"\n- Delivery verification: \"Did my package get delivered?\"\n- Visual confirmation: \"Did the garage door actually close?\"\n- Incident investigation: \"What triggered the motion sensor?\"\n\n**Example Usage:**\n```python\n# Get current snapshot from front door camera\nha_get_camera_image(entity_id=\"camera.front_door\")\n\n# Get resized image to reduce token usage\nha_get_camera_image(entity_id=\"camera.backyard\", width=640, height=480)\n```\n\n**Notes:**\n- Only cameras exposed to Home Assistant are accessible\n- The existing HA authentication/authorization applies\n- Images are returned in their native format (JPEG, PNG, or GIF)\n- Use width/height parameters for large high-resolution cameras to reduce\n  token usage when full resolution is not needed\n\n**Related Services:**\n- camera.snapshot: Save snapshot to file on HA server\n- camera.turn_on/turn_off: Control camera power\n- camera.enable_motion_detection: Enable motion detection",
    "inputSchema": {
      "properties": {
        "entity_id": {
          "type": "str"
        },
        "width": {
          "type": "int | None",
          "default": null
        },
        "height": {
          "type": "int | None",
          "default": null
        }
      },
      "required": [
        "entity_id"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Camera"
    ],
    "source_file": "tools_camera.py"
  },
  {
    "name": "ha_config_delete_dashboard",
    "title": "Delete Dashboard",
    "description": "Delete a storage-mode dashboard completely.\n\nWARNING: This permanently deletes the dashboard and all its configuration.\nCannot be undone. Does not work on YAML-mode dashboards.\n\nAccepts either the internal dashboard ID or the URL path.\nThe tool resolves url_path to internal ID automatically.\n\nEXAMPLES:\n- Delete dashboard: ha_config_delete_dashboard(\"mobile-dashboard\")\n\nNote: The default dashboard cannot be deleted via this method.",
    "inputSchema": {
      "properties": {
        "dashboard_id": {
          "type": "Annotated[str, Field(description=\"Dashboard ID or URL path to delete (e.g., 'my-dashboard' or 'my_dashboard')\")]"
        }
      },
      "required": [
        "dashboard_id"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Dashboards"
    ],
    "source_file": "tools_config_dashboards.py"
  },
  {
    "name": "ha_config_delete_dashboard_resource",
    "title": "Delete Dashboard Resource",
    "description": "Delete a dashboard resource.\n\nRemoves a resource from Home Assistant. The resource will no longer\nbe loaded on dashboards.\n\nWARNING: Deleting a resource used by custom cards in your dashboards\nwill cause those cards to fail to load.\n\nEXAMPLES:\nha_config_delete_dashboard_resource(resource_id=\"abc123\")\n\nNote: Use ha_config_list_dashboard_resources() to find resource IDs\nbefore deleting. Ensure no dashboards depend on the resource.",
    "inputSchema": {
      "properties": {
        "resource_id": {
          "type": "Annotated[str, Field(description='Resource ID to delete. Get from ha_config_list_dashboard_resources()')]"
        }
      },
      "required": [
        "resource_id"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Dashboards"
    ],
    "source_file": "tools_resources.py"
  },
  {
    "name": "ha_config_get_dashboard",
    "title": "Get Dashboard",
    "description": "Get dashboard info - list all dashboards or get config for a specific one.\n\nWithout url_path (or with list_only=True): Lists all storage-mode dashboards\nwith metadata including url_path, title, icon, admin requirements.\n\nWith url_path: Returns the full Lovelace dashboard configuration\nincluding all views and cards.\n\nEXAMPLES:\n- List all dashboards: ha_config_get_dashboard(list_only=True)\n- Get default dashboard: ha_config_get_dashboard(url_path=\"default\")\n- Get custom dashboard: ha_config_get_dashboard(url_path=\"lovelace-mobile\")\n- Force reload: ha_config_get_dashboard(url_path=\"lovelace-home\", force_reload=True)\n\nNote: YAML-mode dashboards (defined in configuration.yaml) are not included in list.",
    "inputSchema": {
      "properties": {
        "url_path": {
          "type": "Annotated[str | None, Field(description=\"Dashboard URL path (e.g., 'lovelace-home'). Use 'default' for default dashboard. If omitted with list_only=True, lists all dashboards.\")]",
          "default": null
        },
        "list_only": {
          "type": "Annotated[bool, Field(description='If True, list all dashboards instead of getting config. When True, url_path is ignored.')]",
          "default": false
        },
        "force_reload": {
          "type": "Annotated[bool, Field(description='Force reload from storage (bypass cache)')]",
          "default": false
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Dashboards"
    ],
    "source_file": "tools_config_dashboards.py"
  },
  {
    "name": "ha_config_list_dashboard_resources",
    "title": "List Dashboard Resources",
    "description": "List all Lovelace dashboard resources (custom cards, themes, CSS/JS).\n\nReturns all registered resources. For inline resources (created with\nha_config_set_dashboard_resource(content=...)), shows a preview of the content\ninstead of the full encoded URL to save tokens.\n\nArgs:\n    include_content: If True, includes full decoded content for inline\n        resources in \"_content\" field. Default False (150-char preview only).\n\nResource types:\n- module: ES6 JavaScript modules (modern custom cards)\n- js: Legacy JavaScript files\n- css: CSS stylesheets\n\nEach resource has a unique ID for update/delete operations.\n\nEXAMPLES:\n- List all resources: ha_config_list_dashboard_resources()\n- List with full content: ha_config_list_dashboard_resources(include_content=True)\n\nNote: Requires advanced mode to be enabled in Home Assistant for resource\nmanagement through the UI, but API access works regardless.",
    "inputSchema": {
      "properties": {
        "include_content": {
          "type": "Annotated[bool, Field(description='Include full decoded content for inline resources. Default False to save tokens (shows 150-char preview instead).')]",
          "default": false
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Dashboards"
    ],
    "source_file": "tools_resources.py"
  },
  {
    "name": "ha_config_set_dashboard",
    "title": "Create or Update Dashboard",
    "description": "Create or update a Home Assistant dashboard.\n\nCreates a new dashboard or updates an existing one with the provided configuration.\nSupports two modes: full config replacement OR Python transformation.\n\nUse 'default' or 'lovelace' to target the built-in default dashboard.\nNew dashboards require a hyphenated url_path (e.g., 'my-dashboard').\n\nWHEN TO USE WHICH MODE:\n- python_transform: RECOMMENDED for edits. Surgical/pattern-based updates, works on all platforms.\n- config: New dashboards only, or full restructure. Replaces everything.\n\nIMPORTANT: After delete/add operations, indices shift! Subsequent python_transform calls\nmust use fresh config_hash from ha_dashboard_find_card() or ha_config_get_dashboard()\nto get updated structure. Chain multiple ops in ONE expression when possible.\n\nTIP: Use ha_dashboard_find_card() to get the path for any card.\n\nPYTHON TRANSFORM EXAMPLES (RECOMMENDED):\n- Update card icon: 'config[\"views\"][0][\"cards\"][0][\"icon\"] = \"mdi:thermometer\"'\n- Add card: 'config[\"views\"][0][\"cards\"].append({\"type\": \"button\", \"entity\": \"light.bedroom\"})'\n- Delete card: 'del config[\"views\"][0][\"cards\"][2]'\n- Pattern-based update: 'for card in config[\"views\"][0][\"cards\"]: if \"light\" in card.get(\"entity\", \"\"): card[\"icon\"] = \"mdi:lightbulb\"'\n- Multi-operation: 'config[\"views\"][0][\"cards\"][0][\"icon\"] = \"mdi:a\"; config[\"views\"][0][\"cards\"][1][\"icon\"] = \"mdi:b\"'\n\nMODERN DASHBOARD BEST PRACTICES (2024+):\n- Use \"sections\" view type (default) with grid-based layouts\n- Use \"tile\" cards as primary card type (replaces legacy entity/light/climate cards)\n- Use \"grid\" cards for multi-column layouts within sections\n- Create multiple views with navigation paths (avoid single-view endless scrolling)\n- Use \"area\" cards with navigation for hierarchical organization\n\nDISCOVERING ENTITY IDs FOR DASHBOARDS:\nDo NOT guess entity IDs - use these tools to find exact entity IDs:\n1. ha_get_overview(include_entity_id=True) - Get all entities organized by domain/area\n2. ha_search_entities(query, domain_filter, area_filter) - Find specific entities\n3. ha_deep_search(query) - Comprehensive search across entities, areas, automations\n\nIf unsure about entity IDs, ALWAYS use one of these tools first.\n\nDASHBOARD DOCUMENTATION (via MCP skills):\n- skill://home-assistant-best-practices/references/dashboard-guide.md — comprehensive guide\n- skill://home-assistant-best-practices/references/dashboard-cards.md — card types list\n- ha_get_skill_home_assistant_best_practices — guidance on card types and configuration\n\nEXAMPLES:\n\nCreate empty dashboard:\nha_config_set_dashboard(\n    url_path=\"mobile-dashboard\",\n    title=\"Mobile View\",\n    icon=\"mdi:cellphone\"\n)\n\nCreate dashboard with modern sections view:\nha_config_set_dashboard(\n    url_path=\"home-dashboard\",\n    title=\"Home Overview\",\n    config={\n        \"views\": [{\n            \"title\": \"Home\",\n            \"type\": \"sections\",\n            \"sections\": [{\n                \"title\": \"Climate\",\n                \"cards\": [{\n                    \"type\": \"tile\",\n                    \"entity\": \"climate.living_room\",\n                    \"features\": [{\"type\": \"target-temperature\"}]\n                }]\n            }]\n        }]\n    }\n)\n\nCreate strategy-based dashboard (auto-generated):\nha_config_set_dashboard(\n    url_path=\"my-home\",\n    title=\"My Home\",\n    config={\n        \"strategy\": {\n            \"type\": \"home\",\n            \"favorite_entities\": [\"light.bedroom\"]\n        }\n    }\n)\n\nNote: Strategy dashboards cannot be converted to custom dashboards via this tool.\nUse the \"Take Control\" feature in the Home Assistant interface to convert them.\n\nUpdate existing dashboard config:\nha_config_set_dashboard(\n    url_path=\"existing-dashboard\",\n    config={\n        \"views\": [{\n            \"title\": \"Updated View\",\n            \"type\": \"sections\",\n            \"sections\": [{\n                \"cards\": [{\"type\": \"markdown\", \"content\": \"Updated!\"}]\n            }]\n        }]\n    }\n)\n\nNote: When updating an existing dashboard, title/icon/require_admin/show_in_sidebar\nare also updated if explicitly provided alongside (or instead of) a config change.",
    "inputSchema": {
      "properties": {
        "url_path": {
          "type": "Annotated[str, Field(description=\"Dashboard URL path (e.g., 'my-dashboard'). Use 'default' or 'lovelace' for the default dashboard. New dashboards must use a hyphenated path.\")]"
        },
        "config": {
          "type": "Annotated[str | dict[str, Any] | None, Field(description='Dashboard configuration with views and cards. Can be dict or JSON string. Omit or set to None to create dashboard without initial config. Mutually exclusive with python_transform.')]",
          "default": null
        },
        "python_transform": {
          "type": "Annotated[str | None, Field(description='Python expression to transform existing dashboard config. Mutually exclusive with config. Requires config_hash for validation. See PYTHON TRANSFORM SECURITY below for allowed operations. Examples: Simple: python_transform=\"config[\\'views\\'][0][\\'cards\\'][0][\\'icon\\'] = \\'mdi:lamp\\'\" Pattern: python_transform=\"for card in config[\\'views\\'][0][\\'cards\\']: if \\'light\\' in card.get(\\'entity\\', \\'\\'): card[\\'icon\\'] = \\'mdi:lightbulb\\'\" Multi-op: python_transform=\"config[\\'views\\'][0][\\'cards\\'][0][\\'icon\\'] = \\'mdi:lamp\\'; del config[\\'views\\'][0][\\'cards\\'][2]\" \\n\\n' + get_security_documentation())]",
          "default": null
        },
        "config_hash": {
          "type": "Annotated[str | None, Field(description='Config hash from ha_config_get_dashboard for optimistic locking. REQUIRED for python_transform (validates dashboard unchanged). Optional for config (validates before full replacement if provided).')]",
          "default": null
        },
        "title": {
          "type": "Annotated[str | None, Field(description='Dashboard display name shown in sidebar')]",
          "default": null
        },
        "icon": {
          "type": "Annotated[str | None, Field(description=\"MDI icon name (e.g., 'mdi:home', 'mdi:cellphone'). Defaults to 'mdi:view-dashboard'\")]",
          "default": null
        },
        "require_admin": {
          "type": "Annotated[bool | None, Field(description='Restrict dashboard to admin users only. For existing dashboards, only updated when explicitly provided.')]",
          "default": null
        },
        "show_in_sidebar": {
          "type": "Annotated[bool | None, Field(description='Show dashboard in sidebar navigation. For existing dashboards, only updated when explicitly provided.')]",
          "default": null
        }
      },
      "required": [
        "url_path"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Dashboards"
    ],
    "source_file": "tools_config_dashboards.py"
  },
  {
    "name": "ha_config_set_dashboard_resource",
    "title": "Set Dashboard Resource",
    "description": "Create or update a dashboard resource (inline code or external URL).\n\nProvide exactly one of:\n- content: Inline JavaScript or CSS code (embedded in URL, no file storage needed)\n- url: External resource URL (/local/, /hacsfiles/, or https://...)\n\nINLINE MODE (content=):\n- Custom card code written inline\n- CSS styling for dashboards\n- Small utility modules (<24KB)\n- URLs are deterministic (same content = same URL)\n- Supports 'module' and 'css' types only (not 'js')\n\nURL MODE (url=):\n- Files in /config/www/ directory (/local/...)\n- HACS-installed cards (/hacsfiles/...)\n- External CDN resources (https://...)\n- Supports all types: 'module', 'js', 'css'\n\nRESOURCE TYPES:\n- module: ES6 JavaScript modules (recommended for custom cards)\n- js: Legacy JavaScript files (older custom cards, url mode only)\n- css: CSS stylesheets (themes, global styles)\n\nEXAMPLES:\n\nInline custom card:\nha_config_set_dashboard_resource(\n    content=\"\"\"\n    class MyCard extends HTMLElement {\n      setConfig(config) { this.config = config; }\n      set hass(hass) {\n        this.innerHTML = `<ha-card>Hello ${hass.states[this.config.entity]?.state}</ha-card>`;\n      }\n    }\n    customElements.define('my-card', MyCard);\n    \"\"\",\n    resource_type=\"module\"\n)\n\nAdd custom card from www/ directory:\nha_config_set_dashboard_resource(\n    url=\"/local/my-custom-card.js\",\n    resource_type=\"module\"\n)\n\nAdd HACS card (after installing via ha_hacs_download):\nha_config_set_dashboard_resource(\n    url=\"/hacsfiles/lovelace-mushroom/mushroom.js\",\n    resource_type=\"module\"\n)\n\nUpdate existing resource:\nha_config_set_dashboard_resource(\n    url=\"/local/my-card-v2.js\",\n    resource_type=\"module\",\n    resource_id=\"abc123\"\n)\n\nNote: After adding a resource, clear browser cache or hard refresh\n(Ctrl+Shift+R) to load changes.",
    "inputSchema": {
      "properties": {
        "content": {
          "type": "Annotated[str | None, Field(description=\"JavaScript or CSS code to host inline (max ~24KB). The code is embedded in the URL via Cloudflare Worker - no file storage needed. Mutually exclusive with url. Supports 'module' and 'css' types only.\")]",
          "default": null
        },
        "url": {
          "type": "Annotated[str | None, Field(description='URL of the resource. Can be: /local/file.js (www/ directory), /hacsfiles/component/file.js (HACS), https://cdn.example.com/card.js (external). Mutually exclusive with content.')]",
          "default": null
        },
        "resource_type": {
          "type": "Annotated[Literal['module', 'js', 'css'], Field(description=\"Resource type: 'module' for ES6 modules (modern cards, default), 'js' for legacy JavaScript (url mode only), 'css' for stylesheets\")]",
          "default": "module"
        },
        "resource_id": {
          "type": "Annotated[str | None, Field(description='Resource ID to update. If omitted, creates a new resource. Get IDs from ha_config_list_dashboard_resources()')]",
          "default": null
        }
      }
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Dashboards"
    ],
    "source_file": "tools_resources.py"
  },
  {
    "name": "ha_dashboard_find_card",
    "title": "Find Dashboard Card",
    "description": "Find cards, badges, and header cards in a dashboard by entity_id, type, or heading text.\n\nReturns card/badge/header locations (view_index, section_index, card_index/badge_index)\nand path for use with ha_config_set_dashboard(python_transform=...).\n\nAlso searches view-level badges (views[n].badges) and sections-view header cards\n(views[n].header.card). Badges are the chip row at the top of a view, and header\ncards are Markdown cards in the view header — both reference entities and are\noften missed during entity rename operations.\n\nUse this tool BEFORE targeted updates to find exact card positions without\nmanually parsing the full dashboard config.\n\nSEARCH CRITERIA (at least one required):\n- entity_id: Match cards and badges containing this entity (supports wildcards with *)\n- card_type: Match cards of this type (e.g., 'tile', 'button', 'heading')\n- heading: Match cards with this text in heading/title (partial, case-insensitive)\n\nMultiple criteria are AND-ed together.\n\nEXAMPLES:\n\nFind all tile cards:\nha_dashboard_find_card(url_path=\"my-dashboard\", card_type=\"tile\")\n\nFind cards for a specific entity:\nha_dashboard_find_card(url_path=\"my-dashboard\", entity_id=\"light.living_room\")\n\nFind all temperature sensors (wildcard):\nha_dashboard_find_card(url_path=\"my-dashboard\", entity_id=\"sensor.temperature_*\")\n\nFind the \"Climate\" section heading:\nha_dashboard_find_card(url_path=\"my-dashboard\", heading=\"Climate\", card_type=\"heading\")\n\nWORKFLOW EXAMPLE:\n1. find = ha_dashboard_find_card(url_path=\"my-dash\", entity_id=\"light.bedroom\")\n2. # Use jq_path and config_hash from result to update:\n3. ha_config_set_dashboard(\n       url_path=\"my-dash\",\n       config_hash=find[\"config_hash\"],\n       python_transform=f'config{find[\"matches\"][0][\"jq_path\"]}[\"icon\"] = \"mdi:lamp\"'\n   )",
    "inputSchema": {
      "properties": {
        "url_path": {
          "type": "Annotated[str | None, Field(description=\"Dashboard URL path, e.g. 'lovelace-home'. Omit for default.\")]",
          "default": null
        },
        "entity_id": {
          "type": "Annotated[str | None, Field(description=\"Find cards by entity ID. Supports wildcards, e.g. 'sensor.temperature_*'. Matches cards with this entity in 'entity' or 'entities' field.\")]",
          "default": null
        },
        "card_type": {
          "type": "Annotated[str | None, Field(description=\"Find cards by type, e.g. 'tile', 'button', 'heading'.\")]",
          "default": null
        },
        "heading": {
          "type": "Annotated[str | None, Field(description=\"Find cards by heading/title text (case-insensitive partial match). Useful for finding section headings (type: 'heading').\")]",
          "default": null
        },
        "include_config": {
          "type": "Annotated[bool, Field(description='Include full card configuration in results (increases output size).')]",
          "default": false
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Dashboards"
    ],
    "source_file": "tools_config_dashboards.py"
  },
  {
    "name": "ha_get_device",
    "title": "Get Device",
    "description": "Get device information - list all devices or get details for a specific one.\n\nWithout device_id/entity_id: Lists all devices with optional filters.\nWith device_id or entity_id: Returns detailed info for that specific device.\n\n**List all devices:**\n- All devices: ha_get_device()\n- By area: ha_get_device(area_id=\"living_room\")\n- By manufacturer: ha_get_device(manufacturer=\"Philips\")\n- By integration: ha_get_device(integration=\"zigbee2mqtt\")\n- Combined filters: ha_get_device(integration=\"zha\", area_id=\"kitchen\")\n\n**Single device lookup:**\n- By device_id: ha_get_device(device_id=\"abc123\")\n- By entity_id: ha_get_device(entity_id=\"light.living_room\")\n\n**Zigbee automation tips:**\n- ZHA triggers: Use `ieee_address` for zha_event triggers\n- Z2M triggers: Use `friendly_name` for MQTT topics (zigbee2mqtt/{friendly_name}/action)\n\n**Returns (list mode):**\n- List of devices with device_id, name, manufacturer, model, area_id\n\n**Returns (single device):**\n- Full device details including integration_type, ieee_address, entities",
    "inputSchema": {
      "properties": {
        "device_id": {
          "type": "Annotated[str | None, Field(description='Device ID to retrieve details for. If omitted, lists devices.', default=None)]",
          "default": null
        },
        "entity_id": {
          "type": "Annotated[str | None, Field(description=\"Entity ID to find the associated device for (e.g., 'light.living_room')\", default=None)]",
          "default": null
        },
        "integration": {
          "type": "Annotated[str | None, Field(description=\"Filter devices by integration: 'zha', 'zigbee2mqtt', 'mqtt', 'hue', etc.\", default=None)]",
          "default": null
        },
        "area_id": {
          "type": "Annotated[str | None, Field(description=\"Filter devices by area ID (e.g., 'living_room')\", default=None)]",
          "default": null
        },
        "manufacturer": {
          "type": "Annotated[str | None, Field(description=\"Filter devices by manufacturer name (e.g., 'Philips')\", default=None)]",
          "default": null
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Device Registry"
    ],
    "source_file": "tools_registry.py"
  },
  {
    "name": "ha_remove_device",
    "title": "Remove Device",
    "description": "Remove an orphaned device from the Home Assistant device registry.\n\nWARNING: This removes the device entry from the registry.\n- Use only for orphaned devices that are no longer connected\n- Active devices will typically be re-added by their integration\n- Associated entities may also be removed\n\nThis uses the config entry removal which is the safe way to remove devices.\nIf the device has multiple config entries, they must all be removed.\n\nEXAMPLES:\n- Remove orphaned device: ha_remove_device(\"abc123def456\")\n\nNOTE: For most use cases, consider disabling the device instead:\nha_update_device(device_id=\"abc123\", disabled_by=\"user\")",
    "inputSchema": {
      "properties": {
        "device_id": {
          "type": "Annotated[str, Field(description='Device ID to remove from the registry')]"
        }
      },
      "required": [
        "device_id"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": true
    },
    "tags": [
      "Device Registry"
    ],
    "source_file": "tools_registry.py"
  },
  {
    "name": "ha_rename_entity",
    "title": "Rename Entity",
    "description": "Rename a Home Assistant entity by changing its entity_id, optionally renaming its device too.\n\nChanges the entity_id (e.g., light.old_name -> light.new_name).\nThe domain must remain the same - you cannot change a light to a switch.\n\nDEVICE RENAME:\nProvide new_device_name to also rename the device associated with this entity.\nThe device is looked up automatically from the entity registry.\n\nVOICE ASSISTANT EXPOSURE:\nBy default, this function preserves voice assistant exposure settings\n(Alexa, Google Assistant, Assist) when renaming. The exposure settings\nare stored separately from the entity registry and must be migrated\nmanually. Set preserve_voice_exposure=False to skip this migration.\n\nIMPORTANT LIMITATIONS:\n- References in automations/scripts/dashboards are NOT automatically updated\n- Entity history is preserved (HA 2022.4+)\n- Some entities cannot be renamed:\n  - Entities without unique IDs\n  - Entities disabled by integration\n\nEXAMPLES:\n- Rename light: ha_rename_entity(\"light.bedroom_1\", \"light.master_bedroom\")\n- Rename with friendly name: ha_rename_entity(\"sensor.temp\", \"sensor.living_room_temp\", name=\"Living Room Temperature\")\n- Rename entity and device: ha_rename_entity(\"light.bedroom_1\", \"light.master_bedroom\", new_device_name=\"Master Bedroom Lamp\")\n- Rename without exposure migration: ha_rename_entity(\"light.old\", \"light.new\", preserve_voice_exposure=False)\n\nNOTE: Device and entity renaming are independent in HA. Renaming a device does\nNOT rename its entities. See ha_update_device() for device-only renaming.",
    "inputSchema": {
      "properties": {
        "entity_id": {
          "type": "Annotated[str, Field(description=\"Current entity ID to rename (e.g., 'light.old_name')\")]"
        },
        "new_entity_id": {
          "type": "Annotated[str, Field(description=\"New entity ID (e.g., 'light.new_name'). Domain must match the original.\")]"
        },
        "name": {
          "type": "Annotated[str | None, Field(description='Optional: New friendly name for the entity', default=None)]",
          "default": null
        },
        "icon": {
          "type": "Annotated[str | None, Field(description=\"Optional: New icon (e.g., 'mdi:lightbulb')\", default=None)]",
          "default": null
        },
        "new_device_name": {
          "type": "Annotated[str | None, Field(description='Optional: New display name for the associated device. If provided, both entity and device are renamed in one operation.', default=None)]",
          "default": null
        },
        "preserve_voice_exposure": {
          "type": "Annotated[bool | str | None, Field(description='Migrate voice assistant exposure settings to the new entity_id. Defaults to True. Set to False to skip exposure migration.', default=None)]",
          "default": null
        }
      },
      "required": [
        "entity_id",
        "new_entity_id"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Device Registry"
    ],
    "source_file": "tools_registry.py"
  },
  {
    "name": "ha_update_device",
    "title": "Update Device",
    "description": "Update device properties such as name, area, disabled state, or labels.\n\nIMPORTANT: Renaming a device does NOT rename its entities!\nDevice and entity names are independent. To rename entities, use ha_rename_entity().\n\nCommon workflow for full rename:\n1. ha_update_device(device_id=\"abc\", name=\"Living Room Sensor\")  # Rename device\n2. ha_rename_entity(entity_id=\"sensor.old\", new_entity_id=\"sensor.living_room\")  # Rename entities separately\n\nPARAMETERS:\n- name: Sets the user-defined display name (name_by_user)\n- area_id: Assigns device to an area/room. Use '' to remove from area.\n- disabled_by: Set to 'user' to disable, or empty to enable\n- labels: List of labels (replaces existing labels)\n\nEXAMPLES:\n- Rename device: ha_update_device(\"abc123\", name=\"Living Room Hub\")\n- Move to area: ha_update_device(\"abc123\", area_id=\"living_room\")\n- Disable device: ha_update_device(\"abc123\", disabled_by=\"user\")\n- Enable device: ha_update_device(\"abc123\", disabled_by=\"\")\n- Add labels: ha_update_device(\"abc123\", labels=[\"important\", \"sensor\"])",
    "inputSchema": {
      "properties": {
        "device_id": {
          "type": "Annotated[str, Field(description='Device ID to update')]"
        },
        "name": {
          "type": "Annotated[str | None, Field(description='New display name for the device (sets name_by_user)', default=None)]",
          "default": null
        },
        "area_id": {
          "type": "Annotated[str | None, Field(description=\"Area/room ID to assign the device to. Use empty string '' to unassign.\", default=None)]",
          "default": null
        },
        "disabled_by": {
          "type": "Annotated[str | None, Field(description=\"Set to 'user' to disable, or None/empty string to enable\", default=None)]",
          "default": null
        },
        "labels": {
          "type": "Annotated[str | list[str] | None, Field(description='Labels to assign to the device (replaces existing labels)', default=None)]",
          "default": null
        }
      },
      "required": [
        "device_id"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Device Registry"
    ],
    "source_file": "tools_registry.py"
  },
  {
    "name": "ha_get_entity",
    "title": "Get Entity",
    "description": "Get entity registry information for one or more entities.\n\nReturns detailed entity registry metadata including area assignment,\ncustom name/icon, enabled/hidden state, aliases, labels, and more.\n\nRELATED TOOLS:\n- ha_set_entity(): Modify entity properties (area, name, icon, enabled, hidden, aliases)\n- ha_get_state(): Get current state/attributes (on/off, temperature, etc.)\n- ha_search_entities(): Find entities by name, domain, or area\n\nEXAMPLES:\n- Single entity: ha_get_entity(\"sensor.temperature\")\n- Multiple entities: ha_get_entity([\"light.living_room\", \"switch.porch\"])\n\nRESPONSE FIELDS:\n- entity_id: Full entity identifier\n- name: Custom display name (null if using original_name)\n- original_name: Default name from integration\n- icon: Custom icon (null if using default)\n- area_id: Assigned area/room ID (null if unassigned)\n- disabled_by: Why disabled (null=enabled, \"user\"/\"integration\"/etc)\n- hidden_by: Why hidden (null=visible, \"user\"/\"integration\"/etc)\n- enabled: Boolean shorthand (True if disabled_by is null)\n- hidden: Boolean shorthand (True if hidden_by is not null)\n- aliases: Voice assistant aliases\n- labels: Assigned label IDs\n- categories: Category assignments (dict mapping scope to category_id)\n- platform: Integration platform (e.g., \"hue\", \"zwave_js\")\n- device_id: Associated device ID (null if standalone)\n- unique_id: Integration's unique identifier",
    "inputSchema": {
      "properties": {
        "entity_id": {
          "type": "Annotated[str | list[str], Field(description=\"Entity ID or list of entity IDs to retrieve (e.g., 'sensor.temperature' or ['light.living_room', 'switch.porch'])\")]"
        }
      },
      "required": [
        "entity_id"
      ]
    },
    "annotations": {
      "readOnlyHint": true,
      "idempotentHint": true
    },
    "tags": [
      "Entity Registry"
    ],
    "source_file": "tools_entities.py"
  },
  {
    "name": "ha_get_entity_exposure",
    "title": "Get Entity Exposure",
    "description": "Get entity exposure settings - list all or get settings for a specific entity.\n\nWithout an entity_id: Lists all entities and their exposure status to\nvoice assistants (Alexa, Google Assistant, Assist).\n\nWith an entity_id: Returns which voice assistants the specific entity\nis exposed to.\n\nEXAMPLES:\n- List all exposures: ha_get_entity_exposure()\n- Filter by assistant: ha_get_entity_exposure(assistant=\"cloud.alexa\")\n- Get specific entity: ha_get_entity_exposure(entity_id=\"light.living_room\")\n\nRETURNS (when listing):\n- exposed_entities: Dict mapping entity_ids to their exposure status\n- summary: Count of entities exposed to each assistant\n\nRETURNS (when getting specific entity):\n- exposed_to: Dict of assistant -> True/False for each assistant\n- is_exposed_anywhere: True if exposed to at least one assistant",
    "inputSchema": {
      "properties": {
        "entity_id": {
          "type": "Annotated[str | None, Field(description='Entity ID to check exposure settings for. If omitted, lists all entities with exposure settings.', default=None)]",
          "default": null
        },
        "assistant": {
          "type": "Annotated[str | None, Field(description=\"Filter by assistant: 'conversation', 'cloud.alexa', or 'cloud.google_assistant'. If not specified, returns all.\", default=None)]",
          "default": null
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Entity Registry"
    ],
    "source_file": "tools_voice_assistant.py"
  },
  {
    "name": "ha_set_entity",
    "title": "Set Entity",
    "description": "Update entity properties in the entity registry.\n\nAllows modifying entity metadata such as area assignment, display name,\nicon, enabled/disabled state, visibility, aliases, labels, and voice\nassistant exposure in a single call.\n\nBULK OPERATIONS:\nWhen entity_id is a list, only labels and expose_to parameters are supported.\nOther parameters (area_id, name, icon, enabled, hidden, aliases) require single entity.\n\nLABEL OPERATIONS:\n- label_operation=\"set\" (default): Replace all labels with the provided list. Use [] to clear.\n- label_operation=\"add\": Add labels to existing ones without removing any.\n- label_operation=\"remove\": Remove specified labels from the entity.\n\nUse ha_search_entities() or ha_get_device() to find entity IDs.\nUse ha_config_get_label() to find available label IDs.\n\nEXAMPLES:\nSingle entity:\n- Assign to area: ha_set_entity(\"sensor.temp\", area_id=\"living_room\")\n- Rename: ha_set_entity(\"sensor.temp\", name=\"Living Room Temperature\")\n- Set labels: ha_set_entity(\"light.lamp\", labels=[\"outdoor\", \"smart\"])\n- Add labels: ha_set_entity(\"light.lamp\", labels=[\"new_label\"], label_operation=\"add\")\n- Remove labels: ha_set_entity(\"light.lamp\", labels=[\"old_label\"], label_operation=\"remove\")\n- Clear labels: ha_set_entity(\"light.lamp\", labels=[])\n- Expose to Alexa: ha_set_entity(\"light.lamp\", expose_to={\"cloud.alexa\": True})\n\nBulk operations:\n- Set labels on multiple: ha_set_entity([\"light.a\", \"light.b\"], labels=[\"outdoor\"])\n- Add labels to multiple: ha_set_entity([\"light.a\", \"light.b\"], labels=[\"new\"], label_operation=\"add\")\n- Expose multiple to Alexa: ha_set_entity([\"light.a\", \"light.b\"], expose_to={\"cloud.alexa\": True})\n\nNOTE: To rename an entity_id (e.g., sensor.old -> sensor.new), use ha_rename_entity() instead.\n\nENABLED/DISABLED WARNING:\nSetting enabled=False performs a **registry-level disable** — the entity is completely\nremoved from the Home Assistant state machine and hidden from the UI. It will NOT appear\nin state queries, dashboards, or automations until re-enabled AND the integration is\nreloaded. This is NOT the same as \"turning off\" an entity.\n\nFor automations and scripts, enabled=False is blocked. Use these instead:\n- ha_call_service(\"automation\", \"turn_off\", entity_id=\"automation.xxx\")\n- ha_call_service(\"script\", \"turn_off\", entity_id=\"script.xxx\")",
    "inputSchema": {
      "properties": {
        "entity_id": {
          "type": "Annotated[str | list[str], Field(description='Entity ID or list of entity IDs to update. Bulk operations (list) only support labels and expose_to parameters.')]"
        },
        "area_id": {
          "type": "Annotated[str | None, Field(description=\"Area/room ID to assign the entity to. Use empty string '' to unassign from current area. Single entity only.\", default=None)]",
          "default": null
        },
        "name": {
          "type": "Annotated[str | None, Field(description=\"Display name for the entity. Use empty string '' to remove custom name and revert to default. Single entity only.\", default=None)]",
          "default": null
        },
        "icon": {
          "type": "Annotated[str | None, Field(description=\"Icon for the entity (e.g., 'mdi:thermometer'). Use empty string '' to remove custom icon. Single entity only.\", default=None)]",
          "default": null
        },
        "enabled": {
          "type": "Annotated[bool | str | None, Field(description='True to enable the entity, False to disable it. Single entity only. WARNING: Setting enabled=False is a registry-level disable — it completely removes the entity from the state machine and hides it from the UI. A reload or restart is required to restore it after re-enabling. NOT allowed for automation or script entities — use automation.turn_off / script.turn_off via ha_call_service() instead.', default=None)]",
          "default": null
        },
        "hidden": {
          "type": "Annotated[bool | str | None, Field(description='True to hide the entity from UI, False to show it. Single entity only.', default=None)]",
          "default": null
        },
        "aliases": {
          "type": "Annotated[str | list[str] | None, Field(description='List of voice assistant aliases for the entity (replaces existing aliases). Single entity only.', default=None)]",
          "default": null
        },
        "categories": {
          "type": "Annotated[str | dict[str, str | None] | None, Field(description='Category assignment as a dict mapping scope to category_id. Example: {\"automation\": \"category_id_here\"}. Use null value to clear: {\"automation\": null}. Single entity only.', default=None)]",
          "default": null
        },
        "labels": {
          "type": "Annotated[str | list[str] | None, Field(description='List of label IDs for the entity. Behavior depends on label_operation parameter. Supports bulk operations.', default=None)]",
          "default": null
        },
        "label_operation": {
          "type": "Annotated[Literal['set', 'add', 'remove'], Field(description=\"How to apply labels: 'set' replaces all labels, 'add' adds to existing, 'remove' removes specified labels.\", default='set')]",
          "default": "set"
        },
        "expose_to": {
          "type": "Annotated[str | dict[str, bool] | None, Field(description='Control voice assistant exposure. Pass a dict mapping assistant IDs to booleans. Valid assistants: \\'conversation\\' (Assist), \\'cloud.alexa\\', \\'cloud.google_assistant\\'. Example: {\"conversation\": true, \"cloud.alexa\": false}. Supports bulk operations.', default=None)]",
          "default": null
        }
      },
      "required": [
        "entity_id"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": true
    },
    "tags": [
      "Entity Registry"
    ],
    "source_file": "tools_entities.py"
  },
  {
    "name": "ha_delete_file",
    "title": "Delete File",
    "description": "Delete a file from allowed directories in the Home Assistant config.\n\nPermanently removes a file from the allowed directories. This action\ncannot be undone.\n\n**Allowed Delete Directories:**\n- `www/` - Web assets\n- `themes/` - Theme files\n- `custom_templates/` - Template files\n\n**Security:**\n- Only the directories above allow deletions\n- Configuration files cannot be deleted\n- Path traversal (../) is blocked\n- Requires confirm=True to prevent accidents\n\n**Returns:**\n- success: Whether the operation succeeded\n- path: The file path that was deleted\n- message: Confirmation message\n\n**Example:**\n```python\n# Delete an old CSS file\nresult = ha_delete_file(\n    path=\"www/deprecated-style.css\",\n    confirm=True\n)\n```",
    "inputSchema": {
      "properties": {
        "path": {
          "type": "Annotated[str, Field(description=\"Relative path from config directory. Must be in www/, themes/, or custom_templates/. Example: 'www/old-file.css'\")]"
        },
        "confirm": {
          "type": "Annotated[bool | str, Field(default=False, description='Must be True to confirm deletion. This is a safety measure to prevent accidental deletions.')]",
          "default": false
        }
      },
      "required": [
        "path"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Files"
    ],
    "source_file": "tools_filesystem.py"
  },
  {
    "name": "ha_list_files",
    "title": "List Files",
    "description": "List files in a directory within the Home Assistant config directory.\n\nLists files in allowed directories (www/, themes/, custom_templates/) with\noptional glob pattern filtering. Returns file names, sizes, and modification times.\n\n**Allowed Directories:**\n- `www/` - Web assets (CSS, JS, images for dashboards)\n- `themes/` - Theme files\n- `custom_templates/` - Jinja2 template files\n\n**Security:** Only directories in the allowed list can be accessed.\nPath traversal attempts (../) are blocked.\n\n**Returns:**\n- success: Whether the operation succeeded\n- path: The directory path that was listed\n- files: List of file info objects with name, size, is_dir, modified\n- count: Number of files found\n\n**Example:**\n```python\n# List all CSS files in www/\nresult = ha_list_files(path=\"www/\", pattern=\"*.css\")\n```",
    "inputSchema": {
      "properties": {
        "path": {
          "type": "Annotated[str, Field(description=\"Relative directory path from config directory. Allowed paths: www/, themes/, custom_templates/. Example: 'www/' or 'themes/my_theme'\")]"
        },
        "pattern": {
          "type": "Annotated[str | None, Field(default=None, description=\"Optional glob pattern to filter files. Example: '*.css', '*.yaml', '*.js'\")]",
          "default": null
        }
      },
      "required": [
        "path"
      ]
    },
    "annotations": {
      "readOnlyHint": true
    },
    "tags": [
      "Files"
    ],
    "source_file": "tools_filesystem.py"
  },
  {
    "name": "ha_read_file",
    "title": "Read File",
    "description": "Read a file from the Home Assistant config directory.\n\nReads files from allowed paths within the config directory. Some files\nhave special handling:\n- `secrets.yaml`: Values are masked for security\n- `home-assistant.log`: Limited to tail (last N lines) by default\n\n**Allowed Read Paths:**\n- `configuration.yaml`, `automations.yaml`, `scripts.yaml`, `scenes.yaml`\n- `secrets.yaml` (values masked)\n- `packages/*.yaml`\n- `home-assistant.log` (tail only)\n- `www/**`, `themes/**`, `custom_templates/**`\n- `custom_components/**/*.py` (read-only)\n\n**Security:**\n- Path traversal (../) is blocked\n- Only allowed paths can be read\n- Sensitive data in secrets.yaml is masked\n\n**Returns:**\n- success: Whether the operation succeeded\n- content: The file content (may be truncated for logs)\n- size: File size in bytes\n- modified: Last modification timestamp\n- path: The file path that was read\n\n**Example:**\n```python\n# Read configuration\nresult = ha_read_file(path=\"configuration.yaml\")\n\n# Read last 100 lines of log\nresult = ha_read_file(path=\"home-assistant.log\", tail_lines=100)\n```",
    "inputSchema": {
      "properties": {
        "path": {
          "type": "Annotated[str, Field(description=\"Relative path from config directory. Examples: 'configuration.yaml', 'www/custom.css', 'home-assistant.log'\")]"
        },
        "tail_lines": {
          "type": "Annotated[int | str | None, Field(default=None, description='For log files, return only the last N lines. Recommended for home-assistant.log to avoid large responses. Default: None (return full file, or last 1000 lines for logs)')]",
          "default": null
        }
      },
      "required": [
        "path"
      ]
    },
    "annotations": {
      "readOnlyHint": true
    },
    "tags": [
      "Files"
    ],
    "source_file": "tools_filesystem.py"
  },
  {
    "name": "ha_write_file",
    "title": "Write File",
    "description": "Write a file to allowed directories in the Home Assistant config.\n\nCreates or updates files in restricted directories only. This is useful for:\n- Creating custom CSS/JS for dashboards\n- Adding theme files\n- Creating Jinja2 templates\n\n**Allowed Write Directories:**\n- `www/` - Web assets for dashboards\n- `themes/` - Theme YAML files\n- `custom_templates/` - Jinja2 template files\n\n**Security:**\n- Only the directories above allow writes\n- Configuration files (configuration.yaml, etc.) cannot be written\n- Path traversal (../) is blocked\n\n**Returns:**\n- success: Whether the operation succeeded\n- path: The file path that was written\n- size: Size of the written file in bytes\n- created: Whether this was a new file (vs overwrite)\n\n**Example:**\n```python\n# Create a custom CSS file\nresult = ha_write_file(\n    path=\"www/custom-dashboard.css\",\n    content=\".card { background: #333; }\",\n    overwrite=True\n)\n\n# Create a theme file\nresult = ha_write_file(\n    path=\"themes/dark_blue.yaml\",\n    content=\"Dark Blue:\\n  primary-color: '#1a237e'\",\n    overwrite=False\n)\n```",
    "inputSchema": {
      "properties": {
        "path": {
          "type": "Annotated[str, Field(description=\"Relative path from config directory. Must be in www/, themes/, or custom_templates/. Example: 'www/custom.css', 'themes/my_theme.yaml'\")]"
        },
        "content": {
          "type": "Annotated[str, Field(description='The content to write to the file.')]"
        },
        "overwrite": {
          "type": "Annotated[bool | str, Field(default=False, description='Whether to overwrite if file exists. Default is False to prevent accidental overwrites.')]",
          "default": false
        },
        "create_dirs": {
          "type": "Annotated[bool | str, Field(default=True, description=\"Whether to create parent directories if they don't exist. Default is True.\")]",
          "default": true
        }
      },
      "required": [
        "path",
        "content"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Files"
    ],
    "source_file": "tools_filesystem.py"
  },
  {
    "name": "ha_config_list_groups",
    "title": "List Groups",
    "description": "List all Home Assistant entity groups with their member entities.\n\nReturns all groups created via group.set service or YAML configuration,\nincluding:\n- Entity ID (group.xxx)\n- Friendly name\n- State (on/off based on member states)\n- Member entities\n- Icon (if set)\n- All mode (if all entities must be on)\n\nEXAMPLES:\n- List all groups: ha_config_list_groups()\n\n**NOTE:** This returns old-style groups (created via group.set or YAML).\nPlatform-specific groups (light groups, cover groups) are separate entities.",
    "inputSchema": {},
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Groups"
    ],
    "source_file": "tools_groups.py"
  },
  {
    "name": "ha_config_remove_group",
    "title": "Remove Group",
    "description": "Remove a Home Assistant entity group.\n\nUses the group.remove service to delete the group.\n\nEXAMPLES:\n- Remove group: ha_config_remove_group(\"living_room_lights\")\n\nUse ha_config_list_groups() to find existing groups.\n\n**WARNING:**\n- Removing a group used in automations may cause those automations to fail.\n- Groups defined in YAML can be removed at runtime but will reappear after restart.\n- This only removes old-style groups, not platform-specific groups.",
    "inputSchema": {
      "properties": {
        "object_id": {
          "type": "Annotated[str, Field(description=\"Group identifier without 'group.' prefix (e.g., 'living_room_lights')\")]"
        }
      },
      "required": [
        "object_id"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": true
    },
    "tags": [
      "Groups"
    ],
    "source_file": "tools_groups.py"
  },
  {
    "name": "ha_config_set_group",
    "title": "Create or Update Group",
    "description": "Create or update a Home Assistant entity group.\n\nUses the group.set service to create a new group or update an existing one.\nGroups are useful for organizing entities and controlling them together.\n\n**For NEW groups:** Provide object_id and entities (required).\n**For EXISTING groups:** Provide object_id and any fields to update.\n\nEXAMPLES:\n- Create group: ha_config_set_group(\"bedroom_lights\", entities=[\"light.lamp\", \"light.ceiling\"])\n- Create with name: ha_config_set_group(\"sensors\", entities=[\"sensor.temp\"], name=\"All Sensors\")\n- Update name: ha_config_set_group(\"lights\", name=\"Living Room Lights\")\n- Add entities: ha_config_set_group(\"lights\", add_entities=[\"light.extra\"])\n- Remove entities: ha_config_set_group(\"lights\", remove_entities=[\"light.old\"])\n- Replace all entities: ha_config_set_group(\"lights\", entities=[\"light.new1\", \"light.new2\"])\n\n**NOTE:** entities, add_entities, and remove_entities are mutually exclusive.",
    "inputSchema": {
      "properties": {
        "object_id": {
          "type": "Annotated[str, Field(description=\"Group identifier without 'group.' prefix (e.g., 'living_room_lights')\")]"
        },
        "entities": {
          "type": "Annotated[list[str] | None, Field(description='List of entity IDs for the group. Required when creating new group. When updating, replaces all entities (mutually exclusive with add_entities/remove_entities).', default=None)]",
          "default": null
        },
        "name": {
          "type": "Annotated[str | None, Field(description='Friendly display name for the group', default=None)]",
          "default": null
        },
        "icon": {
          "type": "Annotated[str | None, Field(description=\"Material Design Icon (e.g., 'mdi:lightbulb-group')\", default=None)]",
          "default": null
        },
        "all_on": {
          "type": "Annotated[bool | None, Field(description='If True, all entities must be on for group to be on (default: False)', default=None)]",
          "default": null
        },
        "add_entities": {
          "type": "Annotated[list[str] | None, Field(description='Add these entities to an existing group (mutually exclusive with entities)', default=None)]",
          "default": null
        },
        "remove_entities": {
          "type": "Annotated[list[str] | None, Field(description='Remove these entities from an existing group (mutually exclusive with entities)', default=None)]",
          "default": null
        }
      },
      "required": [
        "object_id"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Groups"
    ],
    "source_file": "tools_groups.py"
  },
  {
    "name": "ha_hacs_add_repository",
    "title": "Add HACS Repository",
    "description": "Add a custom GitHub repository to HACS.\n\nAllows adding custom repositories that are not in the default HACS store.\nThis is useful for:\n- Adding custom integrations from GitHub\n- Installing custom Lovelace cards\n- Adding custom themes\n- Installing beta/development versions\n\n**Requirements:**\n- Repository must be a valid GitHub repository\n- Repository must follow HACS structure guidelines\n- Category must match the repository type\n\n**Examples:**\n```python\n# Add custom integration\nha_hacs_add_repository(\"owner/custom-integration\", category=\"integration\")\n\n# Add custom card\nha_hacs_add_repository(\"owner/custom-card\", category=\"lovelace\")\n\n# Add custom theme\nha_hacs_add_repository(\"owner/custom-theme\", category=\"theme\")\n```\n\nArgs:\n    repository: GitHub repository in format \"owner/repo\"\n    category: Repository category (integration, lovelace, theme, appdaemon, python_script)\n\nReturns:\n    Success status and repository ID if added successfully.",
    "inputSchema": {
      "properties": {
        "repository": {
          "type": "str"
        },
        "category": {
          "type": "Annotated[Literal['integration', 'lovelace', 'theme', 'appdaemon', 'python_script'], Field(description='Repository category (required)')]"
        }
      },
      "required": [
        "repository",
        "category"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "HACS"
    ],
    "source_file": "tools_hacs.py"
  },
  {
    "name": "ha_hacs_download",
    "title": "Download/Install HACS Repository",
    "description": "Download and install a HACS repository.\n\nThis installs a repository from HACS to your Home Assistant instance.\nFor integrations, a restart of Home Assistant may be required after installation.\n\n**Prerequisites:**\n- The repository must already be in HACS (either from the default store or added via `ha_hacs_add_repository`)\n- Use `ha_hacs_search()` or `ha_hacs_list_installed()` to find the repository ID\n\n**Examples:**\n```python\n# Install latest version of a repository\nha_hacs_download(\"441028036\")\n\n# Install specific version\nha_hacs_download(\"441028036\", version=\"v2.0.0\")\n\n# Install by GitHub path (will look up the numeric ID)\nha_hacs_download(\"piitaya/lovelace-mushroom\", version=\"v4.0.0\")\n```\n\n**Note:** For integrations, you may need to restart Home Assistant after installation.\nFor Lovelace cards, clear your browser cache to see the new card.\n\nArgs:\n    repository_id: Repository numeric ID or GitHub path (e.g., \"441028036\" or \"owner/repo\")\n    version: Specific version to install (optional, defaults to latest)\n\nReturns:\n    Success status and installation details.",
    "inputSchema": {
      "properties": {
        "repository_id": {
          "type": "str"
        },
        "version": {
          "type": "Annotated[str | None, Field(default=None, description=\"Specific version to install (e.g., 'v1.2.3'). If not specified, installs the latest version.\")]",
          "default": null
        }
      },
      "required": [
        "repository_id"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "HACS"
    ],
    "source_file": "tools_hacs.py"
  },
  {
    "name": "ha_hacs_info",
    "title": "Get HACS Info",
    "description": "Get HACS status, version, and enabled categories.\n\nReturns information about the HACS installation including:\n- Version number\n- Enabled categories (integration, lovelace, theme, etc.)\n- Stage (running, startup, etc.)\n- Lovelace mode\n- Disabled reason (if any)\n\nThis is useful for validating that HACS is installed and operational\nbefore using other HACS tools.\n\n**HACS Installation:**\nIf HACS is not installed, visit https://hacs.xyz/ for installation instructions.\n\nReturns:\n    Dictionary with HACS status information or error if HACS is not available.",
    "inputSchema": {},
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "HACS"
    ],
    "source_file": "tools_hacs.py"
  },
  {
    "name": "ha_hacs_list_installed",
    "title": "List HACS Installed",
    "description": "List installed HACS repositories with focused, small response.\n\n**DASHBOARD TIP:** Use `category=\"lovelace\"` to discover installed custom cards\nfor use with `ha_config_set_dashboard()`.\n\nReturns a list of installed repositories with key information:\n- name: Repository name\n- full_name: Full GitHub repository name (owner/repo)\n- category: Type of repository (integration, lovelace, theme, etc.)\n- installed_version: Currently installed version\n- available_version: Latest available version\n- pending_update: Whether an update is available\n- description: Repository description\n\n**Categories:**\n- `integration`: Custom integrations and components\n- `lovelace`: Custom dashboard cards and panels\n- `theme`: Custom themes for the UI\n- `appdaemon`: AppDaemon apps\n- `python_script`: Python scripts\n\nArgs:\n    category: Filter results by category (default: all categories)\n\nReturns:\n    List of installed HACS repositories or error if HACS is not available.",
    "inputSchema": {
      "properties": {
        "category": {
          "type": "Annotated[Literal['integration', 'lovelace', 'theme', 'appdaemon', 'python_script'] | None, Field(default=None, description=\"Filter by category: 'integration', 'lovelace', 'theme', 'appdaemon', or 'python_script'. Use None for all categories.\")]",
          "default": null
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "HACS"
    ],
    "source_file": "tools_hacs.py"
  },
  {
    "name": "ha_hacs_repository_info",
    "title": "Get HACS Repository Info",
    "description": "Get detailed repository information including README and documentation.\n\nReturns comprehensive information about a HACS repository:\n- Basic info (name, description, category, authors)\n- Installation status and versions\n- README content (useful for configuration examples)\n- Available releases and versions\n- GitHub stats (stars, issues)\n- Configuration examples (if available)\n\n**Use Cases:**\n- Get card configuration examples: `ha_hacs_repository_info(\"441028036\")`\n- Check integration setup instructions\n- Find theme customization options\n\n**Note:** The repository_id is the numeric ID from HACS, not the GitHub path.\nUse `ha_hacs_list_installed()` or `ha_hacs_search()` to find the numeric ID.\n\nArgs:\n    repository_id: Repository numeric ID (e.g., \"441028036\") or GitHub path (e.g., \"dvd-dev/hilo\")\n\nReturns:\n    Detailed repository information or error if not found.",
    "inputSchema": {
      "properties": {
        "repository_id": {
          "type": "str"
        }
      },
      "required": [
        "repository_id"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "HACS"
    ],
    "source_file": "tools_hacs.py"
  },
  {
    "name": "ha_hacs_search",
    "title": "Search HACS Store",
    "description": "Search HACS store for repositories by keyword with pagination.\n\nSearches the HACS store for repositories matching the query string.\nReturns repository information including stars, downloads, and descriptions.\n\n**Use Cases:**\n- Find custom cards: `ha_hacs_search(\"mushroom\", category=\"lovelace\")`\n- Find integrations: `ha_hacs_search(\"nest\", category=\"integration\")`\n- Browse themes: `ha_hacs_search(\"dark\", category=\"theme\")`\n\nResults include:\n- name: Repository name\n- full_name: Full GitHub repository name\n- description: Repository description\n- category: Type of repository\n- stars: GitHub stars count\n- downloads: Number of HACS installations\n- authors: Repository authors\n- installed: Whether already installed\n\nArgs:\n    query: Search query (repository name, description, author)\n    category: Filter by category (optional)\n    max_results: Maximum results to return (default: 10, max: 100)\n    offset: Number of results to skip for pagination (default: 0)\n\nReturns:\n    Search results from HACS store or error if HACS is not available.",
    "inputSchema": {
      "properties": {
        "query": {
          "type": "str"
        },
        "category": {
          "type": "Annotated[Literal['integration', 'lovelace', 'theme', 'appdaemon', 'python_script'] | None, Field(default=None, description='Filter by category (optional)')]",
          "default": null
        },
        "max_results": {
          "type": "Annotated[int | str, Field(default=10, description='Maximum number of results to return (default: 10, max: 100)')]",
          "default": 10
        },
        "offset": {
          "type": "Annotated[int | str, Field(default=0, description='Number of results to skip for pagination (default: 0)')]",
          "default": 0
        }
      },
      "required": [
        "query"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "HACS"
    ],
    "source_file": "tools_hacs.py"
  },
  {
    "name": "ha_config_list_helpers",
    "title": "List Helpers",
    "description": "List all Home Assistant helpers of a specific type with their configurations.\n\nReturns complete configuration for all helpers of the specified type including:\n- ID, name, icon\n- Type-specific settings (min/max for input_number, options for input_select, etc.)\n- Area and label assignments\n\nSUPPORTED HELPER TYPES:\n- input_button: Virtual buttons for triggering automations\n- input_boolean: Toggle switches/checkboxes\n- input_select: Dropdown selection lists\n- input_number: Numeric sliders/input boxes\n- input_text: Text input fields\n- input_datetime: Date/time pickers\n- counter: Counters with increment/decrement/reset\n- timer: Countdown timers with start/pause/cancel\n- schedule: Weekly schedules with time ranges (on/off per day)\n- zone: Geographical zones for presence detection\n- person: Person entities linked to device trackers\n- tag: NFC/QR tags for automation triggers\n\nEXAMPLES:\n- List all number helpers: ha_config_list_helpers(\"input_number\")\n- List all counters: ha_config_list_helpers(\"counter\")\n- List all zones: ha_config_list_helpers(\"zone\")\n- List all persons: ha_config_list_helpers(\"person\")\n- List all tags: ha_config_list_helpers(\"tag\")\n\n**NOTE:** This only returns storage-based helpers (created via UI/API), not YAML-defined helpers.\n\nFor detailed helper documentation, use ha_get_skill_home_assistant_best_practices.",
    "inputSchema": {
      "properties": {
        "helper_type": {
          "type": "Annotated[Literal['input_button', 'input_boolean', 'input_select', 'input_number', 'input_text', 'input_datetime', 'counter', 'timer', 'schedule', 'zone', 'person', 'tag'], Field(description='Type of helper entity to list')]"
        }
      },
      "required": [
        "helper_type"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Helper Entities"
    ],
    "source_file": "tools_config_helpers.py"
  },
  {
    "name": "ha_config_remove_helper",
    "title": "Remove Helper",
    "description": "Delete a Home Assistant helper entity.\n\nSUPPORTED HELPER TYPES:\n- input_button, input_boolean, input_select, input_number, input_text, input_datetime\n- counter, timer, schedule, zone, person, tag\n\nEXAMPLES:\n- Delete button: ha_config_remove_helper(\"input_button\", \"my_button\")\n- Delete counter: ha_config_remove_helper(\"counter\", \"my_counter\")\n- Delete timer: ha_config_remove_helper(\"timer\", \"my_timer\")\n- Delete schedule: ha_config_remove_helper(\"schedule\", \"work_hours\")\n\n**WARNING:** Deleting a helper that is used by automations or scripts may cause those automations/scripts to fail.\nUse ha_search_entities() to verify the helper exists before attempting to delete it.",
    "inputSchema": {
      "properties": {
        "helper_type": {
          "type": "Annotated[Literal['input_button', 'input_boolean', 'input_select', 'input_number', 'input_text', 'input_datetime', 'counter', 'timer', 'schedule', 'zone', 'person', 'tag'], Field(description='Type of helper entity to delete')]"
        },
        "helper_id": {
          "type": "Annotated[str, Field(description=\"Helper ID to delete (e.g., 'my_button' or 'input_button.my_button')\")]"
        },
        "wait": {
          "type": "Annotated[bool | str, Field(description='Wait for helper entity to be fully removed before returning. Default: True.', default=True)]",
          "default": true
        }
      },
      "required": [
        "helper_type",
        "helper_id"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": true
    },
    "tags": [
      "Helper Entities"
    ],
    "source_file": "tools_config_helpers.py"
  },
  {
    "name": "ha_config_set_helper",
    "title": "Create or Update Helper",
    "description": "Create or update Home Assistant helper entities.\n\nCreates new helper if helper_id is omitted, updates existing if helper_id is provided.\nParameters are validated by Home Assistant - errors return clear messages.\n\nQUICK EXAMPLES:\n- ha_config_set_helper(\"input_boolean\", \"My Switch\", icon=\"mdi:toggle-switch\")\n- ha_config_set_helper(\"counter\", \"My Counter\", initial=0, step=1)\n- ha_config_set_helper(\"timer\", \"Laundry\", duration=\"0:45:00\")\n- ha_config_set_helper(\"zone\", \"Office\", latitude=37.77, longitude=-122.41, radius=100)\n- ha_config_set_helper(\"schedule\", \"Work\", monday=[{\"from\": \"09:00\", \"to\": \"17:00\"}])\n- ha_config_set_helper(\"schedule\", \"Light\", monday=[{\"from\": \"07:00\", \"to\": \"22:00\", \"data\": {\"brightness\": \"100\", \"mode\": \"comfort\"}}])\n\nTEMPLATE SENSORS AND BINARY SENSORS:\nUse ha_set_config_entry_helper(helper_type=\"template\", ...) — not this tool.\nTemplate helpers are managed via the Config Entry Flow API.\nBefore reaching for a template, check if a simpler built-in exists:\n- min_max instead of template for combining sensors\n- group instead of template binary sensor for any/all logic\n- counter instead of template with math for counting\n- input_number instead of template for storing values\n- schedule instead of template with weekday checks\nWorkflow:\n  1. ha_get_helper_schema(\"template\") → see available sub-types\n  2. ha_get_helper_schema(\"template\", menu_option=\"sensor\") → see form fields\n  3. ha_set_config_entry_helper(\"template\", {\n       \"next_step_id\": \"sensor\",\n       \"name\": \"My Sensor\",\n       \"state\": \"{{ states('sensor.foo') }}\",\n     })\n\nFor detailed parameter info, use ha_get_skill_home_assistant_best_practices.",
    "inputSchema": {
      "properties": {
        "helper_type": {
          "type": "Annotated[Literal['input_button', 'input_boolean', 'input_select', 'input_number', 'input_text', 'input_datetime', 'counter', 'timer', 'schedule', 'zone', 'person', 'tag'], Field(description='Type of helper entity to create or update')]"
        },
        "name": {
          "type": "Annotated[str, Field(description='Display name for the helper')]"
        },
        "helper_id": {
          "type": "Annotated[str | None, Field(description=\"Helper ID for updates (e.g., 'my_button' or 'input_button.my_button'). If not provided, creates a new helper.\", default=None)]",
          "default": null
        },
        "icon": {
          "type": "Annotated[str | None, Field(description=\"Material Design Icon (e.g., 'mdi:bell', 'mdi:toggle-switch')\", default=None)]",
          "default": null
        },
        "area_id": {
          "type": "Annotated[str | None, Field(description='Area/room ID to assign the helper to', default=None)]",
          "default": null
        },
        "labels": {
          "type": "Annotated[str | list[str] | None, Field(description='Labels to categorize the helper', default=None)]",
          "default": null
        },
        "min_value": {
          "type": "Annotated[float | None, Field(description='Minimum value (input_number/counter) or minimum length (input_text)', default=None)]",
          "default": null
        },
        "max_value": {
          "type": "Annotated[float | None, Field(description='Maximum value (input_number/counter) or maximum length (input_text)', default=None)]",
          "default": null
        },
        "step": {
          "type": "Annotated[float | None, Field(description='Step/increment value for input_number or counter', default=None)]",
          "default": null
        },
        "unit_of_measurement": {
          "type": "Annotated[str | None, Field(description=\"Unit of measurement for input_number (e.g., '°C', '%', 'W')\", default=None)]",
          "default": null
        },
        "options": {
          "type": "Annotated[str | list[str] | None, Field(description='List of options for input_select (required for input_select)', default=None)]",
          "default": null
        },
        "initial": {
          "type": "Annotated[str | int | None, Field(description='Initial value for the helper (input_select, input_text, input_boolean, input_datetime, counter)', default=None)]",
          "default": null
        },
        "mode": {
          "type": "Annotated[str | None, Field(description=\"Display mode: 'box'/'slider' for input_number, 'text'/'password' for input_text\", default=None)]",
          "default": null
        },
        "has_date": {
          "type": "Annotated[bool | None, Field(description='Include date component for input_datetime', default=None)]",
          "default": null
        },
        "has_time": {
          "type": "Annotated[bool | None, Field(description='Include time component for input_datetime', default=None)]",
          "default": null
        },
        "restore": {
          "type": "Annotated[bool | None, Field(description='Restore state after restart (counter, timer). Defaults to True for counter, False for timer', default=None)]",
          "default": null
        },
        "duration": {
          "type": "Annotated[str | None, Field(description=\"Default duration for timer in format 'HH:MM:SS' or seconds (e.g., '0:05:00' for 5 minutes)\", default=None)]",
          "default": null
        },
        "monday": {
          "type": "Annotated[list[dict[str, Any]] | None, Field(description=\"Schedule time ranges for Monday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes (e.g. {'from': '07:00', 'to': '22:00', 'data': {'mode': 'comfort'}})\", default=None)]",
          "default": null
        },
        "tuesday": {
          "type": "Annotated[list[dict[str, Any]] | None, Field(description=\"Schedule time ranges for Tuesday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes.\", default=None)]",
          "default": null
        },
        "wednesday": {
          "type": "Annotated[list[dict[str, Any]] | None, Field(description=\"Schedule time ranges for Wednesday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes.\", default=None)]",
          "default": null
        },
        "thursday": {
          "type": "Annotated[list[dict[str, Any]] | None, Field(description=\"Schedule time ranges for Thursday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes.\", default=None)]",
          "default": null
        },
        "friday": {
          "type": "Annotated[list[dict[str, Any]] | None, Field(description=\"Schedule time ranges for Friday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes.\", default=None)]",
          "default": null
        },
        "saturday": {
          "type": "Annotated[list[dict[str, Any]] | None, Field(description=\"Schedule time ranges for Saturday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes.\", default=None)]",
          "default": null
        },
        "sunday": {
          "type": "Annotated[list[dict[str, Any]] | None, Field(description=\"Schedule time ranges for Sunday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes.\", default=None)]",
          "default": null
        },
        "latitude": {
          "type": "Annotated[float | None, Field(description='Latitude for zone (required for zone)', default=None)]",
          "default": null
        },
        "longitude": {
          "type": "Annotated[float | None, Field(description='Longitude for zone (required for zone)', default=None)]",
          "default": null
        },
        "radius": {
          "type": "Annotated[float | None, Field(description='Radius in meters for zone (default: 100)', default=None)]",
          "default": null
        },
        "passive": {
          "type": "Annotated[bool | None, Field(description=\"Passive zone (won't trigger state changes for person entities)\", default=None)]",
          "default": null
        },
        "user_id": {
          "type": "Annotated[str | None, Field(description='User ID to link to person entity', default=None)]",
          "default": null
        },
        "device_trackers": {
          "type": "Annotated[list[str] | None, Field(description='List of device_tracker entity IDs for person', default=None)]",
          "default": null
        },
        "picture": {
          "type": "Annotated[str | None, Field(description='Picture URL for person entity', default=None)]",
          "default": null
        },
        "tag_id": {
          "type": "Annotated[str | None, Field(description='Tag ID for tag (auto-generated if not provided)', default=None)]",
          "default": null
        },
        "description": {
          "type": "Annotated[str | None, Field(description='Description for tag', default=None)]",
          "default": null
        },
        "category": {
          "type": "Annotated[str | None, Field(description=\"Category ID to assign to this helper. Use ha_config_get_category(scope='helpers') to list available categories, or ha_config_set_category() to create one.\", default=None)]",
          "default": null
        },
        "wait": {
          "type": "Annotated[bool | str, Field(description='Wait for helper entity to be queryable before returning. Default: True. Set to False for bulk operations.', default=True)]",
          "default": true
        }
      },
      "required": [
        "helper_type",
        "name"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Helper Entities"
    ],
    "source_file": "tools_config_helpers.py"
  },
  {
    "name": "ha_get_helper_schema",
    "title": "Get Helper Schema",
    "description": "Get configuration schema for a helper type.\n\nReturns the form fields and their types needed to create this helper.\nUse before ha_set_config_entry_helper to understand required config.\n\nTwo-call workflow for menu-based helpers (template, group):\n\n  # Step 1 — discover sub-types:\n  ha_get_helper_schema(\"template\")\n  → {flow_type: \"menu\", menu_options: [\"sensor\", \"binary_sensor\", ...]}\n\n  # Step 2 — inspect form fields for a sub-type:\n  ha_get_helper_schema(\"template\", menu_option=\"sensor\")\n  → {flow_type: \"form\", menu_option: \"sensor\", data_schema: [{name: \"state\", ...}, ...]}\n\nFor form-based helpers (min_max, utility_meter, etc.), omit menu_option.",
    "inputSchema": {
      "properties": {
        "helper_type": {
          "type": "Annotated[SUPPORTED_HELPERS, Field(description='Helper type')]"
        },
        "menu_option": {
          "type": "Annotated[str | None, Field(description=\"For menu-based helpers: the sub-type to inspect (e.g. 'sensor' or 'binary_sensor' for template). Omit to see available menu options first.\", default=None)]",
          "default": null
        }
      },
      "required": [
        "helper_type"
      ]
    },
    "annotations": {
      "readOnlyHint": true
    },
    "tags": [
      "Helper Entities"
    ],
    "source_file": "tools_config_entry_flow.py"
  },
  {
    "name": "ha_set_config_entry_helper",
    "title": "Set Config Entry Helper",
    "description": "Create or update a Config Entry Flow helper (template, group, utility_meter, etc.).\n\nWithout entry_id: creates a new helper.\nWith entry_id: reconfigures an existing helper via its options flow.\n\nSupports 15 helper types that use Config Entry Flow API.\nUse ha_get_helper_schema(helper_type) to discover required config fields.\nUse ha_get_integration(entry_id=..., include_schema=True) before updating\nto inspect available fields.\n\nFor menu-based helpers (e.g. group), include the menu selection in config:\n- group: {\"group_type\": \"light\", \"name\": \"My Group\", \"entities\": [...]}\n- template sensor:\n    {\"next_step_id\": \"sensor\", \"name\": \"Vacuum Last Clean\",\n     \"state\": \"{{ states('sensor.vacuum_last_clean') }}\",\n     \"unit_of_measurement\": \"h\", \"device_class\": \"duration\"}\n- template binary sensor:\n    {\"next_step_id\": \"binary_sensor\", \"name\": \"Window Open\",\n     \"state\": \"{{ is_state('binary_sensor.window', 'on') }}\",\n     \"device_class\": \"window\"}",
    "inputSchema": {
      "properties": {
        "helper_type": {
          "type": "Annotated[SUPPORTED_HELPERS, Field(description='Helper type')]"
        },
        "config": {
          "type": "Annotated[str | dict, Field(description='Helper config (JSON or dict)')]"
        },
        "entry_id": {
          "type": "Annotated[str | None, Field(description='Config entry ID to update. If omitted, creates a new helper. Use ha_get_integration(domain=helper_type) to find entry IDs.', default=None)]",
          "default": null
        }
      },
      "required": [
        "helper_type",
        "config"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Helper Entities"
    ],
    "source_file": "tools_config_entry_flow.py"
  },
  {
    "name": "ha_get_automation_traces",
    "title": "Get Automation Traces",
    "description": "Retrieve execution traces for automations and scripts to debug issues.\n\nTraces show what happened during automation/script runs:\n- What triggered the automation\n- Which conditions passed or failed\n- What actions were executed\n- Any errors that occurred\n- Variable values during execution\n\nUSAGE MODES:\n\n1. List recent traces (omit run_id):\n   ha_get_automation_traces(\"automation.motion_light\")\n   Returns a summary of recent execution runs with timestamps, triggers, and status.\n\n2. Get detailed trace (provide run_id):\n   ha_get_automation_traces(\"automation.motion_light\", run_id=\"1705312800.123456\")\n   Returns full execution details including trigger info, condition results,\n   action trace with timing, and context variables.\n\n3. Get detailed trace with logbook (provide run_id and detailed=True):\n   ha_get_automation_traces(\"automation.motion_light\", run_id=\"1705312800.123456\", detailed=True)\n   Returns the formatted trace plus logbook entries and context metadata.\n   Useful when the standard trace summary doesn't reveal enough for debugging.\n   Note: script-style action paths (sequence/, numeric) are always matched\n   regardless of this flag.\n\n4. Get full variables without deduplication (provide run_id and deduplicate=False):\n   ha_get_automation_traces(\"automation.motion_light\", run_id=\"1705312800.123456\", deduplicate=False)\n   Returns the formatted trace with full variables at every action step.\n\nDEBUGGING EXAMPLES:\n\nAutomation not triggering:\n- Check if traces exist (automation may not be triggered)\n- Look at trigger info to see what event was received\n\nAutomation runs but conditions fail:\n- Get detailed trace to see condition_results\n- Each condition shows whether it passed (true) or failed (false)\n\nUnexpected behavior in actions:\n- Get detailed trace to see action_trace\n- Shows each action step with result and any errors\n- For 'choose' actions, shows which branch was taken\n\nTemplate debugging:\n- Detailed trace shows evaluated template values in context\n- Trigger variables available under trigger_variables\n\nNOTES:\n- Traces are stored for a limited time by Home Assistant\n- Works for both automations and scripts (use full entity_id)\n- The 'state' field shows: 'stopped' (completed), 'running', or error state",
    "inputSchema": {
      "properties": {
        "automation_id": {
          "type": "Annotated[str, Field(description=\"Automation or script entity_id (e.g., 'automation.motion_light' or 'script.morning_routine')\")]"
        },
        "run_id": {
          "type": "Annotated[str | None, Field(description='Specific trace run_id to retrieve detailed trace. Omit to list recent traces.', default=None)]",
          "default": null
        },
        "limit": {
          "type": "Annotated[int, Field(description='Maximum number of traces to return when listing (default: 10, max: 50)', default=10, ge=1, le=50)]",
          "default": 10
        },
        "deduplicate": {
          "type": "Annotated[bool, Field(description='Deduplicate variables across action steps (default: True). Set to False to include full variables at every step.', default=True)]",
          "default": true
        },
        "detailed": {
          "type": "Annotated[bool, Field(description='Include extra diagnostic data: logbook entries and context metadata (default: False). Use when standard trace lacks detail for debugging.', default=False)]",
          "default": false
        },
        "sections": {
          "type": "Annotated[str | None, Field(description=\"Comma-separated list of trace sections to return. Valid values: trigger, conditions, actions, config, error, logbook, context. Omit to return all sections. Example: 'actions' or 'trigger,conditions'.\", default=None)]",
          "default": null
        }
      },
      "required": [
        "automation_id"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "History & Statistics"
    ],
    "source_file": "tools_traces.py"
  },
  {
    "name": "ha_get_history",
    "title": "Get Entity History",
    "description": "Retrieve raw state change history for entities (last ~10 days).\n\nReturns the full-resolution state history from Home Assistant's recorder.\nThis data shows every individual state change for the specified entities.\n\n**Data Characteristics:**\n- Full resolution: Every state transition captured\n- Retention: ~10 days (configurable via recorder.purge_keep_days)\n- Best for: Troubleshooting, pattern analysis, specific event queries\n\n**Parameters:**\n- entity_ids: Entity ID(s) to query (required)\n- start_time: Start of period - ISO datetime or relative ('24h', '7d', '2w'). Default: 24h ago\n- end_time: End of period - ISO datetime. Default: now\n- minimal_response: Omit attributes for smaller response. Default: true\n- significant_changes_only: Filter to actual state changes. Default: true\n- limit: Max entries per entity. Default: 100, Max: 1000\n\n**Use Cases:**\n- \"Why was my bedroom cold last night?\" - Query temperature sensor history\n- \"Did my garage door open while I was away?\" - Check cover state changes\n- \"What time does motion usually trigger?\" - Analyze binary sensor patterns\n- \"Debug automation triggers\" - See exact state change sequence\n\n**Example:**\n```python\n# Get temperature history for the last 24 hours\nha_get_history(entity_ids=\"sensor.bedroom_temperature\")\n\n# Get multiple entity history for last 7 days\nha_get_history(\n    entity_ids=[\"sensor.temperature\", \"sensor.humidity\"],\n    start_time=\"7d\",\n    limit=500\n)\n\n# Get full attributes for debugging\nha_get_history(\n    entity_ids=\"light.living_room\",\n    start_time=\"2025-01-25T00:00:00Z\",\n    end_time=\"2025-01-26T00:00:00Z\",\n    minimal_response=False\n)\n```\n\n**Note:** For long-term trends (>10 days), use ha_get_statistics() instead.\n\n**Returns:**\n- List of entities with their state history\n- Each entity includes: entity_id, period, states array, count",
    "inputSchema": {
      "properties": {
        "entity_ids": {
          "type": "Annotated[str | list[str], Field(description='Entity ID(s) to query. Can be a single ID, comma-separated string, or JSON array.')]"
        },
        "start_time": {
          "type": "Annotated[str | None, Field(description=\"Start time: ISO datetime or relative (e.g., '24h', '7d', '2w'). Default: 24h ago\", default=None)]",
          "default": null
        },
        "end_time": {
          "type": "Annotated[str | None, Field(description='End time: ISO datetime. Default: now', default=None)]",
          "default": null
        },
        "minimal_response": {
          "type": "Annotated[bool, Field(description='Return only states/timestamps without attributes. Default: true', default=True)]",
          "default": true
        },
        "significant_changes_only": {
          "type": "Annotated[bool, Field(description='Filter to significant state changes only. Default: true', default=True)]",
          "default": true
        },
        "limit": {
          "type": "Annotated[int | str | None, Field(description='Max state changes per entity. Default: 100, Max: 1000', default=None)]",
          "default": null
        }
      },
      "required": [
        "entity_ids"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "History & Statistics"
    ],
    "source_file": "tools_history.py"
  },
  {
    "name": "ha_get_logbook",
    "title": "Get Logbook Entries",
    "description": "Get Home Assistant logbook entries for the specified time period.\n\nReturns paginated logbook entries to prevent excessively large responses.\n\n**Parameters:**\n- hours_back: Number of hours to look back (default: 1)\n- entity_id: Optional entity ID to filter entries\n- end_time: Optional end time in ISO format (defaults to now)\n- limit: Maximum number of entries to return (default: 50, max: 500)\n- offset: Number of entries to skip for pagination (default: 0)\n- compact: Return only essential fields per entry (default: True).\n  When True, each entry contains only: when, entity_id, state, name, message, domain, context_id.\n  Set to False to include full attribute dictionaries and all fields.\n\n**Pagination:**\nWhen the logbook has more entries than the limit, use offset to get\nadditional pages. The response includes `has_more` to indicate if\nmore entries are available.\n\n**IMPORTANT - Pagination Stability:**\nPagination is performed client-side on the full result set returned\nby Home Assistant. If new logbook entries are created between page\nrequests, results may shift and items could be missed or duplicated\nacross pages. For best results, use consistent time ranges (start/end)\nand retrieve pages in quick succession.\n\n**Example:**\n- First page: ha_get_logbook(hours_back=24, limit=50, offset=0)\n- Second page: ha_get_logbook(hours_back=24, limit=50, offset=50)\n- Full details: ha_get_logbook(hours_back=1, compact=False)",
    "inputSchema": {
      "properties": {
        "hours_back": {
          "type": "int | str",
          "default": 1
        },
        "entity_id": {
          "type": "str | None",
          "default": null
        },
        "end_time": {
          "type": "str | None",
          "default": null
        },
        "limit": {
          "type": "int | str | None",
          "default": null
        },
        "offset": {
          "type": "int | str",
          "default": 0
        },
        "compact": {
          "type": "bool | str",
          "default": true
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "History & Statistics"
    ],
    "source_file": "tools_utility.py"
  },
  {
    "name": "ha_get_statistics",
    "title": "Get Statistics",
    "description": "Retrieve pre-aggregated long-term statistics for trend analysis.\n\nReturns aggregated statistical data from Home Assistant's long-term statistics\ntable. This data is pre-computed and stored permanently, allowing analysis\nof historical trends beyond the standard ~10 day recorder retention.\n\n**Data Characteristics:**\n- Pre-aggregated: Hourly/daily/monthly statistics\n- Retention: Permanent - never purged\n- Entities: Only those with state_class (measurement, total, total_increasing)\n- Best for: Long-term trends, energy consumption, period comparisons\n\n**Parameters:**\n- entity_ids: Entity ID(s) with state_class attribute (required)\n- start_time: Start of period - ISO datetime or relative ('30d', '6m', '12m'). Default: 30d ago\n- end_time: End of period - ISO datetime. Default: now\n- period: Aggregation: '5minute', 'hour', 'day', 'week', 'month'. Default: 'day'\n- statistic_types: Types to include: 'mean', 'min', 'max', 'sum', 'state', 'change'. Default: all\n\n**Statistic Types Explained:**\n- mean: Average value over the period\n- min: Minimum value during the period\n- max: Maximum value during the period\n- sum: Running total (for total_increasing entities like energy)\n- state: Last known state value\n- change: Change from previous period\n\n**Use Cases:**\n- \"How much electricity did I use this month vs last month?\" - Monthly sum\n- \"What's my average living room temperature?\" - Daily/monthly mean\n- \"Show daily energy consumption for the past 2 weeks\" - Daily sum\n- \"Has my solar production declined year over year?\" - Monthly comparison\n\n**Example:**\n```python\n# Get daily energy statistics for last 30 days\nha_get_statistics(entity_ids=\"sensor.total_energy_kwh\")\n\n# Get monthly temperature averages for 6 months\nha_get_statistics(\n    entity_ids=\"sensor.living_room_temperature\",\n    start_time=\"6m\",\n    period=\"month\",\n    statistic_types=[\"mean\", \"min\", \"max\"]\n)\n\n# Compare multiple sensors\nha_get_statistics(\n    entity_ids=[\"sensor.solar_production\", \"sensor.grid_consumption\"],\n    start_time=\"12m\",\n    period=\"month\",\n    statistic_types=[\"sum\"]\n)\n```\n\n**Note:** Only entities with state_class attribute support statistics.\nUse ha_search_entities() to find entities and check their state_class.\n\n**Returns:**\n- List of entities with their statistics\n- Each includes: entity_id, period type, statistics array, unit_of_measurement",
    "inputSchema": {
      "properties": {
        "entity_ids": {
          "type": "Annotated[str | list[str], Field(description='Entity ID(s) to query. Must have state_class attribute. Can be single ID, comma-separated, or JSON array.')]"
        },
        "start_time": {
          "type": "Annotated[str | None, Field(description=\"Start time: ISO datetime or relative (e.g., '30d', '6m', '12m'). Default: 30d ago\", default=None)]",
          "default": null
        },
        "end_time": {
          "type": "Annotated[str | None, Field(description='End time: ISO datetime. Default: now', default=None)]",
          "default": null
        },
        "period": {
          "type": "Annotated[str, Field(description=\"Aggregation period: '5minute', 'hour', 'day', 'week', 'month'. Default: 'day'\", default='day')]",
          "default": "day"
        },
        "statistic_types": {
          "type": "Annotated[str | list[str] | None, Field(description=\"Statistics types: 'mean', 'min', 'max', 'sum', 'state', 'change'. Default: all\", default=None)]",
          "default": null
        }
      },
      "required": [
        "entity_ids"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "History & Statistics"
    ],
    "source_file": "tools_history.py"
  },
  {
    "name": "ha_delete_config_entry",
    "title": "Delete Config Entry",
    "description": "Delete config entry permanently. Requires confirm=True.\n\nUse ha_get_integration() to find entry IDs.",
    "inputSchema": {
      "properties": {
        "entry_id": {
          "type": "Annotated[str, Field(description='Config entry ID')]"
        },
        "confirm": {
          "type": "Annotated[bool | str, Field(description='Must be True to confirm deletion')]",
          "default": false
        }
      },
      "required": [
        "entry_id"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Integrations"
    ],
    "source_file": "tools_integrations.py"
  },
  {
    "name": "ha_get_integration",
    "title": "Get Integration",
    "description": "Get integration (config entry) information - list all or get a specific one.\n\nWithout an entry_id: Lists all configured integrations with optional filters.\nWith an entry_id: Returns detailed information including full options/configuration.\n\nUse this to audit existing configurations (e.g. template sensor Jinja code).\nWhen creating new functionality, prefer UI-based helpers over templates when possible.\n\nEXAMPLES:\n- List all integrations: ha_get_integration()\n- Search integrations: ha_get_integration(query=\"zigbee\")\n- Get specific entry: ha_get_integration(entry_id=\"abc123\")\n- Get entry with editable fields: ha_get_integration(entry_id=\"abc123\", include_schema=True)\n- List template entries with definitions: ha_get_integration(domain=\"template\")\n- List all with options: ha_get_integration(include_options=True)\n\nSTATES: 'loaded' (running), 'setup_error', 'setup_retry', 'not_loaded',\n'failed_unload', 'migration_error'.\n\nRETURNS (when listing):\n- entries: List of integrations with domain, title, state, capabilities\n- state_summary: Count of entries in each state\n- When domain filter or include_options is set, each entry includes the 'options' object\n\nRETURNS (when getting specific entry):\n- entry: Full config entry details including options/configuration\n- options_schema: Options flow schema when include_schema=True and supports_options=true",
    "inputSchema": {
      "properties": {
        "entry_id": {
          "type": "Annotated[str | None, Field(description='Config entry ID to get details for. If omitted, lists all integrations.', default=None)]",
          "default": null
        },
        "query": {
          "type": "Annotated[str | None, Field(description='When listing, search by domain or title. Uses exact substring matching by default; set exact_match=False for fuzzy.', default=None)]",
          "default": null
        },
        "domain": {
          "type": "Annotated[str | None, Field(description=\"Filter by integration domain (e.g. 'template', 'group'). When set, includes the full options/configuration for each entry.\", default=None)]",
          "default": null
        },
        "include_options": {
          "type": "Annotated[bool | str, Field(description='Include the options object for each entry. Automatically enabled when domain filter is set. Useful for auditing template definitions and helper configurations.', default=False)]",
          "default": false
        },
        "include_schema": {
          "type": "Annotated[bool | str, Field(description='When entry_id is set, also return the options flow schema (available fields and their types). Use before ha_set_config_entry_helper to understand what can be updated. Only applies when supports_options=true.', default=False)]",
          "default": false
        },
        "exact_match": {
          "type": "Annotated[bool | str, Field(description='Use exact substring matching for query filter (default: True). Set to False for fuzzy matching when the query may contain typos.', default=True)]",
          "default": true
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Integrations"
    ],
    "source_file": "tools_integrations.py"
  },
  {
    "name": "ha_set_integration_enabled",
    "title": "Set Integration Enabled",
    "description": "Enable/disable integration (config entry).\n\nUse ha_get_integration() to find entry IDs.",
    "inputSchema": {
      "properties": {
        "entry_id": {
          "type": "Annotated[str, Field(description='Config entry ID')]"
        },
        "enabled": {
          "type": "Annotated[bool | str, Field(description='True to enable, False to disable')]"
        }
      },
      "required": [
        "entry_id",
        "enabled"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Integrations"
    ],
    "source_file": "tools_integrations.py"
  },
  {
    "name": "ha_config_get_category",
    "title": "Get Category",
    "description": "Get category info - list all categories for a scope or get a specific one by ID.\n\nWithout a category_id: Lists all Home Assistant categories for the given scope.\nWith a category_id: Returns configuration for that specific category.\n\nCategories are domain-scoped organizational groups for automations, scripts, scenes, and helpers.\n\nCATEGORY PROPERTIES:\n- ID (category_id), Name\n- Icon (optional)\n\nEXAMPLES:\n- List automation categories: ha_config_get_category(\"automation\")\n- List script categories: ha_config_get_category(\"script\")\n- List helper categories: ha_config_get_category(\"helpers\")\n- Get specific category: ha_config_get_category(\"automation\", category_id=\"my_category_id\")\n\nUse ha_config_set_category() to create or update categories.\nUse ha_set_entity(categories={\"automation\": \"category_id\"}) to assign categories to entities.",
    "inputSchema": {
      "properties": {
        "scope": {
          "type": "Annotated[str, Field(description=\"Domain scope for categories (e.g., 'automation', 'script', 'scene', 'helpers').\")]"
        },
        "category_id": {
          "type": "Annotated[str | None, Field(description='ID of the category to retrieve. If omitted, lists all categories for the scope.', default=None)]",
          "default": null
        }
      },
      "required": [
        "scope"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Labels & Categories"
    ],
    "source_file": "tools_categories.py"
  },
  {
    "name": "ha_config_get_label",
    "title": "Get Label",
    "description": "Get label info - list all labels or get a specific one by ID.\n\nWithout a label_id: Lists all Home Assistant labels with their configurations.\nWith a label_id: Returns configuration for that specific label.\n\nLABEL PROPERTIES:\n- ID (label_id), Name\n- Color (optional), Icon (optional), Description (optional)\n\nEXAMPLES:\n- List all labels: ha_config_get_label()\n- Get specific label: ha_config_get_label(\"my_label_id\")\n\nUse ha_config_set_label() to create or update labels.\nUse ha_set_entity(labels=[\"label1\", \"label2\"]) to assign labels to entities.",
    "inputSchema": {
      "properties": {
        "label_id": {
          "type": "Annotated[str | None, Field(description='ID of the label to retrieve. If omitted, lists all labels.', default=None)]",
          "default": null
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Labels & Categories"
    ],
    "source_file": "tools_labels.py"
  },
  {
    "name": "ha_config_remove_category",
    "title": "Remove Category",
    "description": "Delete a Home Assistant category.\n\nRemoves the category from the category registry for the given scope\n(e.g., 'automation', 'script', 'scene', 'helpers').\nThis will also remove the category assignment from all entities in that scope.\n\nEXAMPLES:\n- Delete category: ha_config_remove_category(\"automation\", \"my_category_id\")\n\nUse ha_config_get_category() to find category IDs.\n\n**WARNING:** Deleting a category will remove it from all assigned entities.\nThis action cannot be undone.",
    "inputSchema": {
      "properties": {
        "scope": {
          "type": "Annotated[str, Field(description=\"Domain scope for the category (e.g., 'automation', 'script', 'scene', 'helpers').\")]"
        },
        "category_id": {
          "type": "Annotated[str, Field(description='ID of the category to delete')]"
        }
      },
      "required": [
        "scope",
        "category_id"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": true
    },
    "tags": [
      "Labels & Categories"
    ],
    "source_file": "tools_categories.py"
  },
  {
    "name": "ha_config_remove_label",
    "title": "Remove Label",
    "description": "Delete a Home Assistant label.\n\nRemoves the label from the label registry. This will also remove the label\nfrom all entities, devices, and areas that have it assigned.\n\nEXAMPLES:\n- Delete label: ha_config_remove_label(\"my_label_id\")\n\nUse ha_config_get_label() to find label IDs.\n\n**WARNING:** Deleting a label will remove it from all assigned entities.\nThis action cannot be undone.",
    "inputSchema": {
      "properties": {
        "label_id": {
          "type": "Annotated[str, Field(description='ID of the label to delete')]"
        }
      },
      "required": [
        "label_id"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": true
    },
    "tags": [
      "Labels & Categories"
    ],
    "source_file": "tools_labels.py"
  },
  {
    "name": "ha_config_set_category",
    "title": "Create or Update Category",
    "description": "Create or update a Home Assistant category.\n\nCreates a new category if category_id is not provided, or updates an existing category if category_id is provided.\n\nCategories are domain-scoped organizational groups for automations, scripts,\nscenes, and helpers. Unlike labels (which are cross-domain), categories are\nspecific to a single domain scope.\n\nEXAMPLES:\n- Create automation category: ha_config_set_category(\"Lighting\", scope=\"automation\")\n- Create with icon: ha_config_set_category(\"Security\", scope=\"automation\", icon=\"mdi:shield\")\n- Update category: ha_config_set_category(\"Updated Name\", scope=\"automation\", category_id=\"my_category_id\")\n\nAfter creating a category, use ha_set_entity(categories={\"automation\": \"category_id\"}) to assign it.",
    "inputSchema": {
      "properties": {
        "name": {
          "type": "Annotated[str, Field(description='Display name for the category')]"
        },
        "scope": {
          "type": "Annotated[str, Field(description=\"Domain scope for the category (e.g., 'automation', 'script', 'scene', 'helpers').\")]"
        },
        "category_id": {
          "type": "Annotated[str | None, Field(description='Category ID for updates. If not provided, creates a new category.', default=None)]",
          "default": null
        },
        "icon": {
          "type": "Annotated[str | None, Field(description=\"Material Design Icon (e.g., 'mdi:tag', 'mdi:label')\", default=None)]",
          "default": null
        }
      },
      "required": [
        "name",
        "scope"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Labels & Categories"
    ],
    "source_file": "tools_categories.py"
  },
  {
    "name": "ha_config_set_label",
    "title": "Create or Update Label",
    "description": "Create or update a Home Assistant label.\n\nCreates a new label if label_id is not provided, or updates an existing label if label_id is provided.\n\nLabels are a flexible tagging system that can be applied to entities,\ndevices, and areas for organization and automation purposes.\n\nEXAMPLES:\n- Create simple label: ha_config_set_label(\"Critical\")\n- Create colored label: ha_config_set_label(\"Outdoor\", color=\"green\")\n- Create label with icon: ha_config_set_label(\"Battery Powered\", icon=\"mdi:battery\")\n- Create full label: ha_config_set_label(\"Security\", color=\"red\", icon=\"mdi:shield\", description=\"Security-related devices\")\n- Update label: ha_config_set_label(\"Updated Name\", label_id=\"my_label_id\", color=\"blue\")\n\nAfter creating a label, use ha_set_entity(labels=[\"label_id\"]) to assign it to entities.",
    "inputSchema": {
      "properties": {
        "name": {
          "type": "Annotated[str, Field(description='Display name for the label')]"
        },
        "label_id": {
          "type": "Annotated[str | None, Field(description='Label ID for updates. If not provided, creates a new label.', default=None)]",
          "default": null
        },
        "color": {
          "type": "Annotated[str | None, Field(description=\"Color for the label (e.g., 'red', 'blue', 'green', or hex like '#FF5733')\", default=None)]",
          "default": null
        },
        "icon": {
          "type": "Annotated[str | None, Field(description=\"Material Design Icon (e.g., 'mdi:tag', 'mdi:label')\", default=None)]",
          "default": null
        },
        "description": {
          "type": "Annotated[str | None, Field(description=\"Description of the label's purpose\", default=None)]",
          "default": null
        }
      },
      "required": [
        "name"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Labels & Categories"
    ],
    "source_file": "tools_labels.py"
  },
  {
    "name": "ha_config_get_script",
    "title": "Get Script Config",
    "description": "Retrieve Home Assistant script configuration.\n\nReturns the complete configuration for a script, including sequence, mode, fields, and other settings.\n\nEXAMPLES:\n- Get script: ha_config_get_script(\"morning_routine\")\n- Get script: ha_config_get_script(\"backup_script\")\n\nFor detailed script configuration help, use ha_get_skill_home_assistant_best_practices.",
    "inputSchema": {
      "properties": {
        "script_id": {
          "type": "Annotated[str, Field(description=\"Script identifier (e.g., 'morning_routine')\")]"
        }
      },
      "required": [
        "script_id"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Scripts"
    ],
    "source_file": "tools_config_scripts.py"
  },
  {
    "name": "ha_config_remove_script",
    "title": "Remove Script",
    "description": "Delete a Home Assistant script.\n\nEXAMPLES:\n- Delete script: ha_config_remove_script(\"old_script\")\n- Delete script: ha_config_remove_script(\"temporary_script\")\n\n**IMPORTANT LIMITATION:**\nThis tool can only delete scripts created via the Home Assistant UI.\nScripts defined in YAML configuration files (scripts.yaml or configuration.yaml)\ncannot be deleted through the API and will return a 405 Method Not Allowed error.\n\nTo remove YAML-defined scripts, you must edit the configuration file directly.\n\n**WARNING:** Deleting a script that is used by automations may cause those automations to fail.",
    "inputSchema": {
      "properties": {
        "script_id": {
          "type": "Annotated[str, Field(description=\"Script identifier to delete (e.g., 'old_script')\")]"
        },
        "wait": {
          "type": "Annotated[bool | str, Field(description='Wait for script to be fully removed before returning. Default: True.', default=True)]",
          "default": true
        }
      },
      "required": [
        "script_id"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": true
    },
    "tags": [
      "Scripts"
    ],
    "source_file": "tools_config_scripts.py"
  },
  {
    "name": "ha_config_set_script",
    "title": "Create or Update Script",
    "description": "Create or update a Home Assistant script.\n\nCreates a new script or updates an existing one with the provided configuration.\nSupports both regular scripts (with sequence) and blueprint-based scripts.\n\nRequired config fields (choose one):\n    - sequence: List of actions to execute (for regular scripts)\n    - use_blueprint: Blueprint configuration (for blueprint-based scripts)\n\nOptional config fields:\n    - alias: Display name (defaults to script_id)\n    - description: Script description\n    - icon: Icon to display\n    - mode: Execution mode ('single', 'restart', 'queued', 'parallel')\n    - max: Maximum concurrent executions (for queued/parallel modes)\n    - fields: Input parameters for the script\n\nIMPORTANT: The 'config' parameter must be passed as a proper dictionary/object.\n\nEXAMPLES:\n\nCreate basic delay script:\nha_config_set_script(\"wait_script\", {\n    \"sequence\": [{\"delay\": {\"seconds\": 5}}],\n    \"alias\": \"Wait 5 Seconds\",\n    \"description\": \"Simple delay script\"\n})\n\nCreate service call script:\nha_config_set_script(\"blink_light\", {\n    \"sequence\": [\n        {\"service\": \"light.turn_on\", \"target\": {\"entity_id\": \"light.living_room\"}},\n        {\"delay\": {\"seconds\": 2}},\n        {\"service\": \"light.turn_off\", \"target\": {\"entity_id\": \"light.living_room\"}}\n    ],\n    \"alias\": \"Light Blink\",\n    \"mode\": \"single\"\n})\n\nCreate script with parameters:\nha_config_set_script(\"backup_script\", {\n    \"alias\": \"Backup with Reference\",\n    \"description\": \"Create backup with optional reference parameter\",\n    \"fields\": {\n        \"reference\": {\n            \"name\": \"Reference\",\n            \"description\": \"Optional reference for backup identification\",\n            \"selector\": {\"text\": None}\n        }\n    },\n    \"sequence\": [\n        {\n            \"action\": \"hassio.backup_partial\",\n            \"data\": {\n                \"compressed\": False,\n                \"homeassistant\": True,\n                \"homeassistant_exclude_database\": True,\n                \"name\": \"Backup_{{ reference | default('auto') }}_{{ now().strftime('%Y%m%d_%H%M%S') }}\"\n            }\n        }\n    ]\n})\n\nUpdate script:\nha_config_set_script(\"morning_routine\", {\n    \"sequence\": [\n        {\"service\": \"light.turn_on\", \"target\": {\"area_id\": \"bedroom\"}},\n        {\"service\": \"climate.set_temperature\", \"target\": {\"entity_id\": \"climate.bedroom\"}, \"data\": {\"temperature\": 22}}\n    ],\n    \"alias\": \"Updated Morning Routine\"\n})\n\nCreate blueprint-based script:\nha_config_set_script(\"notification_script\", {\n    \"alias\": \"My Notification Script\",\n    \"use_blueprint\": {\n        \"path\": \"notification_script.yaml\",\n        \"input\": {\n            \"message\": \"Hello World\",\n            \"title\": \"Test Notification\"\n        }\n    }\n})\n\nUpdate blueprint script inputs:\nha_config_set_script(\"notification_script\", {\n    \"alias\": \"My Notification Script\",\n    \"use_blueprint\": {\n        \"path\": \"notification_script.yaml\",\n        \"input\": {\n            \"message\": \"Updated message\",\n            \"title\": \"Updated Title\"\n        }\n    }\n})\n\nPREFER NATIVE ACTIONS OVER TEMPLATES:\nBefore using template-based logic in scripts, check if native actions exist:\n- Use `choose` action instead of template-based service names\n- Use `if/then/else` action instead of template conditions\n- Use `repeat` action with `for_each` instead of template loops\n- Use `wait_for_trigger` instead of `wait_template` when waiting for state changes\n- Use native action variables instead of complex template calculations\n\nFor detailed script configuration help, use ha_get_skill_home_assistant_best_practices.\n\nNote: Scripts use Home Assistant's action syntax. Check the documentation for advanced\nfeatures like conditions, variables, parallel execution, and service call options.",
    "inputSchema": {
      "properties": {
        "script_id": {
          "type": "Annotated[str, Field(description=\"Script identifier (e.g., 'morning_routine')\")]"
        },
        "config": {
          "type": "Annotated[str | dict[str, Any], Field(description=\"Script configuration dictionary. Must include EITHER 'sequence' (for regular scripts) OR 'use_blueprint' (for blueprint-based scripts). Optional fields: 'alias', 'description', 'icon', 'mode', 'max', 'fields'\")]"
        },
        "category": {
          "type": "Annotated[str | None, Field(description=\"Category ID to assign to this script. Use ha_config_get_category(scope='script') to list available categories, or ha_config_set_category() to create one.\", default=None)]",
          "default": null
        },
        "wait": {
          "type": "Annotated[bool | str, Field(description='Wait for script to be queryable before returning. Default: True. Set to False for bulk operations.', default=True)]",
          "default": true
        }
      },
      "required": [
        "script_id",
        "config"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Scripts"
    ],
    "source_file": "tools_config_scripts.py"
  },
  {
    "name": "ha_deep_search",
    "title": "Deep Search",
    "description": "Search inside automation, script, helper, and dashboard *configurations* — not for finding entity IDs.\n\nUse this when you need to find automations/scripts by what they *do* (e.g., which automations\ncall a specific service, reference a particular entity, or contain a certain action).\nFor finding entity IDs by name, use ha_search_entities instead.\n\nSearches within configuration definitions including triggers, actions, sequences, and other\nconfig fields. Also searches dashboard configurations (cards, badges, views) when\nsearch_types includes 'dashboard'.\n\n**NOTE:** Dashboards and badges are NOT searched by default. Add 'dashboard' to\nsearch_types to include them.\n\nArgs:\n    query: Search query (exact substring by default, or fuzzy with exact_match=False)\n    search_types: Types to search (default: [\"automation\", \"script\", \"helper\"])\n    limit: Maximum total results to return (default: 5)\n    exact_match: Use exact substring matching (default: True)\n\nExamples:\n    - Find automations referencing an entity: ha_deep_search(\"sensor.temperature\")\n    - Find with fuzzy matching: ha_deep_search(\"motion\", exact_match=False)\n    - Search dashboards for entity refs: ha_deep_search(\"sensor.temperature\", search_types=[\"dashboard\"])\n    - Search everything: ha_deep_search(\"light.bedroom\", search_types=[\"automation\",\"script\",\"helper\",\"dashboard\"])",
    "inputSchema": {
      "properties": {
        "query": {
          "type": "str"
        },
        "search_types": {
          "type": "Annotated[str | list[str] | None, Field(default=None, description=\"Types to search: 'automation', 'script', 'helper', 'dashboard'. Pass as list or JSON array string. Default: automation, script, helper.\")]",
          "default": null
        },
        "limit": {
          "type": "int",
          "default": 5
        },
        "offset": {
          "type": "int",
          "default": 0
        },
        "include_config": {
          "type": "Annotated[bool | str, Field(default=False, description='Include full config in results. Default: False (returns summary only). Use ha_config_get_automation/ha_config_get_script for individual configs.')]",
          "default": false
        },
        "exact_match": {
          "type": "Annotated[bool | str, Field(default=True, description='Use exact substring matching (default: True). Set to False for fuzzy matching when the query may contain typos or when searching with approximate terms.')]",
          "default": true
        }
      },
      "required": [
        "query"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Search & Discovery"
    ],
    "source_file": "tools_search.py"
  },
  {
    "name": "ha_get_overview",
    "title": "Get System Overview",
    "description": "Get AI-friendly system overview with intelligent categorization.\n\nReturns comprehensive system information at the requested detail level,\nincluding Home Assistant base_url, version, location, timezone, entity overview,\nand active persistent notifications (if any).\nDefault is 'minimal' — use this unless you specifically need all entities.",
    "inputSchema": {
      "properties": {
        "detail_level": {
          "type": "Annotated[Literal['minimal', 'standard', 'full'], Field(default='minimal', description=\"'minimal': 10 entities per domain sample (default); 'standard': ALL entities per domain (friendly_name only); 'full': ALL entities with entity_id + friendly_name + state + system_info\")]",
          "default": "minimal"
        },
        "max_entities_per_domain": {
          "type": "Annotated[int | None, Field(default=None, description='Override max entities per domain (None = all). Minimal defaults to 10.')]",
          "default": null
        },
        "include_state": {
          "type": "Annotated[bool | str | None, Field(default=None, description='Include state field for entities (None = auto based on level). Full defaults to True.')]",
          "default": null
        },
        "include_entity_id": {
          "type": "Annotated[bool | str | None, Field(default=None, description='Include entity_id field for entities (None = auto based on level). Full defaults to True.')]",
          "default": null
        },
        "include_notifications": {
          "type": "Annotated[bool | str | None, Field(default=True, description='Include active persistent notifications (default: True). Set False to skip.')]",
          "default": true
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Search & Discovery"
    ],
    "source_file": "tools_search.py"
  },
  {
    "name": "ha_get_state",
    "title": "Get Entity State",
    "description": "Get current status, state, and attributes of any entity (lights, switches, sensors, climate, covers, locks, fans, etc.).",
    "inputSchema": {
      "properties": {
        "entity_id": {
          "type": "str"
        }
      },
      "required": [
        "entity_id"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Search & Discovery"
    ],
    "source_file": "tools_search.py"
  },
  {
    "name": "ha_get_states",
    "title": "Get Multiple Entity States",
    "description": "Get state information for multiple Home Assistant entities in a single call.\n\nEfficiently retrieves states for multiple entities using parallel requests\ninstead of calling ha_get_state repeatedly. Maximum 100 entities per call.\nDuplicate entity IDs are automatically deduplicated.\n\nReturns success=True if at least one entity state was retrieved.\nCheck 'error_count' for any failed lookups in partial-success scenarios.\n\nWHEN TO USE:\n- Checking states of multiple entities at once (e.g., verifying automation results)\n- Comparing states across related entities\n- Any scenario requiring 2+ entity state lookups\n\nEXAMPLES:\n- ha_get_states([\"light.kitchen\", \"light.living_room\", \"sensor.temperature\"])\n- ha_get_states([\"automation.morning_routine\", \"binary_sensor.motion\"])\n\nNOTE: For a single entity, use ha_get_state() instead.",
    "inputSchema": {
      "properties": {
        "entity_ids": {
          "type": "Annotated[list[str], Field(description=\"List of entity IDs to retrieve states for (e.g., ['light.kitchen', 'sensor.temperature'])\")]"
        }
      },
      "required": [
        "entity_ids"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Search & Discovery"
    ],
    "source_file": "tools_search.py"
  },
  {
    "name": "ha_search_entities",
    "title": "Search Entities",
    "description": "PRIMARY tool for finding entities (lights, sensors, switches, etc.) by name, area, or domain. Use this first when looking up any entity ID.\n\nFor searching *inside* automation/script/helper configurations, use ha_deep_search instead.\n\n**Listing Entities by Domain:**\nUse domain_filter with an empty query to list all entities of a specific type:\n- ha_search_entities(query=\"\", domain_filter=\"calendar\") - List all calendars\n- ha_search_entities(query=\"\", domain_filter=\"todo\") - List all todo lists\n- ha_search_entities(query=\"\", domain_filter=\"scene\") - List all scenes\n- ha_search_entities(query=\"\", domain_filter=\"zone\") - List all zones (as entities)\n\n**BEST PRACTICE:** Before performing searches, call ha_get_overview() first to understand:\n- Smart home size and scale (total entities, domains, areas)\n- Language used in entity naming (French/English/mixed)\n- Available areas/rooms and their entity distribution\n\nChoose overview detail level based on task:\n- 'minimal': Quick orientation (10 entities per domain sample) - RECOMMENDED for searches\n- 'standard': Complete picture (all entities, friendly names only) - for comprehensive tasks\n- 'full': Maximum detail (includes states, device types, services) - for deep analysis",
    "inputSchema": {
      "properties": {
        "query": {
          "type": "str"
        },
        "domain_filter": {
          "type": "str | None",
          "default": null
        },
        "area_filter": {
          "type": "str | None",
          "default": null
        },
        "limit": {
          "type": "int",
          "default": 10
        },
        "offset": {
          "type": "Annotated[int | str, Field(default=0, description='Number of results to skip for pagination (default: 0)')]",
          "default": 0
        },
        "group_by_domain": {
          "type": "bool | str",
          "default": false
        },
        "exact_match": {
          "type": "Annotated[bool | str, Field(default=True, description='Use exact substring matching (default: True). Set to False for fuzzy matching when the query may contain typos or approximate terms.')]",
          "default": true
        }
      },
      "required": [
        "query"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Search & Discovery"
    ],
    "source_file": "tools_search.py"
  },
  {
    "name": "ha_bulk_control",
    "title": "Bulk Control",
    "description": "Control multiple devices with bulk operation support and WebSocket tracking.",
    "inputSchema": {
      "properties": {
        "operations": {
          "type": "str | list[dict[str, Any]]"
        },
        "parallel": {
          "type": "bool | str",
          "default": true
        }
      },
      "required": [
        "operations"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Service & Device Control"
    ],
    "source_file": "tools_service.py"
  },
  {
    "name": "ha_call_service",
    "title": "Call Service",
    "description": "Execute Home Assistant services to control entities and trigger automations.\n\nThis is the universal tool for controlling all Home Assistant entities. Services follow\nthe pattern domain.service (e.g., light.turn_on, climate.set_temperature).\n\n**Basic Usage:**\n```python\n# Turn on a light\nha_call_service(\"light\", \"turn_on\", entity_id=\"light.living_room\")\n\n# Set temperature with parameters\nha_call_service(\"climate\", \"set_temperature\",\n              entity_id=\"climate.thermostat\", data={\"temperature\": 22})\n\n# Trigger automation\nha_call_service(\"automation\", \"trigger\", entity_id=\"automation.morning_routine\")\n\n# Universal controls work with any entity\nha_call_service(\"homeassistant\", \"toggle\", entity_id=\"switch.porch_light\")\n```\n\n**Parameters:**\n- **domain**: Service domain (light, climate, automation, etc.)\n- **service**: Service name (turn_on, set_temperature, trigger, etc.)\n- **entity_id**: Optional target entity. For some services (e.g., light.turn_off), omitting this targets all entities in the domain\n- **data**: Optional dict of service-specific parameters\n- **return_response**: Set to True for services that return data\n- **wait**: Wait for the entity state to change after the service call (default: True).\n  Only applies to state-changing services on a single entity. Set to False for\n  fire-and-forget calls, bulk operations, or services without observable state changes.\n\n**For detailed service documentation, use ha_get_skill_home_assistant_best_practices.**\n\nCommon patterns: Use ha_get_state() to check current values before making changes.\nUse ha_search_entities() to find correct entity IDs.",
    "inputSchema": {
      "properties": {
        "domain": {
          "type": "str"
        },
        "service": {
          "type": "str"
        },
        "entity_id": {
          "type": "str | None",
          "default": null
        },
        "data": {
          "type": "str | dict[str, Any] | None",
          "default": null
        },
        "return_response": {
          "type": "bool | str",
          "default": false
        },
        "wait": {
          "type": "bool | str",
          "default": true
        }
      },
      "required": [
        "domain",
        "service"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Service & Device Control"
    ],
    "source_file": "tools_service.py"
  },
  {
    "name": "ha_get_operation_status",
    "title": "Get Operation Status",
    "description": "Check status of one or more device operations with real-time WebSocket verification.\n\nPass a single operation_id string to check one operation, or a list of IDs\nto check multiple operations at once (bulk status).\n\nThe timeout_seconds parameter applies to single-operation checks only.\nBulk checks poll each operation individually with a short internal timeout.\n\nUse this to track operations initiated by ha_bulk_control or ha_call_service.\nFor current entity states, use ha_get_state instead.",
    "inputSchema": {
      "properties": {
        "operation_id": {
          "type": "Annotated[str | list[str], Field(description='Single operation ID or list of operation IDs to check. Use a single string for one operation, or a list for bulk status checks.')]"
        },
        "timeout_seconds": {
          "type": "int",
          "default": 10
        }
      },
      "required": [
        "operation_id"
      ]
    },
    "annotations": {
      "readOnlyHint": true
    },
    "tags": [
      "Service & Device Control"
    ],
    "source_file": "tools_service.py"
  },
  {
    "name": "ha_list_services",
    "title": "List Available Services",
    "description": "List available Home Assistant services with their parameters.\n\nDiscovers services/actions that can be called via ha_call_service.\nReturns service definitions including field names, types, and descriptions.\n\nArgs:\n    domain: Filter by domain (e.g., 'light', 'switch', 'climate').\n           If not provided, returns services from all domains.\n    query: Search in service names and descriptions.\n           Matches against service IDs and their descriptions.\n\nReturns:\n    Dictionary with:\n    - success: Whether the operation succeeded\n    - domains: List of available domains (when no domain filter)\n    - services: Dictionary of service definitions keyed by domain.service\n    - total_count: Total number of services returned\n\nExamples:\n    # List all light services\n    ha_list_services(domain=\"light\")\n\n    # Search for services related to temperature\n    ha_list_services(query=\"temperature\")\n\n    # Get all available services (may be large)\n    ha_list_services()",
    "inputSchema": {
      "properties": {
        "domain": {
          "type": "str | None",
          "default": null
        },
        "query": {
          "type": "str | None",
          "default": null
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Service & Device Control"
    ],
    "source_file": "tools_services.py"
  },
  {
    "name": "ha_backup_create",
    "title": "Create Backup",
    "description": "Create a fast Home Assistant backup (local only).",
    "inputSchema": {
      "properties": {
        "name": {
          "type": "Annotated[str | None, Field(description=\"Backup name (auto-generated if not provided, e.g., 'MCP_Backup_2025-10-05_04:30')\", default=None)]",
          "default": null
        }
      }
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "System"
    ],
    "source_file": "backup.py"
  },
  {
    "name": "ha_backup_restore",
    "title": "Restore Backup",
    "description": "Restore Home Assistant from a backup (LAST RESORT - use with extreme caution).\n\n**⚠️ WARNING - DESTRUCTIVE OPERATION ⚠️**\n\n**This tool restarts Home Assistant and restores configuration to a previous state.**\n\n**IMPORTANT CONSIDERATIONS:**\n1. **Try undo operations first** - Often you can just reverse what you did:\n   - Deleted automation? Recreate it with ha_config_set_automation\n   - Modified script? Use ha_config_set_script to fix it\n   - Most config changes can be rolled back without using restore\n\n2. **Safety mechanism:** A NEW backup is automatically created BEFORE restore\n   - This allows you to rollback the restore if needed\n   - You can restore from this pre-restore backup if something goes wrong\n\n3. **What gets restored:**\n   - Home Assistant configuration (automations, scripts, etc.)\n   - Add-ons (if they were in the backup)\n   - Optional: Database - historical sensor data, statistics, state history (set restore_database=true)\n\n4. **Side effects:**\n   - Home Assistant will RESTART during restore\n   - Any changes made after the backup was created will be LOST\n   - Temporary disconnection from all integrations during restart\n\n**Recommended workflow:**\n1. Try to undo your changes manually first\n2. If you must restore, use the most recent backup\n3. Set restore_database=false unless you need historical data\n4. Expect a restart and temporary downtime\n\n**Example Usage:**\n- Restore config only: ha_backup_restore(\"dd7550ed\")\n- Full restore with DB: ha_backup_restore(\"dd7550ed\", restore_database=true)\n\n**Returns:** Restore job status",
    "inputSchema": {
      "properties": {
        "backup_id": {
          "type": "Annotated[str, Field(description=\"Backup ID to restore (e.g., 'dd7550ed' from backup list or ha_backup_create result)\")]"
        },
        "restore_database": {
          "type": "Annotated[bool, Field(description='Restore database (default: false for config-only restore)', default=False)]",
          "default": false
        }
      },
      "required": [
        "backup_id"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "System"
    ],
    "source_file": "backup.py"
  },
  {
    "name": "ha_check_config",
    "title": "Check Configuration",
    "description": "Check Home Assistant configuration for errors.\n\nValidates configuration files without applying changes.\nAlways run this before ha_restart() to ensure configuration is valid.",
    "inputSchema": {},
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "System"
    ],
    "source_file": "tools_system.py"
  },
  {
    "name": "ha_config_set_yaml",
    "title": "Set YAML Config",
    "description": "Add, replace, or remove a top-level key in configuration.yaml or package files.\n\nIMPORTANT: Only use when NO UI or API alternative exists. Prefer:\n- Template sensors -> ha_config_set_helper (Template Helper)\n- Automations -> ha_config_set_automation\n- Scripts -> ha_config_set_script\n- Input helpers -> ha_config_set_helper\n- Scenes -> ha_config_set_scene\n\nThis tool is for YAML-only features with no UI/API path (e.g.,\ncommand_line sensors, platform-based MQTT sensors in YAML, rest\nsensors defined in packages).\n\nSafeguards: file backup, YAML validation, top-level key whitelist,\npath traversal blocking, post-edit config check.\n\nIMPORTANT: Check 'post_action' in the response. Most keys require\na full HA restart ('restart_required'). Only template, mqtt, and\ngroup support reload ('reload_available' with 'reload_service').\n\nNote: YAML comments are not preserved after editing. The backup\nretains the original file with comments intact.",
    "inputSchema": {
      "properties": {
        "yaml_path": {
          "type": "Annotated[str, Field(description=\"Top-level YAML key to modify (e.g., 'template', 'sensor', 'input_boolean'). Only whitelisted keys are allowed.\")]"
        },
        "action": {
          "type": "Annotated[str, Field(description=\"Action to perform: 'add' (insert/merge content under key), 'replace' (overwrite key with new content), or 'remove' (delete the key entirely).\")]"
        },
        "content": {
          "type": "Annotated[str | None, Field(default=None, description=\"YAML content for the value under yaml_path. Required for 'add' and 'replace' actions. Must be valid YAML.\")]",
          "default": null
        },
        "file": {
          "type": "Annotated[str, Field(default='configuration.yaml', description=\"Relative path to the YAML config file. Defaults to 'configuration.yaml'. Also supports 'packages/*.yaml'.\")]",
          "default": "configuration.yaml"
        },
        "backup": {
          "type": "Annotated[bool | str, Field(default=True, description='Create a backup before editing. Defaults to True. Backups are saved to www/yaml_backups/.')]",
          "default": true
        }
      },
      "required": [
        "yaml_path",
        "action"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": false
    },
    "tags": [
      "System"
    ],
    "source_file": "tools_yaml_config.py"
  },
  {
    "name": "ha_get_system_health",
    "title": "Get System Health",
    "description": "Get Home Assistant system health information.\n\nReturns health check results from integrations, system resources, and connectivity.\nAvailable information varies by installation type and loaded integrations.",
    "inputSchema": {},
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "System"
    ],
    "source_file": "tools_system.py"
  },
  {
    "name": "ha_get_updates",
    "title": "Get Updates",
    "description": "Get update information - list all updates or get details for a specific one.\n\nWithout an entity_id: Lists all available updates across the system including\nHome Assistant Core, add-ons, device firmware, HACS, and OS updates.\n\nWith an entity_id: Returns detailed information about a specific update including\nversion info, category, and release notes (if available).\n\nWith include_release_notes=True (Core updates only): Also fetches HA release\nblog posts for every monthly version between installed and latest. Returns\nstructured breaking changes and installed integration domains for cross-referencing.\n\nEXAMPLES:\n- List all updates: ha_get_updates()\n- List including skipped: ha_get_updates(include_skipped=True)\n- Get specific update: ha_get_updates(entity_id=\"update.home_assistant_core_update\")\n- Pre-update analysis: ha_get_updates(entity_id=\"update.home_assistant_core_update\", include_release_notes=True)\n\nRETURNS (when listing):\n- updates_available: Count of available updates\n- updates: List of update entities with version info\n- categories: Updates grouped by category (core, addons, devices, hacs, os)\n\nRETURNS (when getting specific update):\n- Update details including installed/latest versions\n- Release notes (fetched from WebSocket API or GitHub)\n- Category and installation status\n\nRETURNS (with include_release_notes=True, Core only):\n- breaking_changes.entries[]: Each has integration, description, version\n- multi_version_release_notes[]: Full text per version {version, content, source_url}\n- installed_integrations: Your integration domains for cross-referencing",
    "inputSchema": {
      "properties": {
        "entity_id": {
          "type": "Annotated[str | None, Field(description=\"Update entity ID to get details for (e.g., 'update.home_assistant_core_update'). If omitted, lists all available updates.\", default=None)]",
          "default": null
        },
        "include_skipped": {
          "type": "Annotated[bool | str, Field(description='When listing all updates, include updates that have been skipped (default: False)', default=False)]",
          "default": false
        },
        "include_release_notes": {
          "type": "Annotated[bool | str, Field(description='When getting a Core update entity, fetch multi-version release notes and breaking changes for all versions between installed and latest (default: False). Adds breaking_changes, multi_version_release_notes, and installed_integrations to the response.', default=False)]",
          "default": false
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "openWorldHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "System"
    ],
    "source_file": "tools_updates.py"
  },
  {
    "name": "ha_reload_core",
    "title": "Reload Core Components",
    "description": "Reload Home Assistant configuration without full restart.\n\nThis tool reloads specific configuration components, allowing changes\nto take effect without restarting the entire Home Assistant instance.\nThis is much faster than a full restart.\n\n**Parameters:**\n- target: What to reload. Options:\n  - \"all\": Reload all reloadable components\n  - \"automations\": Reload automation configurations\n  - \"scripts\": Reload script configurations\n  - \"scenes\": Reload scene configurations\n  - \"groups\": Reload group configurations\n  - \"input_booleans\": Reload input_boolean helpers\n  - \"input_numbers\": Reload input_number helpers\n  - \"input_texts\": Reload input_text helpers\n  - \"input_selects\": Reload input_select helpers\n  - \"input_datetimes\": Reload input_datetime helpers\n  - \"input_buttons\": Reload input_button helpers\n  - \"timers\": Reload timer helpers\n  - \"counters\": Reload counter helpers\n  - \"templates\": Reload template sensors/entities\n  - \"persons\": Reload person configurations\n  - \"zones\": Reload zone configurations\n  - \"core\": Reload core configuration (customize, packages)\n  - \"themes\": Reload frontend themes\n\n**Example Usage:**\n```python\n# Reload just automations after editing\nha_reload_core(target=\"automations\")\n\n# Reload all configurations\nha_reload_core(target=\"all\")\n\n# Reload input helpers after adding new ones\nha_reload_core(target=\"input_booleans\")\n```\n\n**When to Use:**\n- After editing automation/script YAML files\n- After adding new input helpers via YAML\n- After modifying customize.yaml\n- After theme changes",
    "inputSchema": {
      "properties": {
        "target": {
          "type": "str",
          "default": "all"
        }
      }
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "System"
    ],
    "source_file": "tools_system.py"
  },
  {
    "name": "ha_restart",
    "title": "Restart Home Assistant",
    "description": "Restart Home Assistant.\n\n**WARNING: This will restart the entire Home Assistant instance!**\nAll automations will be temporarily unavailable during restart.\nThe restart typically takes 1-5 minutes depending on your setup.\n\n**Parameters:**\n- confirm: Must be set to True to confirm the restart. This is a safety\n           measure to prevent accidental restarts.\n\n**Best Practices:**\n1. Always run ha_check_config() first to ensure configuration is valid\n2. Notify users before restarting (if applicable)\n3. Schedule restarts during low-activity periods\n\n**Example Usage:**\n```python\n# Always check config first\nconfig = ha_check_config()\nif config[\"result\"] == \"valid\":\n    # Restart with confirmation\n    result = ha_restart(confirm=True)\n```\n\n**Alternative:** For configuration changes, consider using ha_reload_core()\ninstead, which reloads specific components without a full restart.",
    "inputSchema": {
      "properties": {
        "confirm": {
          "type": "bool | str",
          "default": false
        }
      }
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "System"
    ],
    "source_file": "tools_system.py"
  },
  {
    "name": "ha_add_todo_item",
    "title": "Add Todo Item",
    "description": "Add an item to a Home Assistant todo list.\n\nCreates a new item in the specified todo list with optional description and due date.\n\nPARAMETERS:\n- entity_id: The todo list to add to (e.g., 'todo.shopping_list')\n- summary: The item text (required)\n- description: Optional detailed description\n- due_date: Optional due date (YYYY-MM-DD format)\n- due_datetime: Optional due datetime (ISO format, overrides due_date if both provided)\n\nEXAMPLES:\n- Add simple item: ha_add_todo_item(\"todo.shopping_list\", \"Buy milk\")\n- Add with description: ha_add_todo_item(\"todo.shopping_list\", \"Buy milk\", description=\"2% organic\")\n- Add with due date: ha_add_todo_item(\"todo.tasks\", \"Pay bills\", due_date=\"2024-12-31\")\n\nUSE CASES:\n- \"Add milk to my shopping list\"\n- \"Add 'call mom' to my todo list\"\n- \"Remind me to pay rent by the 1st\"\n\nNOTE: Not all todo integrations support all features (description, due dates).\nThe Shopping List integration only supports summary.",
    "inputSchema": {
      "properties": {
        "entity_id": {
          "type": "Annotated[str, Field(description=\"Todo list entity ID (e.g., 'todo.shopping_list')\")]"
        },
        "summary": {
          "type": "Annotated[str, Field(description=\"Item text/name to add (e.g., 'Buy milk')\")]"
        },
        "description": {
          "type": "Annotated[str | None, Field(description='Optional detailed description for the item', default=None)]",
          "default": null
        },
        "due_date": {
          "type": "Annotated[str | None, Field(description=\"Optional due date in YYYY-MM-DD format (e.g., '2024-12-25')\", default=None)]",
          "default": null
        },
        "due_datetime": {
          "type": "Annotated[str | None, Field(description=\"Optional due datetime in ISO format (e.g., '2024-12-25T14:00:00')\", default=None)]",
          "default": null
        }
      },
      "required": [
        "entity_id",
        "summary"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Todo Lists"
    ],
    "source_file": "tools_todo.py"
  },
  {
    "name": "ha_get_todo",
    "title": "Get Todo",
    "description": "Get todo lists or items - list all todo lists or get items from a specific list.\n\nWithout an entity_id: Lists all todo list entities in Home Assistant.\nWith an entity_id: Gets items from that specific todo list, optionally filtered by status.\n\n**LISTING TODO LISTS (entity_id omitted):**\nReturns all entities in the 'todo' domain, including shopping lists\nand any other todo-type integrations.\n\nEach todo list includes:\n- entity_id: The unique identifier (e.g., 'todo.shopping_list')\n- friendly_name: Human-readable name\n- state: Number of incomplete items or current status\n\n**GETTING TODO ITEMS (entity_id provided):**\nRetrieves items from the specified todo list.\n\nStatus filter values:\n- needs_action: Items that still need to be done\n- completed: Items that have been marked as done\n- None (default): Returns all items regardless of status\n\nItem properties:\n- uid: Unique identifier for the item\n- summary: The item text/description\n- status: Current status (needs_action or completed)\n- description: Optional detailed description\n- due: Optional due date (if supported)\n\nEXAMPLES:\n- List all todo lists: ha_get_todo()\n- Get all items: ha_get_todo(\"todo.shopping_list\")\n- Get incomplete items: ha_get_todo(\"todo.shopping_list\", status=\"needs_action\")\n- Get completed items: ha_get_todo(\"todo.shopping_list\", status=\"completed\")\n\nUSE CASES:\n- \"What todo lists do I have?\"\n- \"Show me my shopping list\"\n- \"What's on my todo list?\"\n- \"Show completed items\"",
    "inputSchema": {
      "properties": {
        "entity_id": {
          "type": "Annotated[str | None, Field(description=\"Todo list entity ID (e.g., 'todo.shopping_list'). If omitted, lists all todo list entities.\", default=None)]",
          "default": null
        },
        "status": {
          "type": "Annotated[Literal['needs_action', 'completed'] | None, Field(description=\"Filter items by status: 'needs_action' for incomplete, 'completed' for done. Only applies when entity_id is provided.\", default=None)]",
          "default": null
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Todo Lists"
    ],
    "source_file": "tools_todo.py"
  },
  {
    "name": "ha_remove_todo_item",
    "title": "Remove Todo Item",
    "description": "Remove an item from a Home Assistant todo list.\n\nPermanently deletes an item from the specified todo list.\n\nIDENTIFYING ITEMS:\n- Use the item's UID (from ha_get_todo)\n- Or use the exact item summary/name text\n\nEXAMPLES:\n- Remove by name: ha_remove_todo_item(\"todo.shopping_list\", \"Buy milk\")\n- Remove by UID: ha_remove_todo_item(\"todo.shopping_list\", \"abc123-uid\")\n\nUSE CASES:\n- \"Remove milk from my shopping list\"\n- \"Delete the eggs item\"\n- \"Clear 'call mom' from my todo\"\n\nWARNING: This permanently removes the item. To mark as completed instead,\nuse ha_update_todo_item() with status=\"completed\".",
    "inputSchema": {
      "properties": {
        "entity_id": {
          "type": "Annotated[str, Field(description=\"Todo list entity ID (e.g., 'todo.shopping_list')\")]"
        },
        "item": {
          "type": "Annotated[str, Field(description='Item to remove - can be the item UID or the exact item summary/name')]"
        }
      },
      "required": [
        "entity_id",
        "item"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": true
    },
    "tags": [
      "Todo Lists"
    ],
    "source_file": "tools_todo.py"
  },
  {
    "name": "ha_update_todo_item",
    "title": "Update Todo Item",
    "description": "Update or complete a todo item in Home Assistant.\n\nModifies an existing item in the specified todo list. Can be used to:\n- Mark items as completed or incomplete\n- Rename items\n- Update descriptions and due dates\n\nIDENTIFYING ITEMS:\n- Use the item's UID (from ha_get_todo)\n- Or use the exact item summary/name text\n\nSTATUS VALUES:\n- completed: Mark the item as done\n- needs_action: Mark the item as not done (reopen)\n\nEXAMPLES:\n- Complete item: ha_update_todo_item(\"todo.shopping_list\", \"Buy milk\", status=\"completed\")\n- Rename item: ha_update_todo_item(\"todo.tasks\", \"Old task\", rename=\"New task name\")\n- Update due date: ha_update_todo_item(\"todo.tasks\", \"Pay bills\", due_date=\"2024-12-31\")\n- Reopen item: ha_update_todo_item(\"todo.tasks\", \"Task to redo\", status=\"needs_action\")\n\nUSE CASES:\n- \"Mark milk as bought\"\n- \"Complete the eggs on my shopping list\"\n- \"Change the due date for my task\"\n- \"Rename 'call mom' to 'video call with mom'\"\n\nNOTE: At least one update field (rename, status, description, due_date, due_datetime) must be provided.",
    "inputSchema": {
      "properties": {
        "entity_id": {
          "type": "Annotated[str, Field(description=\"Todo list entity ID (e.g., 'todo.shopping_list')\")]"
        },
        "item": {
          "type": "Annotated[str, Field(description='Item to update - can be the item UID or the exact item summary/name')]"
        },
        "rename": {
          "type": "Annotated[str | None, Field(description='New name/summary for the item', default=None)]",
          "default": null
        },
        "status": {
          "type": "Annotated[Literal['needs_action', 'completed'] | None, Field(description=\"New status: 'completed' to mark done, 'needs_action' to mark incomplete\", default=None)]",
          "default": null
        },
        "description": {
          "type": "Annotated[str | None, Field(description='New description for the item', default=None)]",
          "default": null
        },
        "due_date": {
          "type": "Annotated[str | None, Field(description='New due date in YYYY-MM-DD format', default=None)]",
          "default": null
        },
        "due_datetime": {
          "type": "Annotated[str | None, Field(description='New due datetime in ISO format', default=None)]",
          "default": null
        }
      },
      "required": [
        "entity_id",
        "item"
      ]
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Todo Lists"
    ],
    "source_file": "tools_todo.py"
  },
  {
    "name": "ha_eval_template",
    "title": "Evaluate Template",
    "description": "Evaluate Jinja2 templates using Home Assistant's template engine.\n\nThis tool allows testing and debugging of Jinja2 template expressions that are commonly used in\nHome Assistant automations, scripts, and configurations. It provides real-time evaluation with\naccess to all Home Assistant states, functions, and template variables.\n\n**Parameters:**\n- template: The Jinja2 template string to evaluate\n- timeout: Maximum evaluation time in seconds (default: 3)\n- report_errors: Whether to return detailed error information (default: True)\n\n**Common Template Functions:**\n\n**State Access:**\n```jinja2\n{{ states('sensor.temperature') }}              # Get entity state value\n{{ states.sensor.temperature.state }}           # Alternative syntax\n{{ state_attr('light.bedroom', 'brightness') }} # Get entity attribute\n{{ is_state('light.living_room', 'on') }}       # Check if entity has specific state\n```\n\n**Numeric Operations:**\n```jinja2\n{{ states('sensor.temperature') | float(0) }}   # Convert to float with default\n{{ states('sensor.humidity') | int }}           # Convert to integer\n{{ (states('sensor.temp') | float + 5) | round(1) }} # Math operations\n```\n\n**Time and Date:**\n```jinja2\n{{ now() }}                                     # Current datetime\n{{ now().strftime('%H:%M:%S') }}               # Format current time\n{{ as_timestamp(now()) }}                      # Convert to Unix timestamp\n{{ now().hour }}                               # Current hour (0-23)\n{{ now().weekday() }}                          # Day of week (0=Monday)\n```\n\n**Conditional Logic:**\n```jinja2\n{{ 'Day' if now().hour < 18 else 'Night' }}    # Ternary operator\n{% if is_state('sun.sun', 'above_horizon') %}\n  It's daytime\n{% else %}\n  It's nighttime\n{% endif %}\n```\n\n**Lists and Loops:**\n```jinja2\n{% for entity in states.light %}\n  {{ entity.entity_id }}: {{ entity.state }}\n{% endfor %}\n\n{{ states.light | selectattr('state', 'eq', 'on') | list | count }} # Count on lights\n```\n\n**String Operations:**\n```jinja2\n{{ states('sensor.weather') | title }}         # Title case\n{{ 'Hello ' + states('input_text.name') }}     # String concatenation\n{{ states('sensor.data') | regex_replace('pattern', 'replacement') }}\n```\n\n**Device and Area Functions:**\n```jinja2\n{{ device_entities('device_id_here') }}        # Get entities for device\n{{ area_entities('living_room') }}             # Get entities in area\n{{ device_id('light.bedroom') }}               # Get device ID for entity\n```\n\n**Common Use Cases:**\n\n**Automation Conditions:**\n```jinja2\n# Check if it's a workday and after 7 AM\n{{ is_state('binary_sensor.workday', 'on') and now().hour >= 7 }}\n\n# Temperature-based condition\n{{ states('sensor.outdoor_temp') | float < 0 }}\n```\n\n**Dynamic Service Data:**\n```jinja2\n# Dynamic brightness based on time\n{{ 255 if now().hour < 22 else 50 }}\n\n# Message with current values\n\"Temperature is {{ states('sensor.temp') }}°C, humidity {{ states('sensor.humidity') }}%\"\n```\n\n**Examples:**\n\n**Test basic state access:**\n```python\nha_eval_template(\"{{ states('light.living_room') }}\")\n```\n\n**Test conditional logic:**\n```python\nha_eval_template(\"{{ 'Day' if now().hour < 18 else 'Night' }}\")\n```\n\n**Test mathematical operations:**\n```python\nha_eval_template(\"{{ (states('sensor.temperature') | float + 5) | round(1) }}\")\n```\n\n**Test complex automation condition:**\n```python\nha_eval_template(\"{{ is_state('binary_sensor.workday', 'on') and now().hour >= 7 and states('sensor.temperature') | float > 20 }}\")\n```\n\n**Test entity counting:**\n```python\nha_eval_template(\"{{ states.light | selectattr('state', 'eq', 'on') | list | count }}\")\n```\n\n**IMPORTANT NOTES:**\n- Templates have access to all current Home Assistant states and attributes\n- Use this tool to test templates before using them in automations or scripts\n- Template evaluation respects Home Assistant's security model and timeouts\n- Complex templates may affect Home Assistant performance - keep them efficient\n- Use default values (e.g., `| float(0)`) to handle missing or invalid states\n\n**For template documentation:** https://www.home-assistant.io/docs/configuration/templating/",
    "inputSchema": {
      "properties": {
        "template": {
          "type": "str"
        },
        "timeout": {
          "type": "int",
          "default": 3
        },
        "report_errors": {
          "type": "bool | str",
          "default": true
        }
      },
      "required": [
        "template"
      ]
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Utilities"
    ],
    "source_file": "tools_utility.py"
  },
  {
    "name": "ha_install_mcp_tools",
    "title": "Install MCP Tools Component",
    "description": "Install the ha_mcp_tools custom component via HACS.\n\nThis tool installs the ha_mcp_tools custom component which provides\nadvanced services not available through standard Home Assistant APIs:\n\n**Available Services (after installation):**\n- `ha_mcp_tools.list_files`: List files in allowed directories (www/, themes/)\n- More services coming soon: file write, backup cleanup, event buffer, etc.\n\n**Installation Process:**\n1. Checks if HACS is available\n2. Checks if ha_mcp_tools is already installed\n3. Adds the repository to HACS if not present\n4. Downloads and installs the component\n5. Optionally restarts Home Assistant\n\n**Note:** A restart is required for the integration to load and become available.\nSet `restart=True` to automatically restart, or manually restart later.\n\nArgs:\n    restart: Whether to restart Home Assistant after installation (default: False)\n\nReturns:\n    Installation status and next steps.",
    "inputSchema": {
      "properties": {
        "restart": {
          "type": "Annotated[bool, Field(default=False, description='Whether to restart Home Assistant after installation (required for integration to load)')]",
          "default": false
        }
      }
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Utilities"
    ],
    "source_file": "tools_mcp_component.py"
  },
  {
    "name": "ha_report_issue",
    "title": "Report Issue or Feedback",
    "description": "Collect diagnostic information for filing issue reports or feedback.\n\nThis tool generates templates for TWO types of reports:\n1. **Runtime Bug Report** - For ha-mcp errors, failures, unexpected behavior\n2. **Agent Behavior Feedback** - For AI agent inefficiency, wrong tool usage\n\n**IMPORTANT FOR AI AGENTS:**\nYou MUST analyze the conversation context to determine which template to present:\n\n🐛 **Present RUNTIME BUG template if:**\n   - User reports an error, failure, or unexpected behavior\n   - A tool returned an error or incorrect result\n   - Something is broken or not working in ha-mcp\n\n🤖 **Present AGENT BEHAVIOR template if:**\n   - User mentions YOU (the agent) used the wrong tool\n   - User suggests a more efficient workflow\n   - User reports YOUR inefficiency or mistakes\n   - User says you should have done something differently\n\n**If unclear which type, ASK the user:**\n\"Are you reporting a bug in ha-mcp, or providing feedback on how I used the tools?\"\n\n**WHEN TO USE THIS TOOL:**\n- \"I want to file a bug/issue/report\"\n- \"This isn't working\"\n- \"You should have used [other tool]\"\n- \"That was inefficient\"\n\n**OUTPUT:**\nReturns both templates. Choose the appropriate one based on context.",
    "inputSchema": {
      "properties": {
        "tool_call_count": {
          "type": "Annotated[int, Field(default=10, ge=1, le=16, description='Number of tool calls made since the issue started. This determines how many log entries to include. Count how many ha_* tools were called from when the issue began. Default: 10. Max: 16 (limited by 200-entry log buffer: 16*4*3=192)')]",
          "default": 10
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Utilities"
    ],
    "source_file": "tools_bug_report.py"
  },
  {
    "name": "ha_get_zone",
    "title": "Get Zone",
    "description": "Get zone information - list all zones or get details for a specific one.\n\nWithout a zone_id: Lists all Home Assistant zones with their coordinates and radius.\nWith a zone_id: Returns detailed configuration for a specific zone.\n\nZONE PROPERTIES:\n- ID, name, icon\n- Latitude, longitude, radius\n- Passive mode setting\n\nEXAMPLES:\n- List all zones: ha_get_zone()\n- Get specific zone: ha_get_zone(zone_id=\"abc123\")\n\n**NOTE:** This returns storage-based zones (created via UI/API), not YAML-defined zones.\nThe 'home' zone is typically defined in YAML and may not appear in this list.",
    "inputSchema": {
      "properties": {
        "zone_id": {
          "type": "Annotated[str | None, Field(description='Zone ID to get details for (from ha_get_zone() list). If omitted, lists all zones.', default=None)]",
          "default": null
        }
      }
    },
    "annotations": {
      "idempotentHint": true,
      "readOnlyHint": true
    },
    "tags": [
      "Zones"
    ],
    "source_file": "tools_zones.py"
  },
  {
    "name": "ha_remove_zone",
    "title": "Remove Zone",
    "description": "Remove a Home Assistant zone.\n\nEXAMPLES:\n- Remove zone: ha_remove_zone(\"abc123\")\n\n**WARNING:** Removing a zone used in automations may cause those automations to fail.\nUse ha_get_zone() to find the zone_id for the zone you want to remove.\n\n**NOTE:** The 'home' zone cannot be removed as it is typically defined in configuration.yaml.",
    "inputSchema": {
      "properties": {
        "zone_id": {
          "type": "Annotated[str, Field(description='Zone ID to remove (use ha_get_zone to find IDs)')]"
        }
      },
      "required": [
        "zone_id"
      ]
    },
    "annotations": {
      "destructiveHint": true,
      "idempotentHint": true
    },
    "tags": [
      "Zones"
    ],
    "source_file": "tools_zones.py"
  },
  {
    "name": "ha_set_zone",
    "title": "Set Zone",
    "description": "Create or update a Home Assistant zone.\n\nOmit zone_id to create a new zone (name, latitude, longitude required).\nProvide zone_id to update an existing zone (only specified fields change).\n\nEXAMPLES:\n- Create: ha_set_zone(name=\"Office\", latitude=40.7128, longitude=-74.0060, radius=150, icon=\"mdi:briefcase\")\n- Update name: ha_set_zone(zone_id=\"abc123\", name=\"New Office\")\n- Update radius: ha_set_zone(zone_id=\"abc123\", radius=200)\n- Update location: ha_set_zone(zone_id=\"abc123\", latitude=40.7128, longitude=-74.0060)\n\nNote: The 'home' zone is typically defined in YAML and cannot be modified via this API.",
    "inputSchema": {
      "properties": {
        "name": {
          "type": "Annotated[str | None, Field(description='Display name for the zone (required for create)', default=None)]",
          "default": null
        },
        "latitude": {
          "type": "Annotated[float | None, Field(description='Latitude coordinate of the zone center (required for create)', default=None)]",
          "default": null
        },
        "longitude": {
          "type": "Annotated[float | None, Field(description='Longitude coordinate of the zone center (required for create)', default=None)]",
          "default": null
        },
        "zone_id": {
          "type": "Annotated[str | None, Field(description='Zone ID to update (omit to create new zone, use ha_get_zone to find IDs)', default=None)]",
          "default": null
        },
        "radius": {
          "type": "Annotated[float | None, Field(description='Radius of the zone in meters (must be > 0, defaults to 100 on create)', default=None)]",
          "default": null
        },
        "icon": {
          "type": "Annotated[str | None, Field(description=\"Material Design Icon (e.g., 'mdi:briefcase', 'mdi:school')\", default=None)]",
          "default": null
        },
        "passive": {
          "type": "Annotated[bool | None, Field(description='Passive mode - if True, zone will not trigger enter/exit automations (defaults to False on create)', default=None)]",
          "default": null
        }
      }
    },
    "annotations": {
      "destructiveHint": true
    },
    "tags": [
      "Zones"
    ],
    "source_file": "tools_zones.py"
  }
]