Get the Home Assistant version

Returns: A string with the Home Assistant version (e.g., "2025.3.0")

Get the state of a Home Assistant entity with optional field filtering

Args: entity_id: The entity ID to get (e.g. 'light.living_room') fields: Optional list of fields to include (e.g. ['state', 'attr.brightness']) detailed: If True, returns all entity fields without filtering

Examples: entity_id="light.living_room" - basic state check entity_id="light.living_room", fields=["state", "attr.brightness"] - specific fields entity_id="light.living_room", detailed=True - all details

Perform an action on a Home Assistant entity (on, off, toggle)

Args: entity_id: The entity ID to control (e.g. 'light.living_room') action: The action to perform ('on', 'off', 'toggle') params: Optional dictionary of additional parameters for the service call

Returns: The response from Home Assistant

Examples: entity_id="light.living_room", action="on", params={"brightness": 255} entity_id="switch.garden_lights", action="off" entity_id="climate.living_room", action="on", params={"temperature": 22.5}

Domain-Specific Parameters: - Lights: brightness (0-255), color_temp, rgb_color, transition, effect - Covers: position (0-100), tilt_position - Climate: temperature, target_temp_high, target_temp_low, hvac_mode - Media players: source, volume_level (0-1)

Get a list of Home Assistant entities with optional filtering

Args: domain: Optional domain to filter by (e.g., 'light', 'switch', 'sensor') search_query: Optional search term to filter entities by name, id, or attributes (Note: Does not support wildcards. To get all entities, leave this empty) limit: Maximum number of entities to return (default: 100) fields: Optional list of specific fields to include in each entity detailed: If True, returns all entity fields without filtering

Returns: A list of entity dictionaries with lean formatting by default

Examples: domain="light" - get all lights search_query="kitchen", limit=20 - search entities domain="sensor", detailed=True - full sensor details

Best Practices: - Use lean format (default) for most operations - Prefer domain filtering over no filtering - For domain overviews, use domain_summary_tool instead of list_entities - Only request detailed=True when necessary for full attribute inspection - To get all entity types/domains, use list_entities without a domain filter, then extract domains from entity_ids

Get all entities assigned to a specific Home Assistant area (room).

Area lookup is case-insensitive and matches the area's name as configured in Home Assistant (e.g., "Kitchen", "Living Room"). Entities inherit their area from their parent device when no area is set directly, matching HA's own resolution behavior.

Args: area: Name of the area to filter by (case-insensitive) domain: Optional domain to further filter results (e.g., 'light') lean: If True (default), returns token-efficient entity records

Returns: A dictionary containing: - area: The matched area name (as canonicalized by HA) - count: Number of matching entities - entities: List of entity records with their state and area

Examples: get_entities_by_area(area="Kitchen") - everything in the kitchen get_entities_by_area(area="Living Room", domain="light") - lights only

Search for entities matching a query string

Args: query: The search query to match against entity IDs, names, and attributes. (Note: Does not support wildcards. To get all entities, leave this blank or use list_entities tool) limit: Maximum number of results to return (default: 20)

Returns: A dictionary containing search results and metadata: - count: Total number of matching entities found - results: List of matching entities with essential information - domains: Map of domains with counts (e.g. {"light": 3, "sensor": 2})

Examples: query="temperature" - find temperature entities query="living room", limit=10 - find living room entities query="", limit=500 - list all entity types

Get a summary of entities in a specific domain

Args: domain: The domain to summarize (e.g., 'light', 'switch', 'sensor') example_limit: Maximum number of examples to include for each state

Returns: A dictionary containing: - total_count: Number of entities in the domain - state_distribution: Count of entities in each state - examples: Sample entities for each state - common_attributes: Most frequently occurring attributes

Examples: domain="light" - get light summary domain="climate", example_limit=5 - climate summary with more examples Best Practices: - Use this before retrieving all entities in a domain to understand what's available

Get a comprehensive overview of the entire Home Assistant system

