Home Assistant MCP Server

Overview Schema Source Related Servers Discussions Admin

Explain why something changed

explain_state_change

Read-onlyIdempotent

Explains why a Home Assistant entity changed by reading the logbook and reporting the cause of each recent change: automation or script, user action, service call, or the device itself.

Instructions

Why did this entity change? Reads the logbook and reports, for each recent change, what caused it: an automation or script (with the id to pass to get_automation_trace), a user or service call, or the device itself.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "entity_id": "<entity_id>"
    },
    "name": "explain_state_change"
  }
}

Input Schema

Name	Required	Description	Default
`hours`	No
`limit`	No
`entity_id`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.1Nov 5, 2026

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this a read-only, idempotent, non-destructive operation, and the description adds real substance beyond that: it reads the logbook, buckets causes into three categories, and returns an automation id for get_automation_trace. It does not disclose cost, rate limits, or what happens when no attributable cause exists, so it falls short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences, front-loaded with the motivating question followed immediately by what is returned and how to act on it. No filler, though the rhetorical opening costs a few words before the concrete verb 'Reads' appears.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter read tool with no output schema, the causal-bucketing behavior and the hand-off to get_automation_trace are well covered. What is missing is the temporal scope and result-count semantics, which an agent needs to interpret a sparse or empty answer correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden for entity_id, hours, and limit. It only vaguely gestures at scope with the word 'recent' and never mentions the time window, result cap, or accepted entity identifier format; the defaults (6 hours, 15 results) and bounds live only in the schema with no explanation of how to tune them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('explain') and resource ('state change') and states exactly what the tool returns: for each recent change, the cause (automation/script, user/service call, or the device itself). By framing output as causal attribution rather than raw entries, it is distinguishable from siblings like get_logbook and get_history without opening their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the opening question ('Why did this entity change?'), which signals a diagnostic scenario, and it points forward to get_automation_trace for follow-up. However, it never states when to prefer this over get_logbook or get_history, nor any prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.