Tools

Generic Tools

The cross-cutting helpers that aren't tied to a specific HA domain: search, history, dashboard, and more.

The tools in src/tools/ (sibling to src/tools/homeassistant/) cover cross-cutting concerns: searching for entities, fetching history, rendering a dashboard summary, managing the server’s state, and a few helpers for testing and automation config.

Discovery

search_entities

Full-text search across entity_id, name, and attributes. Returns up to N matches sorted by relevance.

{
  query: string;                // free-form: "kitchen", "motion", "light.living"
  limit?: number;               // default 25
  domain?: string;              // restrict to e.g. "light"
  include_disabled?: boolean;
}

Annotations: readOnlyHint: true, openWorldHint: true.

entity_state

Get the current state of one entity (or a list of entities). Cheaper than list_devices when you know the id.

{ entity_id: string | string[]; }

History and observability

history

Query the historical state of an entity over a time window. Wraps HA’s history service.

{
  entity_id: string | string[];
  start_time: string;           // ISO 8601
  end_time?: string;
  minimal_response?: boolean;
  significant_changes_only?: boolean;
}

error_log

Returns the last N log entries from the server. Useful for debugging “why is my AI host saying the tool failed?”.

{ level?: "error" | "warn" | "info" | "debug"; limit?: number; since?: string; }

Annotations: readOnlyHint: true.

sse_stats

Returns the count of active SSE/WS clients, the bytes sent, and the time-since-last-ping for each. Useful for verifying a stream is healthy.

{
}

Annotations: readOnlyHint: true.

Dashboards

dashboard

Returns a summary of the current state of your home: active lights, open covers, climate temperatures, motion sensors that have fired in the last hour, and any triggered automations.

{ sections?: ("lights"|"climate"|"covers"|"motion"|"automations")[]; }

If sections is omitted, returns everything. Annotations: readOnlyHint: true, openWorldHint: true.

Subscriptions

subscribe_events

Subscribes the calling connection to a stream of HA events. On the HTTP+WS entry point, the events are streamed to the client over the WebSocket. On STDIO, they’re emitted as JSON-RPC notifications.

{
  event_type?: string;          // e.g. "state_changed"; default = all
  entity_id?: string;           // filter to one entity
}

To unsubscribe, the client sends a notifications/cancelled JSON-RPC message with the subscription id returned by the initial call.

Universal control

control

The “I don’t know which domain this entity is in” tool. Accepts an arbitrary entity_id, looks up its domain, and dispatches to the right specialized control tool (light, switch, cover, lock, vacuum, …). Convenient when you’re scripting a bunch of generic entity_ids.

{
  entity_id: string;
  action: "turn_on" | "turn_off" | "toggle";
  // ... domain-specific extras are passed through:
  brightness?: number;
  position?: number;
  fan_speed?: string;
  // ...
}

This is the most flexible tool, but the specialized ones are more discoverable. Prefer control_light over control when you know the entity is a light.

Templates and automation config

template

Renders a Handlebars template against a context object. Useful for one-off computations and for the AI to format responses.

{
  template: string; // e.g. "There are {{count}} lights on."
  context: Record<string, unknown>;
}

Annotations: readOnlyHint: true, openWorldHint: false.

automation_config

Create, update, or delete an automation. The full HA automation schema is supported.

{
  action: "create" | "update" | "delete";
  automation_id?: string;       // required for update/delete
  config: AutomationConfig;
}

AutomationConfig is a Zod-validated mirror of HA’s automation schema. Annotations: destructiveHint: true.

System

addon

Manage Home Assistant add-ons (install, start, stop, restart, update, config).

{
  action: "list" | "info" | "install" | "start" | "stop" | "restart" | "update" | "uninstall" | "set_option" | "get_config";
  slug?: string;                // for everything except "list"
  // ... action-specific args
}

package

Manage HACS integrations and custom components.

{
  action: "list" | "install" | "uninstall" | "update";
  category: "integration" | "theme" | "python_script";
  name?: string;
}

Testing and development

example

A no-op tool that echoes its input back. Used to verify the end-to-end JSON-RPC pipeline is healthy.

{
  message: string;
}

Next