Returns: A dictionary containing: - total_entities: Total count of all entities - domains: Dictionary of domains with their entity counts and state distributions - domain_samples: Representative sample entities for each domain (2-3 per domain) - domain_attributes: Common attributes for each domain - area_distribution: Entities grouped by area (if available)

Examples: Returns domain counts, sample entities, and common attributes Best Practices: - Use this as the first call when exploring an unfamiliar Home Assistant instance - Perfect for building context about the structure of the smart home - After getting an overview, use domain_summary_tool to dig deeper into specific domains

Get a list of all automations from Home Assistant

This function retrieves all automations configured in Home Assistant, including their IDs, entity IDs, state, and display names.

Returns: A list of automation dictionaries, each containing id, entity_id, state, and alias (friendly name) fields.

Examples: Returns all automation objects with state and friendly names

Restart Home Assistant

⚠️ WARNING: Temporarily disrupts all Home Assistant operations

Returns: Result of restart operation

Call any Home Assistant service (low-level API access)

Args: domain: The domain of the service (e.g., 'light', 'switch', 'automation') service: The service to call (e.g., 'turn_on', 'turn_off', 'toggle') data: Optional data to pass to the service (e.g., {'entity_id': 'light.living_room'})

Returns: A dictionary with success status, the domain/service called, and the list of affected entity states returned by Home Assistant.

Examples: domain='light', service='turn_on', data={'entity_id': 'light.x', 'brightness': 255} domain='automation', service='reload' domain='fan', service='set_percentage', data={'entity_id': 'fan.x', 'percentage': 50}

Get the history of an entity's state changes

Args: entity_id: The entity ID to get history for hours: Number of hours of history to retrieve (default: 24)

Returns: A dictionary containing: - entity_id: The entity ID requested - states: List of state objects with timestamps - count: Number of state changes found - first_changed: Timestamp of earliest state change - last_changed: Timestamp of most recent state change

Examples: entity_id="light.living_room" - get 24h history entity_id="sensor.temperature", hours=168 - get 7 day history Best Practices: - Keep hours reasonable (24-72) for token efficiency - Use for entities with discrete state changes rather than continuously changing sensors - Consider the state distribution rather than every individual state

Get the Home Assistant error log for troubleshooting

Returns: A dictionary containing: - log_text: The full error log text - error_count: Number of ERROR entries found - warning_count: Number of WARNING entries found - integration_mentions: Map of integration names to mention counts - error: Error message if retrieval failed

Examples: Returns errors, warnings count and integration mentions Best Practices: - Use this tool when troubleshooting specific Home Assistant errors - Look for patterns in repeated errors - Pay attention to timestamps to correlate errors with events - Focus on integrations with many mentions in the log

Fetch a full Lovelace dashboard config via WebSocket.

Args: url_path: Dashboard slug (e.g. "scenes" for a custom dashboard). Pass None (default) for the built-in Overview dashboard.

Fetch a single view from a Lovelace dashboard by title or path.

Args: view_name: Matched against view['path'] first, then view['title'] (case-insensitive). url_path: Dashboard slug, or None for the Overview dashboard.

Save (overwrite) an entire Lovelace dashboard config.

Args: config: The complete dashboard config dict (as returned by :func:get_lovelace_dashboard). url_path: Dashboard slug, or None for Overview.

Returns the raw HA response envelope so the caller can inspect success.

Get a stored HA config item (automation, scene, script, etc.) by numeric ID.

Args: item_type: One of automation, scene, script. item_id: Numeric config ID (not the entity_id) — e.g. "1722562028372".

Fetch logs for a Supervisor add-on as plain text.

Args: slug: Add-on slug (e.g. "a0d7b954_nginxproxymanager"). tail: If set, return only the last N lines.

Fetch the Home Assistant Core log as plain text.

Replaces the upstream get_error_log tool, which hits /api/error_log — an endpoint removed in HA 2026.5+. This uses the Supervisor proxy /api/hassio/core/logs/latest instead.

Args: tail: If set, return only the last N lines after any grep filtering. grep: Optional case-insensitive substring filter applied per line (e.g. "http.ban" to find failed login attempts).

Read a file from the Home Assistant host over SSH.

