← Back to Home Assistant toolkit docs

Home Assistant toolkit — Tool Reference

Read selected Home Assistant entities and control allowed lights and switches through its outbound Toolforest integration. Does not automatically expose an existing Apple Home configuration.

4 tools · auto-generated from the deployed toolkit

Your AI assistant discovers and invokes these tools through the MCP Server's meta tools — it calls execute_tool with the tool name and arguments below.

# control_entity write

Turn an explicitly allowed Home Assistant light or switch on/off.

Full description 
Set an exposed light or switch on/off through Home Assistant's native API.

The entity and action must both be explicitly enabled in integration options.
Brightness requires separate permission and capability support. No arbitrary
service dispatch, toggle, scenes, scripts, locks, alarms, garages or cameras.
Controls are never retried automatically; after a timeout or disconnect,
read current state before deciding whether to repeat the request. The reply
reports the state observed after the service call, not physical confirmation.
Parameter Type Required Description
instance_id string Yes Paired Home Assistant instance_id returned by list_instances.
entity_id string Yes Exposed light or switch entity_id returned by list_entities.
action "turn_on" | "turn_off" Yes Explicit target state; no toggle.
brightness integer | null No Optional light brightness (1–255) on turn_on, if supported and separately allowed. Use turn_off to turn a light off.
Parameter schema (JSON) 
{
  "additionalProperties": false,
  "properties": {
    "instance_id": {
      "description": "Paired Home Assistant instance_id returned by list_instances.",
      "maxLength": 64,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Instance Id",
      "type": "string"
    },
    "entity_id": {
      "description": "Exposed light or switch entity_id returned by list_entities.",
      "maxLength": 255,
      "pattern": "^(light|switch)\\.[a-z0-9_]+$",
      "title": "Entity Id",
      "type": "string"
    },
    "action": {
      "description": "Explicit target state; no toggle.",
      "enum": [
        "turn_on",
        "turn_off"
      ],
      "title": "Action",
      "type": "string"
    },
    "brightness": {
      "anyOf": [
        {
          "maximum": 255,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional light brightness (1–255) on turn_on, if supported and separately allowed. Use turn_off to turn a light off.",
      "title": "Brightness"
    }
  },
  "required": [
    "instance_id",
    "entity_id",
    "action"
  ],
  "title": "Control",
  "type": "object"
}
Result schema (JSON) 
{
  "properties": {
    "data": {
      "additionalProperties": true,
      "description": "Current instance-scoped response from Home Assistant.",
      "title": "Data",
      "type": "object"
    }
  },
  "required": [
    "data"
  ],
  "title": "Result",
  "type": "object"
}

# get_entity_state read

Read the current state of an explicitly exposed Home Assistant light or switch.

Full description 
Read a selected light or switch's current state, brightness and allowed actions.

Fails closed for entities outside the integration's exposure selection.
Direct Apple Home/HomeKit configurations are not automatically exposed.
Parameter Type Required Description
instance_id string Yes Paired Home Assistant instance_id returned by list_instances.
entity_id string Yes Exposed light or switch entity_id returned by list_entities.
Parameter schema (JSON) 
{
  "additionalProperties": false,
  "properties": {
    "instance_id": {
      "description": "Paired Home Assistant instance_id returned by list_instances.",
      "maxLength": 64,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Instance Id",
      "type": "string"
    },
    "entity_id": {
      "description": "Exposed light or switch entity_id returned by list_entities.",
      "maxLength": 255,
      "pattern": "^(light|switch)\\.[a-z0-9_]+$",
      "title": "Entity Id",
      "type": "string"
    }
  },
  "required": [
    "instance_id",
    "entity_id"
  ],
  "title": "Entity",
  "type": "object"
}
Result schema (JSON) 
{
  "properties": {
    "data": {
      "additionalProperties": true,
      "description": "Current instance-scoped response from Home Assistant.",
      "title": "Data",
      "type": "object"
    }
  },
  "required": [
    "data"
  ],
  "title": "Result",
  "type": "object"
}

# list_entities read

List explicitly exposed lights and switches in one Home Assistant instance.

Full description 
List a page of exposed lights and switches with their state and allowed actions.

Requires an online, paired instance. Inventory is filtered inside Home
Assistant and sorted by entity_id before applying offset/limit. Only entity
IDs, state, allowed actions and brightness-related fields are returned.
Parameter Type Required Description
instance_id string Yes Paired Home Assistant instance_id returned by list_instances.
offset integer No Offset into sorted exposed entities. Default: 0
limit integer No Maximum exposed entities to return. Default: 50
Parameter schema (JSON) 
{
  "additionalProperties": false,
  "properties": {
    "instance_id": {
      "description": "Paired Home Assistant instance_id returned by list_instances.",
      "maxLength": 64,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Instance Id",
      "type": "string"
    },
    "offset": {
      "default": 0,
      "description": "Offset into sorted exposed entities.",
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    },
    "limit": {
      "default": 50,
      "description": "Maximum exposed entities to return.",
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "required": [
    "instance_id"
  ],
  "title": "ListEntities",
  "type": "object"
}
Result schema (JSON) 
{
  "properties": {
    "data": {
      "additionalProperties": true,
      "description": "Current instance-scoped response from Home Assistant.",
      "title": "Data",
      "type": "object"
    }
  },
  "required": [
    "data"
  ],
  "title": "Result",
  "type": "object"
}

# list_instances read

List Home Assistant instances paired with your Toolforest account.

Full description 
List paired Home Assistant instances belonging to the authenticated account.

Includes offline instances. Use instance_id to scope every subsequent call.

No parameters.

Parameter schema (JSON) 
{
  "additionalProperties": false,
  "properties": {},
  "title": "Empty",
  "type": "object"
}
Result schema (JSON) 
{
  "properties": {
    "data": {
      "additionalProperties": true,
      "description": "Current instance-scoped response from Home Assistant.",
      "title": "Data",
      "type": "object"
    }
  },
  "required": [
    "data"
  ],
  "title": "Result",
  "type": "object"
}