Tools reference

Create, edit, or delete automations in the YAML file your configuration.yaml routes automations to. Split configurations (!include and !include_dir_* layouts) are followed to the correct leaf file and only the target entry's lines are rewritten: comments, formatting, and !secret references elsewhere in the file are preserved byte-for-byte. New automations are appended for a plain !include, or written as a new file per entry for directory includes. Ambiguous cases (duplicate ids across files, entries in packages or inline config, multiple create targets) are refused rather than guessed at.

create

config (required), an object holding alias, trigger, action, plus optional condition, mode

edit / delete

automation_id (the slug); edit replaces the entire config

Create, edit, or delete scripts in the YAML file your configuration.yaml routes scripts to. Split configurations (!include and !include_dir_named/merge_named layouts) are followed to the correct leaf file, preserving untouched content byte-for-byte, the same include-graph handling as the automation tools.

create

script_id and config (both required), where config holds alias, sequence, mode, variables, fields

edit / delete

script_id (the slug); edit replaces the entire config

Read a curated subset of Home Assistant's configuration: version, time zone, unit system, location name, and the list of loaded integrations. Precise home coordinates, internal/external URLs, and host filesystem paths are withheld.

List installed automation and script blueprints with their inputs. To instantiate one, create an automation or script with a use_blueprint config (the existing authoring tools accept it); there is no separate create-from-blueprint tool.

params

domain (optional, automation or script)

Recent HA system log entries. ATM's own entries are excluded and token values, JWTs, and URL credentials are scrubbed from messages and tracebacks. The scrubber is pattern-based and cannot guarantee removal of arbitrary third-party secrets or PII an integration writes into a log line, so treat Log read as an elevated-trust grant.

params

limit (default 50, max 100), level (INFO / WARNING / ERROR)

The human-readable logbook (state changes, automations and scripts triggered). Scoped to entities the token can access; entries for out-of-scope entities are dropped. This is the narrative event history, distinct from get_logs (error log) and get_history (raw samples).

params

start_time (default 24h), end_time, entity_id (optional, focus on one entity), limit (default 100, max 1000)

Render a Jinja2 template in a permission-scoped environment; templates can only reach entities the token can read.

params

template (string, required)