Reads are restricted to standard HA-exposed directories: /config, /share, /ssl, /addons, /media, /backup.

Args: path: Absolute path on the HA host (e.g. /config/ip_bans.yaml). tail: If set, return only the last N lines after any grep filtering. grep: Optional case-insensitive substring filter applied per line.

List a directory on the Home Assistant host over SSH (ls -la).

Restricted to the same allowed roots as :func:read_ha_file.

Args: path: Absolute directory path (e.g. /config).

Create or overwrite a stored automation config via the HA REST API.

Args: automation_id: Unique string ID for the automation (e.g. a timestamp like "1716300000000"). Use a new value to create; pass the existing ID to update in place. config: Full automation config dict. Must include at least alias, trigger, action, and mode. Do NOT include "id" — it is injected automatically from automation_id.

Returns the raw HA response (usually {"result": "ok"}).

Run a read-only SQL SELECT against the Home Assistant recorder (MariaDB).

Use this for ad-hoc queries against the recorder database — e.g. fetching Zigbee action events, checking state history, or inspecting statistics.

Only SELECT statements are allowed. Key tables:

• states — entity state changes (joined to states_meta for entity_id)

• states_meta — maps metadata_id -> entity_id

• events — HA events (joined to event_types for event name)

• event_types — maps event_type_id -> event_type

• event_data — JSON payload blobs (joined via data_id)

• statistics — hourly aggregates

• statistics_short_term — 5-minute aggregates

Timestamps are stored as DATETIME in UTC (last_updated_ts / time_fired_ts are FLOAT unix epoch seconds; the older last_updated / time_fired DATETIME columns may be NULL in recent HA versions — use the _ts columns instead).

Args: sql: A SELECT statement to execute.

Fetch recent Zigbee action events for a device directly from the recorder DB.

Much more efficient than the logbook API — returns only the rows you need without loading the entire logbook into memory.

The action is stored in state_attributes.shared_attrs as event_type (e.g. down_double, up_single). This tool extracts it via JSON_UNQUOTE and returns one row per event.

Args: device_name: Friendly device name as it appears in Zigbee2MQTT, e.g. "Master Light Switch". Converted to the entity slug automatically (e.g. event.master_light_switch_action). minutes: How many minutes of history to return (default 60, max 10080). action: Optional filter, e.g. "down_double". If omitted, all actions are returned.

Fetch logbook entries for an entity, including full event attributes.

Queries the recorder MariaDB directly via SSH rather than the logbook HTTP API, avoiding the massive response payloads the API endpoint returns.

For event.*_action entities the action name is extracted from state_attributes.shared_attrs and returned as action. For all other entities state is returned as-is.

Args: entity_id: Entity to query (e.g. "event.master_light_switch_action"). hours: How many hours of history to fetch (default 24, max 168).

Fetch add-on logs and filter lines by a case-insensitive substring.

Avoids blowing the token limit when logs are very large.

Args: slug: Add-on slug (e.g. "45df7312_zigbee2mqtt"). grep: Case-insensitive substring to filter lines by. tail: Return only the last N matching lines (default 200).

Look up device registry info for a device — integration, manufacturer, model, connections.

Useful for determining which network/protocol a device uses (Zigbee, Z-Wave, Matter, Thread, etc.) and its config entry, so you know how to re-pair or debug it.

Pass exactly one of entity_id or device_name.

Args: entity_id: Any entity belonging to the device, e.g. "binary_sensor.motion_pantry_occupancy". device_name: Friendly device name, e.g. "Motion Pantry". Matched case-insensitively against the device's name and name_by_user fields.

Returns a dict with keys: id, name, name_by_user, manufacturer, model, sw_version, hw_version, integration (config entry domain), config_entry_title, connections (e.g. Zigbee IEEE address), identifiers, and disabled_by.

Update a stored scene's entity states.

Args: scene_id: Numeric scene ID from get_ha_config_item("scene", ...). name: Display name for the scene. entities: Mapping of entity_id -> state dict, e.g. {"fan.upstairs": {"state": "on", "percentage": 16}}.