---
url: https://devitek.github.io/mcp-ha/reference/tools.md
---
# Tool reference

19 tools, prefixed `ha_`. All read tools carry the `readOnlyHint` annotation. Responses are compact JSON with a standard list envelope:

```json
{ "items": [...], "returned": 50, "total": 734, "has_more": true, "next_offset": 50, "note": "..." }
```

## Entities

### ha\_search\_entities

Fuzzy search by name, entity\_id or area. The natural entry point.

| Param | Type | Notes |
|-------|------|-------|
| `query` | string, required | e.g. `kitchen light` |
| `limit` | number | default 20, max 50 |

### ha\_list\_entities

Paginated list. **Called without any filter, it returns a histogram** (counts per domain and per area) instead of a dump.

| Param | Type | Notes |
|-------|------|-------|
| `domain` | string | e.g. `light`, `sensor`, `automation` |
| `area` | string | area name, case insensitive |
| `search` | string | fuzzy filter |
| `state` | string | exact state, e.g. `on` |
| `limit` / `offset` | number | default 50, max 200 |

### ha\_get\_entity

Full state and attributes of one entity (long attribute values truncated).

| Param | Type |
|-------|------|
| `entity_id` | string, required |

### ha\_list\_areas

All areas with their entity counts. No parameters.

### ha\_list\_devices

Devices with manufacturer, model, area. Params: `area`, `limit`, `offset`.

## Services

### ha\_list\_services

Without parameters: domains and their service counts. With `domain`: detailed services and fields. With `search`: cross-domain lookup.

### ha\_call\_service 

Only registered when `allow_write` is enabled. Subject to the [write rules](/guide/configuration#write-rules).

| Param | Type | Notes |
|-------|------|-------|
| `domain` / `service` | string, required | e.g. `light` / `turn_on` |
| `target` | object | `entity_id`, `device_id`, `area_id` (prefer `entity_id`) |
| `data` | object | service data, e.g. `{ "brightness_pct": 50 }` |
| `dry_run` | boolean | preview without executing |
| `confirm_token` | string | token from a `confirmation_required` answer (sensitive domains) |
| `return_response` | boolean | for services that return data |

On domains listed in `confirm_domains` (locks and alarms by default), the first call answers `confirmation_required` with a single-use `confirm_token` bound to that exact call; execute by calling again with the same arguments plus the token.

### ha\_run\_script 

Runs a script, optionally with variables. Same guarded path as `ha_call_service`.

| Param | Type | Notes |
|-------|------|-------|
| `entity_id` | string, required | must be a `script.*` entity |
| `variables` | object | passed to the script |
| `dry_run` / `confirm_token` | | as in `ha_call_service` |

### ha\_trigger\_automation 

Triggers an automation now. `skip_condition` defaults to `true` (actions run even if conditions do not hold).

| Param | Type | Notes |
|-------|------|-------|
| `entity_id` | string, required | must be an `automation.*` entity |
| `skip_condition` | boolean | default `true` |
| `dry_run` / `confirm_token` | | as in `ha_call_service` |

### ha\_set\_automation 

Enables or disables an automation.

| Param | Type | Notes |
|-------|------|-------|
| `entity_id` | string, required | must be an `automation.*` entity |
| `enabled` | boolean, required | `true` to enable |
| `dry_run` / `confirm_token` | | as in `ha_call_service` |

## Automations and scripts

### ha\_list\_automations

entity\_id, name, enabled, last\_triggered. Params: `limit`, `offset`.

### ha\_get\_automation

State plus, for UI-created automations, the full configuration (triggers, conditions, actions). YAML-defined automations return their state with a note.

### ha\_list\_scripts

entity\_id, name, running, last\_triggered. Params: `limit`, `offset`.

## History

### ha\_get\_history

State changes of one entity. Window: `hours` (min 0.25, default 24, max 168) or `start`/`end` ISO 8601. The first point is the state already in effect at window start; more than 250 points are downsampled with a note.

### ha\_get\_statistics

Recorder aggregates (mean, min, max, sum) for numeric sensors. `statistic_id` (string or list up to 10), `period` among `5minute`, `hour`, `day`, `week`, `month`, window up to one year. Prefer this over `ha_get_history` for long ranges.

### ha\_get\_logbook

Human-readable events, filterable by `entity_id`, window from 0.25 h up to 7 days, capped at 100 events.

## Add-ons and system

### ha\_get\_addons

Without `slug`: list of installed add-ons. With `slug`: details of one. Read only. Requires the Supervisor (unavailable in dev mode).

### ha\_render\_template

Evaluates a Jinja2 template server-side and returns the rendering. Read only, very powerful for computed queries. Not registered when `filter_reads` is enabled (a template can read any entity):

```
{{ states.light | selectattr('state','eq','on') | list | count }}
```

### ha\_get\_system

`section: "config"`: HA version, name, timezone, units, integration count. `section: "error_log"`: last 100 lines of the HA error log.