Provides comprehensive control over Home Assistant instances, including entity management, registry operations, automation debugging, and retrieval of historical statistics and system logs.
Supports monitoring and debugging of the MQTT integration within Home Assistant, enabling searches for related entities and access to integration-specific debug logs.
A complete rewrite of voska/hass-mcp — an MCP server for Home Assistant built for token efficiency, security hardening, and context flooding prevention. Thanks to Matt Voska for the original project.
Features:
24 tools covering entity control, registry management, statistics, logs, and automation debugging
CEL expression filtering for complex entity queries (e.g., "all battery sensors below 20%")
Entity registry management with safe two-phase delete
Long-term statistics with hourly/daily/weekly/monthly aggregation and date range support
Core journal log access with debug-level and integration filtering
Automation trace inspection for debugging failed runs
Configurable output formats (lean/compact/detailed)
Input validation, error sanitization, and context flooding prevention across all calls
Works with Claude Desktop, Claude Code, Cursor, and other MCP clients
Home Assistant instance with a Long-Lived Access Token
One of the following:
Docker (recommended)
Python 3.13+ and uv
Variable | Required | Description |
| Yes | Home Assistant URL (e.g., |
| Yes | Home Assistant Long-Lived Access Token |
| No | Set to |
| No | Timezone (e.g., |
docker pull rmaher001/hass-mcp-plus:latestVerify the server starts correctly:
docker run -i --rm \
-e HA_URL=http://homeassistant.local:8123 \
-e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
rmaher001/hass-mcp-plusNote: If Home Assistant is running on the same machine, use
http://host.docker.internal:8123(Docker Desktop on Mac/Windows) or add--network hostand usehttp://localhost:8123.
pip install hass-mcp-plusRun the server:
HA_URL=http://homeassistant.local:8123 HA_TOKEN=YOUR_LONG_LIVED_TOKEN uvx hass-mcp-plusRelated MCP server: hass-mcp-server
claude mcp add hass-mcp-plus \
-e HA_URL=http://homeassistant.local:8123 \
-e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
-- docker run -i --rm -e HA_URL -e HA_TOKEN rmaher001/hass-mcp-plusReplace YOUR_LONG_LIVED_TOKEN with your actual token and update HA_URL.
Open Claude Desktop → Settings → Developer → Edit Config
Add to claude_desktop_config.json:
Using Docker:
{
"mcpServers": {
"hass-mcp-plus": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"HA_URL",
"-e",
"HA_TOKEN",
"rmaher001/hass-mcp-plus"
],
"env": {
"HA_URL": "http://homeassistant.local:8123",
"HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
}
}
}
}Using uvx:
{
"mcpServers": {
"hass-mcp-plus": {
"command": "uvx",
"args": ["hass-mcp-plus"],
"env": {
"HA_URL": "http://homeassistant.local:8123",
"HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
}
}
}
}Replace YOUR_LONG_LIVED_TOKEN with your actual token and update HA_URL to match your Home Assistant instance
Save and restart Claude Desktop
Go to Cursor Settings → MCP → Add New MCP Server
Fill in the form:
Name: Hass-MCP-Plus
Type: command
Command:
docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN rmaher001/hass-mcp-plusReplace YOUR_LONG_LIVED_TOKEN with your actual token and update HA_URL
Click "Add" to save
Here are some examples of prompts you can use with Claude once Hass-MCP-Plus is set up:
"What's the current state of my living room lights?"
"Turn off all the lights in the kitchen"
"Find all battery sensors below 20%"
"Give me a summary of my climate entities"
"Show me the hourly temperature statistics for the last week"
"Why didn't my motion sensor automation fire last night?"
"List all unavailable or unknown entities"
"Disable the orphaned sensor that no longer exists"
"Show me the debug logs for the MQTT integration"
"Search for entities related to my living room"
Hass-MCP-Plus provides 24 tools for interacting with Home Assistant:
get_entity: Get the state of a specific entity with optional field filtering
entity_action: Perform actions on entities (turn on, off, toggle) with domain-specific parameters
list_entities: Get entities with domain filtering, search, and output format options (lean/compact/detailed)
search_entities: Search for entities matching a query string across IDs, names, and attributes
query_entities: Filter entities using CEL expressions with numeric comparisons and boolean logic
domain_summary: Get a summary of a domain's entities with state distribution and examples
system_overview: Get a comprehensive overview of the entire Home Assistant system
get_entity_registry: Get detailed registry entry for a single entity (platform, device, area, status)
list_entity_registry: List all registry entries with optional domain filter (for auditing and bulk management)
update_entity: Update entity properties — rename, change icon, assign area, disable/enable, hide/unhide
remove_entity: Remove an entity from the registry (requires explicit confirm=True flag)
list_automations: Get all automations with pagination support
list_automation_traces: Get recent execution traces for a specific automation
get_automation_trace: Get detailed trace for a specific automation run (trigger, conditions, actions, errors)
get_error_log: Get the Home Assistant error log with integration/level filtering
get_core_logs: Get core journal logs (DEBUG/INFO/WARNING/ERROR) with integration/pattern filtering
set_log_level: Set log level for any integration (enable debug logging, then read with get_core_logs)
get_history: Get raw state change history with automatic pagination and sampling
get_history_range: Get state changes for a specific date/time range with sampling strategies
get_statistics: Get aggregated statistics (mean, min, max) with configurable periods (5min/hour/day/week/month)
get_statistics_range: Get long-term statistics for any date range — the best tool for historical analysis
get_version: Get the Home Assistant version
call_service: Call any Home Assistant service (low-level API access)
restart_ha: Restart Home Assistant
uv run pytest tests/ -vCall any Home Assistant service directly (low-level API).
Args: domain: Service domain (e.g. 'light', 'automation') service: Service name (e.g. 'turn_on', 'reload') data: Service data (e.g. {'entity_id': 'light.x', 'brightness': 255})
Examples: call_service("light", "turn_on", {"entity_id": "light.x", "brightness": 255}) call_service("automation", "reload")
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | ||
| service | Yes | ||
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It fails to disclose side effects, error handling, return values, or any behavioral traits beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with a clear header and list of arguments with examples. No unnecessary text, though it could be slightly better structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the generic nature and lack of annotations/output schema, the description leaves significant gaps: no error info, return type, or usage constraints. Incomplete for a low-level API.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description provides clear examples for each parameter (domain, service, data), adding meaning that the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool calls any Home Assistant service directly as a low-level API. This distinguishes it from sibling tools that target specific domains or actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like entity_action. The description only implies it is low-level without explicit usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a summary of entities in a domain (counts, state distribution, examples).
Args: domain: Domain to summarize (e.g. 'light', 'switch', 'sensor') example_limit: Max examples per state (default: 3)
Examples: domain_summary("light") domain_summary("climate", example_limit=5)
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | ||
| example_limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not mention whether the tool is read-only, any side effects, or permissions needed. It only lists the output components, missing behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the purpose, and includes clear parameter explanations and examples in a well-structured format. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 simple params, no nested objects) and no output schema, the description adequately explains what the tool returns. However, it lacks details like return format or pagination, but that is acceptable for a simple summary tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains both parameters: 'domain' with example values and 'example_limit' with default and example usage, significantly beyond the schema's minimal type info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'entities in a domain', and specifies the summary includes counts, state distribution, and examples. This distinguishes it from sibling tools like 'get_entity' or 'list_entities'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when you need a domain overview), but does not explicitly state when not to use it or provide alternatives. No guidance on exclusions or comparison with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform an action on a Home Assistant entity (on, off, toggle).
Args: entity_id: Entity ID to control (e.g. 'light.living_room') action: 'on', 'off', or 'toggle' params: Additional service parameters (e.g. {"brightness": 255, "temperature": 22.5})
Domain-specific params: Lights: brightness (0-255), color_temp, rgb_color, transition, effect Covers: position (0-100), tilt_position Climate: temperature, target_temp_high, target_temp_low, hvac_mode Media players: source, volume_level (0-1)
Examples: entity_action("light.living_room", "on", {"brightness": 255}) entity_action("switch.garden_lights", "off")
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | ||
| action | Yes | ||
| params | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should fully disclose behavior. It states this is a mutation action but omits important traits like idempotency, error states (e.g., entity not found), or authentication needs. The agent is left to infer these.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear summary sentence, then parameters, then domain-specific hints, then examples. It is front-loaded with the core action. The domain list could be trimmed, but each section is useful. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should explain what the tool returns (e.g., success/failure, new state) and side effects. It does not, leaving a significant completeness gap. Examples show usage but not response. Agent cannot determine if the action succeeded or how to handle errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no descriptions in properties), so the description compensates well by explaining entity_id format, action values, and common domain-specific params for lights, covers, climate, and media players. Examples further clarify usage, adding significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Perform an action'), the resource ('Home Assistant entity'), and the specific actions (on, off, toggle). This distinguishes it from siblings like call_service (generic service calls) or get_entity (read-only), so purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for controlling entity state but does not explicitly differentiate from similar tools like call_service. No 'when-not-to-use' guidance or alternatives are mentioned, though the domain-specific hints indirectly help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed trace for a specific automation run (trigger, conditions, actions, errors).
Args: automation_id: Automation ID (e.g. 'motion_light') run_id: Run/trace ID from list_automation_traces domain: 'automation' or 'script' (default: 'automation')
Examples: get_automation_trace("motion_light", "1700000000.123456")
| Name | Required | Description | Default |
|---|---|---|---|
| automation_id | Yes | ||
| run_id | Yes | ||
| domain | No | automation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It discloses that the tool returns trace details (trigger, conditions, actions, errors), implying a read-only retrieval. It does not mention side effects, permissions, or potential errors, but the behavior is straightforward.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence stating purpose, a brief Args section, and one example. No redundant information. Front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers the tool's purpose, parameters, return content, and usage example. It lacks error handling or prerequisites but is sufficiently complete for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates well by explaining each parameter's purpose: automation_id with example, run_id as coming from list_automation_traces, and domain with default and allowed values. A usage example further clarifies parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'detailed trace for a specific automation run', including components like trigger, conditions, actions, errors. This distinguishes it from sibling tools like list_automation_traces which list runs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear retrieval context, noting that run_id comes from list_automation_traces. It includes a default domain and an example call. However, it does not explicitly state when not to use it or mention alternative tools beyond the implicit sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Home Assistant core logs (all levels) from the Supervisor journal, with fallback to error log.
Args: limit: Max records (1-200, default: 50) level: Filter: "DEBUG", "INFO", "WARNING", or "ERROR" integration: Filter by integration (e.g. "mqtt", "llmvision") pattern: Case-insensitive substring match on message since_minutes: Only logs from last N minutes lines: Journal lines to request (default: 500) truncate_traces: Truncate stacktraces to 3 lines (default: True)
Use set_log_level to enable DEBUG before reading debug logs; reset to WARNING after.
Examples: get_core_logs(level="DEBUG", integration="llmvision") get_core_logs(pattern="timeout", since_minutes=60)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| level | No | ||
| integration | No | ||
| pattern | No | ||
| since_minutes | No | ||
| lines | No | ||
| truncate_traces | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description fully carries behavioral disclosure. It describes reading from Supervisor journal, fallback to error log, and parameter behaviors like truncate_traces. No contradictions, and it gives sufficient detail for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with no wasted words: one line for purpose, a structured Args list, a usage tip, and two examples. Information is front-loaded, making it easy for an AI to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no output schema, no annotations), the description covers purpose, parameters, usage guidelines, and examples. While return format is not detailed, it's a log retrieval tool; the description provides enough context for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds substantial meaning: limit range (1-200), level values, integration example, pattern substring matching, since_minutes context, lines default, and truncate_traces default. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets Home Assistant core logs from the Supervisor journal with fallback to error log. The verb 'Get' and specific resource 'Home Assistant core logs' make the purpose unambiguous. It implicitly differentiates from sibling 'get_error_log' by mentioning fallback and all levels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use guidance: 'Use set_log_level to enable DEBUG before reading debug logs; reset to WARNING after' provides a clear prerequisite. Examples show typical usage patterns, helping the agent understand appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the state of a Home Assistant entity with optional field filtering.
Args: entity_id: Entity ID (e.g. 'light.living_room') fields: Fields to include (e.g. ['state', 'attr.brightness']) detailed: If True, returns all fields unfiltered
Examples: get_entity("light.living_room", fields=["state", "attr.brightness"])
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | ||
| fields | No | ||
| detailed | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description is the sole source of behavioral info. It explains the effect of parameters like detailed (returns all fields) and fields (filtering), but does not disclose error handling for invalid entity IDs or missing entities. Overall adequate for a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with 3 sentences plus an Args section and an example. It front-loads the purpose. The Args section is structured but could be slightly more streamlined. Still efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not explain the return structure beyond implied state and attributes. It covers basic usage for a 3-parameter tool but omits error cases and edge behaviors like handling null fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description adds significant value by explaining each parameter: entity_id with example, fields with format example, and detailed with clear behavior. The example further reinforces usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the state of a Home Assistant entity with optional field filtering,' which is a specific verb and resource. It distinguishes from sibling tools like list_entities or search_entities by focusing on a single entity, but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples and parameter explanations, implying usage for retrieving entity state with optional field selection. However, it does not compare with alternatives like list_entities or query_entities, leaving the when-to-use context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full entity registry entry (platform, config, device, disabled/hidden, area).
Args: entity_id: Entity ID to look up (e.g. 'light.living_room')
Examples: get_entity_registry("light.living_room")
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description carries the full burden. Description discloses the return fields but does not mention side effects, read-only nature, permissions, or error behavior (e.g., what if entity_id not found). The name 'get' implies idempotence, but no explicit behavioral traits beyond that. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two sentences plus one line of code example. No wasted words, every sentence adds value. Front-loaded with the main action and fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description is sufficient: explains what it returns and gives an example. However, it could mention the return format or that it retrieves the registry entry vs state. Lacks explicit mention of output structure, but schema coverage is 0% so some extra detail would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It adds meaning to the entity_id parameter by providing an example ('e.g. 'light.living_room') and stating the purpose 'Entity ID to look up'. However, it does not specify format constraints or where to find entity IDs. Adds value above the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get the full entity registry entry' and lists the fields (platform, config, device, disabled/hidden, area). It is specific about the resource (entity registry entry) and the action (get), distinguishing it from sibling tools like list_entity_registry (which lists multiple) and get_entity (which likely gets state).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides an example usage and context for when to use (to look up a single entity's registry details). It does not explicitly exclude alternatives or state when not to use, but the context of sibling tools implies appropriate usage. Lacks explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the Home Assistant error log (WebSocket API). Stacktraces truncated by default.
Args: limit: Max records (1-100, default: 50) integration: Filter by integration (e.g. "mqtt", "zwave") level: Filter by level: "ERROR" or "WARNING" since_minutes: Only errors from last N minutes truncate_traces: Truncate stacktraces to 3 lines (default: True)
Examples: get_error_log(integration="mqtt") get_error_log(level="ERROR", since_minutes=60)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| integration | No | ||
| level | No | ||
| since_minutes | No | ||
| truncate_traces | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: default stacktrace truncation and filter options. It is transparent about the truncate_traces parameter's effect, though it could mention that the tool is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: one introductory sentence, a clear parameter list, and two examples. No unnecessary text, well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All 5 parameters are explained with examples, but the description lacks details on the return format (e.g., fields in the log entries). Given no output schema, slightly more completions would be ideal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the schema: it explains each parameter's purpose, value range, and defaults (e.g., limit 1-100, level values 'ERROR' or 'WARNING'). The schema itself has no descriptions, making this essential.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the Home Assistant error log via WebSocket API, specifying a specific resource. It distinguishes from sibling tools like get_core_logs by focusing on errors and stacktraces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for usage via examples and parameter descriptions, but does not explicitly guide when to use this over alternatives like get_core_logs or set_log_level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get raw state changes for an entity. For aggregated trends, use get_statistics instead.
By default returns last N hours. Provide start_time to query a specific date range instead. Best for: exact state change timestamps, infrequently-changing entities (doors, switches), short time periods. NOT for: long ranges on frequently-updating sensors — use get_statistics.
Args: entity_id: Entity ID to get history for hours: Hours of history (default: 24). Ignored if start_time is provided. start_time: ISO 8601, date only, or 'yesterday'/'today'. If set, uses range mode instead of hours. end_time: End of range (default: 'now'). Only used with start_time. limit: Max records (1-500, default: 100) sample_strategy: 'recent' (default), 'first', or 'even' — how to sample if over limit minimal_response: Reduce response size in range mode (default: true)
Examples: get_history("binary_sensor.front_door") get_history("sensor.temperature", hours=1, limit=50) get_history("sensor.temp", start_time="2025-10-28T10:00:00Z", end_time="2025-10-28T11:00:00Z") get_history("light.living_room", start_time="yesterday", end_time="today")
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | ||
| hours | No | ||
| start_time | No | ||
| end_time | No | ||
| limit | No | ||
| sample_strategy | No | recent | |
| minimal_response | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains default behavior (last N hours), range mode with start_time, sampling strategies, and minimal response. It does not mention permissions or rate limits, but as a read-only operation, this is sufficient. No annotations were provided, so the description carries the full burden and does so adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose, usage guidelines, Args list, and examples. Every sentence adds value, and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what the tool does and its parameters well, but it lacks details about the return value structure. Without an output schema, the agent is left to infer the format of 'raw state changes.' Additionally, error cases and permissions are not mentioned. While the description is strong for a complex tool, this gap in output documentation reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds comprehensive parameter details: entity_id meaning, hours default and ignore condition, start_time accepted values, end_time default, limit constraints, sample_strategy options, and minimal_response purpose. Examples further clarify usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Get raw state changes for an entity,' which is a specific verb and resource. It also distinguishes itself from the sibling tool 'get_statistics' by mentioning that tool is for aggregated trends.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool (exact timestamps, infrequently-changing entities, short periods) and when not to (long ranges on frequently-updating sensors), directing users to 'get_statistics' as an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get aggregated statistics (mean/min/max) for an entity. Best tool for historical data — no token limits.
By default returns last N hours. Provide start_time to query a specific date range instead. Handles any range efficiently (days, months, years). If get_history hits token limits, use this tool with the same time range instead.
Args: entity_id: Entity ID to get statistics for hours: Hours of data (default: 24). Ignored if start_time is provided. start_time: ISO 8601, date only, or 'yesterday'/'today'. If set, uses range mode instead of hours. end_time: End of range (default: 'now'). Only used with start_time. period: Aggregation period (default: 'hour'): '5minute' (~12 points/hr), 'hour' (24/day), 'day' (monthly views), 'week' (quarterly), 'month' (yearly). Match period to time range.
Examples: get_statistics("sensor.temperature", hours=24, period="hour") get_statistics("sensor.power_usage", hours=168, period="day") get_statistics("sensor.temperature", start_time="2024-10-01", end_time="2024-10-31", period="day") get_statistics("sensor.humidity", start_time="yesterday", period="5minute")
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | ||
| hours | No | ||
| start_time | No | ||
| end_time | No | ||
| period | No | hour |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that it returns mean/min/max, handles any range efficiently, and details parameter interactions. However, it does not explicitly state the operation is read-only or mention any potential limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with paragraphs, bullet points, and examples. Every sentence adds value; purpose is front-loaded. No redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and no output schema, the description covers usage thoroughly, including parameter dependencies and examples. It lacks explicit output format details beyond mean/min/max, and error handling is not mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds extensive meaning for all 5 parameters, including default behaviors, special values like 'yesterday'/'today' for start_time, and resolution hints for period options. Examples further clarify usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get aggregated statistics (mean/min/max) for an entity' and distinguishes itself from sibling tools by noting it is the best tool for historical data with no token limits and suggesting use when get_history hits limits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use ('Best tool for historical data — no token limits'), when not to use (implicitly via alternative: 'If get_history hits token limits, use this tool'), and explains the two modes of operation (default hours vs. date range).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the Home Assistant version.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It does not state that the operation is read-only or non-destructive, nor does it disclose any potential side effects or permissions needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description is mostly complete. It could mention the expected return format (e.g., a string), but for a version tool, the scope is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema description coverage is 100%. The description adds no parameter meaning but does not need to; the baseline for 0-param tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('Home Assistant version'). It is specific and unambiguous, distinguishing it from sibling tools like 'get_entity' or 'get_error_log'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any context about prerequisites or expected results. The simplicity of the tool partially excuses this, but explicit context is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List automations with their IDs, entity IDs, state, and aliases.
Args: limit: Max automations to return (1-200, default: 50)
Examples: list_automations() list_automations(limit=200)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description does not disclose any behavioral traits beyond listing. No mention of side effects, auth requirements, rate limits, or performance implications. For a read-only list, some context on data freshness or pagination would help.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is short (two lines plus examples), front-loaded with purpose, and includes a clear args section. Could structure the examples better, but no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description covers the key return fields and parameter semantics. Lacks details on error handling or ordering, but low complexity justifies this score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides only default value (50) for 'limit'; description adds range (1-200) and example usage, supplying meaning beyond the schema. However, coverage is 0% overall, but the single param is well-documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List automations' and specifies the exact fields returned (IDs, entity IDs, state, aliases). Distinguishes from siblings like list_entities, which focus on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites or exclusions mentioned. Although the sibling tools are distinct, the description does not help the agent decide between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent execution traces for a specific automation.
Args: automation_id: Automation ID (e.g. 'motion_light' or 'automation.motion_light') domain: 'automation' or 'script' (default: 'automation') limit: Max traces to return (default: 10, max: 50)
Use run_id from results with get_automation_trace for full details.
Examples: list_automation_traces("motion_light") list_automation_traces("kitchen_lights", limit=5)
| Name | Required | Description | Default |
|---|---|---|---|
| automation_id | Yes | ||
| domain | No | automation | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It implies read-only behavior ('list') and provides constraints (limit max 50), but does not explicitly state non-destructiveness or other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear structure: purpose, parameter list, usage tip, examples. No superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description minimally provides enough to use the tool, referencing run_id for full details, but lacks description of the output structure (e.g., fields in each trace) which is important for a list tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description adds full meaning to all parameters: format hints for automation_id, default for domain, default and max for limit, and concrete examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists recent execution traces for a specific automation, with examples that distinguish it from the sibling get_automation_trace by mentioning the use of run_id for full details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (to list traces) and hints at a workflow with get_automation_trace, but does not explicitly state when not to use it or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Home Assistant entities with optional filtering.
Args: domain: Domain filter (e.g. 'light', 'switch', 'sensor') search_query: Search by name, id, or attributes (no wildcards) limit: Max entities to return (default: 100) fields: Specific fields to include per entity detailed: If True, returns all fields unfiltered compact: If True, returns only entity_id/state/friendly_name (overrides detailed/fields)
Examples: list_entities(domain="light") list_entities(search_query="kitchen", limit=20) list_entities(compact=True)
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | ||
| search_query | No | ||
| limit | No | ||
| fields | No | ||
| detailed | No | ||
| compact | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions parameters like 'limit' and 'compact' but does not describe performance characteristics, ordering, side effects (no mutations), or the default return format. Behavioral traits are inadequately disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear paragraph followed by an args list and examples. It is concise without redundant information, though it could be slightly more streamlined by merging the default note into the limit bullet.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all parameters and provides examples, but lacks information about the return format, error handling, or pagination behavior (though limit serves as a pagination control). Given the tool's complexity and absence of an output schema, some gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description explicitly explains all 6 parameters, including details like 'no wildcards' for search_query and the overriding behavior of compact over detailed/fields. The provided examples further clarify usage, adding significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List Home Assistant entities with optional filtering,' which is a specific verb and resource. However, it does not explicitly differentiate from similar sibling tools like 'search_entities' or 'query_entities', leaving some ambiguity about when to use this tool over alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples but lacks any guidance on when to use this tool versus alternatives such as 'search_entities' or 'query_entities'. No exclusions or context for appropriate usage are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List entity registry entries (platform, config, disabled/hidden, area). Not states — use list_entities for states.
Args: domain: Domain filter (e.g. 'light', 'sensor') limit: Max entries (default: 100, max: 5000)
Examples: list_entity_registry(domain="light") list_entity_registry(domain="sensor", limit=50)
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes the operation as listing registry entries, implying a read-only behavior, but does not explicitly state it is non-destructive or mention any auth requirements or rate limits. Adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: two-line purpose, then args, then examples. No fluff, front-loaded with key differentiator. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is simple with two parameters and no output schema, the description is complete: it tells what it returns (registry entries, not states), the parameters, and provides examples. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It explains 'domain' as a filter (e.g., 'light', 'sensor') and 'limit' with default (100) and max (5000), adding meaning beyond the schema's titles and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists entity registry entries (platform, config, disabled/hidden, area) and explicitly distinguishes from list_entities which lists states. The verb 'List' and the resource 'entity registry' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use this tool ('List entity registry entries') and when not to ('Not states — use list_entities for states'). Also mentions optional domain filter and limit parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query entities using CEL (Common Expression Language) expressions.
CEL context: entity_id (string), state (numeric if possible, else string), domain (string), attributes (dict).
Args: domain: Domain pre-filter (e.g. "sensor", "light") expression: CEL filter expression limit: Max entities (default: 50) lean: Minimal fields with domain-specific attrs (default: True) compact: Only entity_id/state/friendly_name (default: False)
CEL examples: domain="sensor", expression='state < 30 && attributes.device_class == "battery"' domain="light", expression='state == "on" && attributes.brightness < 50' expression='state == "unavailable" || state == "unknown"'
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | ||
| expression | No | ||
| limit | No | ||
| lean | No | ||
| compact | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must convey behavior. It implies read-only by 'Query entities', but does not explicitly state non-destructive nature, rate limits, or error handling. Acceptable for a query tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with bullet points for arguments and clear CEL examples, concise yet comprehensive, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description does not describe the return format or potential errors, leaving a gap in completeness for a tool with 5 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description carries full burden. It thoroughly explains all 5 parameters with defaults, purpose, and examples, adding significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it queries entities using CEL expressions, with explicit context variables and examples, distinguishing it from sibling tools like list_entities (simple listing) and search_entities (likely text search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use (complex filtering via CEL) and includes examples, but does not explicitly contrast with alternatives or give when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove an entity from the entity registry. Two-phase safety: preview first, then confirm.
By default returns a preview. Set confirm=True to actually delete. Entity may reappear if integration recreates it; consider disable instead.
Args: entity_id: Entity ID to remove (e.g. 'light.old_device') confirm: False=preview (default), True=permanently remove
Examples: remove_entity("light.orphaned_device") # preview remove_entity("light.orphaned_device", confirm=True) # delete
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | ||
| confirm | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the two-phase behavior, default preview, confirm flag effect, and potential reappearance, adding value beyond the input schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, front-loaded with purpose and safety note, then details and examples. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers purpose, usage, parameters, behavior, return info, and a caveat, fully equipping an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description explains both parameters with examples and default behavior, fully compensating for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool removes an entity from the registry and introduces two-phase safety (preview then confirm), distinguishing it from siblings like get_entity or update_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context on when to use (remove permanently), when to preview, and a caveat about entity reappearance suggesting an alternative (disable), though no sibling tool is named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restart Home Assistant. WARNING: Temporarily disrupts all operations.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It warns of temporary disruption to all operations, which is the key behavior for a restart. It lacks details like whether it is graceful or if state is preserved, but for a simple action, it is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences, front-loading the purpose and adding a critical warning. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description covers the essential purpose and a key behavioral warning. It could mention that the connection will be lost, but the warning implies this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (schema coverage 100%), so baseline is 4. The description correctly adds no parameter info, as none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Restart Home Assistant', which is a specific verb and resource. No other sibling tool performs a restart, so it is well-distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear warning about disrupting operations, implying when to use (when a restart is needed) and caution about consequences. However, it does not explicitly state when not to use or list alternatives, which would be helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for entities matching a query string across IDs, names, and attributes.
Args: query: Search term (no wildcards; empty string returns all entities) limit: Max results (default: 20)
Examples: search_entities("temperature") search_entities("living room", limit=10)
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key behaviors like no wildcards and empty query behavior, but omits details such as case sensitivity, exact match vs partial match, and return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise and uses a standard Args format with examples. However, it could be slightly more streamlined by merging the introductory sentence with the Args section.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not explain return values or result format. It sufficiently covers the two input parameters but lacks completeness for an agent to understand what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It explains each parameter clearly: query with constraints and limit with default value, plus examples for clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for entities across IDs, names, and attributes. However, it does not differentiate from sibling tools like 'list_entities' or 'query_entities', which may have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides usage guidelines such as no wildcards, empty string returns all, and a default limit. But lacks explicit guidance on when to use this tool versus similar sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the log level for a Home Assistant integration.
Args: integration: Integration name (e.g. "mqtt", "llmvision") level: "debug", "info", "warning", or "error" custom_component: If True, targets custom_components.X (for HACS integrations)
Examples: set_log_level("mqtt", "debug") set_log_level("llmvision", "debug", custom_component=True) set_log_level("mqtt", "warning") # reset to normal
| Name | Required | Description | Default |
|---|---|---|---|
| integration | Yes | ||
| level | Yes | ||
| custom_component | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose whether changes are persistent, require restart, or affect other parts of the system. Lacks behavioral context beyond the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very concise with two paragraphs plus examples. Every sentence adds value. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameters, and examples. Does not explain return values or error handling, but for a simple setter tool this is acceptable. Could mention integration validation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage, so description adds significant value by listing valid level values and explaining custom_component targeting custom_components.X. Provides examples showing usage patterns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Set the log level for a Home Assistant integration'. Examples further clarify the action. It distinguishes from siblings like get_core_logs or restart_ha by focusing on a specific logging control operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides examples and explains the custom_component parameter. It implicitly indicates when to use (debugging) but does not explicitly exclude alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a comprehensive overview of the Home Assistant system (domain counts, samples, areas).
Good first call when exploring an unfamiliar instance. Use domain_summary to drill deeper.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It implies a read operation ('overview') but does not explicitly state read-only, permissions, or side effects. However, it adequately describes the scope of data returned (domain counts, samples, areas), which is sufficient for a non-mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. The first sentence states purpose and resource, the second provides usage context. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description conveys the essential information: what the tool returns (domain counts, samples, areas) and when to use it (first call). This is complete for a simple overview tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is 100%. Baseline is 4; the description does not need to add parameter information, and it correctly omits any.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a 'comprehensive overview of the Home Assistant system (domain counts, samples, areas)' with a specific verb ('Get') and resource. It also distinguishes from siblings by suggesting 'Use domain_summary to drill deeper'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states it is a 'Good first call when exploring an unfamiliar instance' and provides an alternative tool for deeper exploration ('Use domain_summary to drill deeper'), giving clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update entity registry properties (name, icon, area, disable/enable, hide/unhide, rename).
For fields that can be cleared, pass "none" as the string value to set to null.
Args: entity_id: Entity ID to update name: Friendly name (or "none" to clear) icon: Icon (e.g. 'mdi:lamp', or "none" to clear) disabled_by: "user" to disable, "none" to re-enable hidden_by: "user" to hide, "none" to unhide area_id: Area ID (or "none" to remove) new_entity_id: Rename entity ID (e.g. 'light.new_name') options: Platform options dict
Examples: update_entity("sensor.old", disabled_by="user") update_entity("sensor.old", disabled_by="none") # re-enable update_entity("light.x", name="Living Room Lamp", area_id="kitchen")
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | ||
| name | No | ||
| icon | No | ||
| disabled_by | No | ||
| hidden_by | No | ||
| area_id | No | ||
| new_entity_id | No | ||
| options | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses all updatable fields and special behavior (clearing with 'none', rename, disable/enable, hide/unhide). However, it does not mention potential side effects, permissions, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose line, Args list, and examples. It is front-loaded but slightly lengthy; could be trimmed slightly without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no output schema, and no annotations, the description covers all necessary usage details. It includes examples and clearing conventions. Missing return value info, but acceptable without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description thoroughly explains each parameter in the Args section and provides examples, fully compensating for the schema's lack of parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: 'Update entity registry properties' and lists specific fields (name, icon, area, etc.), making it distinct from siblings like remove_entity or get_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides examples and explains how to clear fields with 'none', but does not explicitly state when to use this tool versus alternatives (e.g., when to use remove_entity instead). Usage context is implied but not definitive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose. Overlapping entity retrieval tools (get_entity, list_entities, search_entities, query_entities, get_entity_registry, list_entity_registry) are differentiated by focus and filtering. get_history and get_statistics clearly explain when to use each.
All tool names use snake_case consistently, following a verb_noun pattern (e.g., call_service, list_automations, get_automation_trace). No mixing of conventions or vague names.
22 tools is well-scoped for a Home Assistant MCP server, covering entity control, querying, history, automations, logs, and system management without being overwhelming or insufficient.
The tool surface covers core Home Assistant operations: entity CRUD, service calls, history/statistics, automation traces, logs, system overview, version, restart, and log level control. Obvious gaps like entity creation are intentionally out of scope.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
MCP server for building and testing AI agents with multi-model experimentation and insights.
A TypeScript MCP server for Home Assistant, enabling programmatic management of entities, automati…
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/rmaher001/hass-mcp-plus'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