check_config validates the HA configuration files. validate_config validates an automation or script config without saving and reports, per referenced entity, whether it is accessible to the token (entities outside the token's scope are reported as inaccessible and not visible).

Compare accessible entities' states between two times, backed by the recorder.

One area, its floor, and accessible entities grouped by domain. Takes an area name, alias, or area_id.

Comprehension summary of one entity: state, area, the services in its domain, what references it, and its MESA control_mode when MESA is active.

The services in an entity's domain and whether the token can invoke each one now, accounting for write access, physical and dual gates, and the entity's MESA control_mode.

Execution traces for an accessible automation. Optional run_id and summary (highlights the error and last step).

Compact home summary: total accessible entities, counts by domain and area, the unavailable count, and the deployment mesa_mode. When MESA is active and the token has Config Read, it also includes the operator-set prohibited and read-only entities (the “do not operate” list), so the agent learns what is off-limits in one call.

Reverse references (automations, scripts, scenes that reference the entity) and forward references, scoped to what the token can access.

Home Assistant version and per-integration system health. Secret-keyed values and URL-embedded credentials in the integration data are scrubbed before they are returned, as are network-topology details (LAN IP addresses, hostnames inside URLs, and filesystem paths) that ATM withholds elsewhere. This is an elevated read; treat cap_diagnostics accordingly.

Radio-network health (Zigbee2MQTT or ZHA, auto-detected). get_radio_network reports every radio network present: channel, PAN id, coordinator, and whether the pairing window is open. get_radio_device reports one device's signal quality (LQI/RSSI), availability, power source, interview state, and (ZHA) mesh neighbors, with out-of-scope neighbor identifiers redacted. Network keys never appear in any response.

params

get_radio_network: none; get_radio_device: device_id

Registry enumeration restricted to areas, floors, zones, and devices that contain at least one accessible entity. get_device returns one device plus its accessible entities.

Enumerate accessible scenes and helpers.

Accessible entities that changed in the last N minutes, newest first.

Filter accessible entities by query, domain, area, device class, state, and staleness. A multi-word query matches entities containing all the words and results are ranked by relevance, so the best matches lead. If that exact matching finds nothing, a typo-tolerant fallback retries against entity id and friendly name, tagging the response fuzzy_fallback: true. Each row carries control_mode when its MESA nature is non-default, so restricted entities are visible without a follow-up call.

params

query, domain, area, device_class, state, unavailable, stale_hours, limit (all optional)

Predict which automations would fire if an accessible entity changed to a hypothetical state, without changing anything. State and numeric_state triggers are evaluated best-effort.

Read and edit configuration.yaml directly. Confirm-eligible. get_yaml_config returns the file verbatim, so any inline secrets enter the agent's context; grant this only to fully-trusted clients, and prefer !secret references (which ATM preserves) over inline values.

List and create backups. Restore is intentionally never exposed. Confirm-eligible.

Read and write files under www/, themes/, and custom_templates/. Confirm-eligible.

List integrations and enable or disable them. Confirm-eligible.

Edit an entity's registry metadata (friendly name, icon, area) or delete a stale/duplicate registry entry. Requires write access to the entity and cap_registry_write; Confirm-eligible and version-captured. Renaming the entity_id is not exposed; a deleted entry cannot be re-created through ATM.

params

set_entity: entity_id + one of name / icon / area_id; delete_entity: entity_id

Manage the Zigbee network (Zigbee2MQTT or ZHA, auto-detected). Open the pairing window for up to 254 seconds or close it with duration 0, re-interview a misbehaving device, or remove one from the network (re-pairing required to rejoin). Requires cap_radio_write; Confirm-eligible. Device-scoped writes need write access to at least one of the device's entities, and the coordinator can never be targeted.

params

permit_zigbee_join: duration (0-254, default 60), optional device_id (router) and backend; others: device_id

Restart Home Assistant. Pass-through-exempt: even pass-through tokens must have this flag enabled.

Field-by-field explanation of why an accessible entity resolved the way it did, including any conflicts between levels.

The MESA context for the current caller.

The stored and effective profile for one accessible entity. With include_semantic_moments: true, also the purpose-specific triggers and conditions the entity participates in (Home Assistant 2026.7+), read live from Home Assistant; informational only, and omitted on older versions.

List the profiles in scope, filterable by domain, tag (any or all), area, intent, and origin, with pagination. Tag and intent filters match the effective (resolved) profile. Counts and cursors are relative to the token's scope.

Announce a short operation on specific entities (up to 30 seconds) so MESA-aware components can coordinate. A lease is advice, not a lock, and grants no authority: every action stays gated by scope, capabilities, and MESA. Covers only entities the token could already control; entities under protected or critical automation control are denied. Lease endings fire an atm_mesa_lease_expired event.

Release a lease early when the work finishes ahead of its expiry. A token can only release its own leases.

Send an announcement through Assist satellite devices.

params

message (string, required)

Cancel all running timers in an area (or everywhere if area is omitted). Always returns speech_slots: { "canceled": N }, even when N is 0.

Set a climate device's target temperature.

params

temperature (required), plus area / floor / name

Set fan speed by percentage.

params

percentage (0-100, required), plus area / floor / name

Set brightness, color, or color temperature of accessible lights.

params

area, floor, name, brightness (0-100), color, temperature (kelvin)

Control playback on an accessible media player by area, floor, or name. Each gates on the player's current state before calling the service.

Search and play media on a player.

params

search_query (required), media_class, plus area / floor / name

Set the position of covers, blinds, or valves (0-100); each target is routed to its own domain service. Needs the physical-control capability.

Set or adjust media player volume. HassSetVolume takes volume_level (0-100); HassSetVolumeRelative takes volume_step ("up", "down", or a signed percentage).

Stop a moving cover or similar device.

Turn entities on or off by area, name, floor, or domain.

params

area, floor, name (strings), domain, device_class (string arrays), all optional

Historical state changes for an entity. Accepts relative times (24h, 7d, 2w, 1m). Ranges over 7 days are clamped. Returns entity_id, mode, count, and history (each entry's state and when); the REST proxy additionally returns the queried range in X-ATM-History-Start/End headers.

params

entity_id (required), start_time, end_time (ISO or relative)

Current state of a single entity. Returns a compact, domain-aware view by default (key attributes only); pass detailed=true for the full state, or fields=[...] to select exact fields. Requires READ or WRITE on the entity. Sensitive attributes are always scrubbed.

params

entity_id (string, required), fields (array, optional), detailed (boolean, optional)

returns

by default entity_id, state, and key attributes; the full state with detailed=true

All entity states the token can read, as a compact domain-aware view per entity by default (detailed=true or fields=[...] to change). Pass-through tokens receive every non-ATM entity.

Long-term statistics for numeric entities, aggregated by 5-minute, hour, day, week, or month.

params

entity_id (required), start_time, end_time, period

returns

min, max, mean, sum, state per period

Events from an accessible calendar.* entity within a time window (defaults to the next 7 days). Requires READ access to the calendar entity.

params

calendar_id (required), start_time (default now), end_time (default start + 7 days)

Current date, time, and timezone. Always available, no permission required.

YAML snapshot of accessible entity states, optimized for LLM context. Filtered by the token's permissions; pass-through tokens get the same output as the native server.

Bounded blocking subscription (max 30 seconds) that waits for an accessible entity to change state, then returns it.

Manage helpers (input_*, counter, timer). Confirm-eligible. Created helpers appear in the Helpers UI and persist in HA's storage collection, which HA flushes on a short (~10 second) debounce. A graceful restart (including restart_ha or the homeassistant.restart service) flushes the pending write first, so the helper survives; only an abrupt restart or crash within a few seconds of creation can lose it. If one is lost that way, you can restore it from the Changes tab, since the create was recorded in version history immediately.

Manage scenes. Confirm-eligible. Split configurations (!include and !include_dir_* layouts in configuration.yaml) are followed to the correct leaf file, the same include-graph handling as the automation tools.

List and manage Lovelace dashboards, and read or replace a dashboard's view/card layout. get_dashboard_config redacts out-of-scope entities; set_dashboard_config writes storage-mode dashboards and is versioned. Confirm-eligible. Note that a saved layout is display config, not automatic execution: a card action (for example a call-service tap action) runs under the viewing user's session when they click it, the same indirect control risk as authored automations, so a layout can reference entities outside the token's scope.

Call any Home Assistant service. device_id and area_id are flattened to an explicit entity list first; denied entities are silently dropped, and if all resolve to denied the call returns 403. Response data is scanned and inaccessible entity IDs are replaced with <redacted>. Physical-control and restart services need their capability flags.

params

domain and service (two separate fields, both required, e.g. light and turn_on), entity_id, device_id, area_id, service_data

Preview a service call without running it. Resolves and flattens targets, reports the MESA verdict per entity, and returns a single predicted_outcome of allowed, pending_approval, or denied, folding the capability gate and MESA together. Same parameter shape as call_service.

Check a Confirm-gated action you submitted. With an approval_id, returns its status and result; without one, lists all of this token's pending approvals, useful after a reconnect.

Block until one of your pending approvals resolves, instead of polling. Returns immediately if already resolved, otherwise waits server-side (up to a capped timeout) for a human to approve or reject, then returns the status and result; on timeout it returns still-pending so you can call again.

This token's own recent audit entries (request_id, time, method, resource, outcome), newest first, with an optional outcome filter.

This token's persona, effective capabilities, Confirm-gated capabilities, write scope, rate limits, and a tool-level gate map (tools.usable / tools.needs_approval / tools.unavailable).