Skip to main content
Glama
homeassistant-ai

Home Assistant MCP Server

Official
by homeassistant-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Get Automation Traces

ha_get_automation_traces
Read-onlyIdempotent

Retrieve execution traces for Home Assistant automations and scripts to debug failures, inspect triggers, condition results, actions, errors, and runtime variables.

Instructions

Get execution traces for automations and scripts to debug issues.

Traces show what triggered a run, which conditions passed or failed, which actions executed (for 'choose', which branch was taken), any errors, and variable values during execution. Home Assistant keeps only the most recent runs of each automation or script (its stored_traces setting), so older runs are not available. The 'state' field shows 'stopped' (completed), 'running', or an error state.

USAGE MODES:

  1. List recent traces (omit run_id): returns a summary of recent runs with timestamps, triggers, and status. Use offset to page deeper when has_more is true. ha_get_automation_traces("automation.motion_light")

  2. Get a detailed trace (provide run_id): full execution details including trigger info, condition results, action trace with timing, and context variables. ha_get_automation_traces("automation.motion_light", run_id="1705312800.123456")

  3. Add logbook entries and context metadata: detailed=True. Script-style action paths (sequence/, numeric) are always matched regardless of this flag.

  4. Variables at every step (trigger sets and null entries are still omitted): deduplicate=False.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of traces to return when listing (default: 10, max: 50).
orderNoOrder traces are returned in. 'newest' returns most-recent first; 'oldest' returns chronological-first.newest
offsetNoNumber of traces to skip from the start of the requested order. Use with `limit` to page through stored traces when `total_available > limit`.
run_idNoSpecific trace run_id to retrieve detailed trace.
detailedNoInclude extra diagnostic data: logbook entries and context metadata.
sectionsNoComma-separated list of trace sections to return. Valid values: trigger, conditions, actions, config, error, logbook, context. Omit to return all sections. Example: 'actions' or 'trigger,conditions'.
deduplicateNoDeduplicate variables across action steps. Set to False to record the variables at every step; steps whose variables carry 'trigger', and null-valued entries, are omitted either way.
automation_idYesAutomation or script entity_id (e.g., 'automation.motion_light' or 'script.morning_routine')

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv8.6.0
    • changedInput schema / properties / deduplicate / description
      Previous value: -"Deduplicate variables across action steps (default: True). Set to False to include full variables at every step."New value: +"Deduplicate variables across action steps. Set to False to record the variables at every step; steps whose variables carry 'trigger', and null-valued entries, are omitted either way."
    • changedInput schema / properties / detailed / description
      Previous value: -"Include extra diagnostic data: logbook entries and context metadata (default: False). Use when standard trace lacks detail for debugging."New value: +"Include extra diagnostic data: logbook entries and context metadata."
    • changedInput schema / properties / order / description
      Previous value: -"Order traces are returned in. 'newest' (default) returns most-recent first; 'oldest' returns chronological-first."New value: +"Order traces are returned in. 'newest' returns most-recent first; 'oldest' returns chronological-first."
    • changedInput schema / properties / run_id / description
      Previous value: -"Specific trace run_id to retrieve detailed trace. Omit to list recent traces."New value: +"Specific trace run_id to retrieve detailed trace."
  2. First observedv7.14.2

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already cover the read-only/idempotent safety profile, and the description adds real behavioral context on top: traces are retained only for the most recent runs per the stored_traces setting, older runs are unavailable, list mode is paginated via offset/has_more, and 'state' values are defined ('stopped', 'running', or error). It also discloses that trigger-set variables and null entries are omitted regardless of deduplicate.

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?

Front-loaded with the purpose and the payload contents, then a scannable numbered mode list; length is justified by 8 parameters and three distinct call shapes. Minor redundancy: the deduplicate behavior is explained in both the description and the schema, and the retention note could sit closer to the list mode it constrains.

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

Completeness5/5

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

For an 8-parameter, read-only diagnostic tool with an output schema present, the description covers the remaining agent-facing unknowns: what is returned in each mode, retention limits, pagination, and section/flag semantics. An agent can choose the right mode and interpret results without further guessing.

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

Parameters4/5

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

Schema description coverage is 100%, so a 3 is the baseline, but the description adds operational meaning the schema lacks: worked examples of the automation_id and run_id formats, the offset-when-has_more paging rule, and the caveat that script-style action paths (sequence/, numeric) are always matched regardless of the detailed flag.

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?

States a specific verb and resource ('Get execution traces for automations and scripts') plus the goal ('to debug issues'), and enumerates exactly what a trace contains (trigger, condition results, action/branch, errors, variables). This is enough to separate it from config-oriented siblings like ha_config_get_automation and from log/history tools without opening a schema.

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

Usage Guidelines4/5

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

The numbered USAGE MODES give explicit conditional guidance: omit run_id to list vs. supply run_id for detail, use offset when has_more is true, detailed=True for logbook/context, deduplicate=False for per-step variables, with literal call examples. It never names an alternative tool (e.g., ha_get_logs or ha_get_history) for when traces are the wrong instrument, so it stops short of a 5.

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

Deploy Server

Other Tools