Hass-MCP is a Model Context Protocol server that connects AI assistants to Home Assistant, enabling natural language control, monitoring, and troubleshooting of smart home devices.
Entity Management
Query the current state of any entity (lights, sensors, switches, etc.)
Control devices: turn on/off, toggle, or set parameters (brightness, temperature, etc.)
List, search, and filter entities by domain, name, ID, or area
Get domain summaries with state distributions and common attributes
System Information
Full system overview: entity counts, domain breakdowns, and area distributions
Retrieve the current Home Assistant version
Automations & Services
List all automations and their states
Call any Home Assistant service directly for advanced/granular control
Restart the Home Assistant instance
History & Statistics
Retrieve entity state change history over a time period or explicit date range
Access long-term aggregated statistics (mean/min/max)
Fetch and filter error logs by level, integration, or search term for troubleshooting
Guided Conversation Prompts
Built-in prompts to assist with creating/debugging automations, troubleshooting entities, optimizing routines, auditing entity naming, and generating dashboard layouts
Offers deployment through Docker containers, making it easy to run the MCP server with proper environment configuration.
Enables querying and controlling Home Assistant entities (lights, switches, sensors), retrieving summaries of smart home devices, troubleshooting automations, searching for entities, and guiding through automation creation.
Supports native Python installation as an alternative to Docker deployment, with specific requirements for Python 3.13+ and uv.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Hass-MCP turn off the living room lights"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for Home Assistant integration with Claude and other LLMs.
Hass-MCP enables AI assistants like Claude to interact directly with your Home Assistant instance, allowing them to:
Query the state of devices and sensors
Control lights, switches, and other entities
Get summaries of your smart home
Troubleshoot automations and entities
Search for specific entities
Create guided conversations for common tasks
Related MCP server: Home Assistant MCP Server
Entity Management: Get states, control devices, and search for entities
Domain Summaries: Get high-level information about entity types
Automation Support: List and control automations
Guided Conversations: Use prompts for common tasks like creating automations
Smart Search: Find entities by name, type, or state
Live Dashboard Editing: Read and edit Lovelace dashboards (cards and views) over Home Assistant's WebSocket API — changes appear instantly in open browsers, with automatic backups and a dry-run preview
Token Efficiency: Lean JSON responses to minimize token usage
Home Assistant instance with Long-Lived Access Token
One of the following:
Docker (recommended)
Python 3.13+ and uv
Pull the Docker image:
docker pull voska/hass-mcp:latestAdd the MCP server to Claude Desktop:
a. Open Claude Desktop and go to Settings
b. Navigate to Developer > Edit Config
c. Add the following configuration to your claude_desktop_config.json file:
{
"mcpServers": {
"hass-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"HA_URL",
"-e",
"HA_TOKEN",
"voska/hass-mcp"
],
"env": {
"HA_URL": "http://homeassistant.local:8123",
"HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
}
}
}
}d. Replace YOUR_LONG_LIVED_TOKEN with your actual Home Assistant long-lived access token
e. Update the HA_URL:
If running Home Assistant on the same machine: use http://host.docker.internal:8123 (Docker Desktop on Mac/Windows)
If running Home Assistant on another machine: use the actual IP or hostname
f. Save the file and restart Claude Desktop
The "Hass-MCP" tool should now appear in your Claude Desktop tools menu
Note: If you're running Home Assistant in Docker on the same machine, you may need to add
--network hostto the Docker args for the container to access Home Assistant. Alternatively, use the IP address of your machine instead ofhost.docker.internal.
Install uv on your system.
Add the MCP server to Claude Desktop:
a. Open Claude Desktop and go to Settings
b. Navigate to Developer > Edit Config
c. Add the following configuration to your claude_desktop_config.json file:
{
"mcpServers": {
"hass-mcp": {
"command": "uvx",
"args": ["hass-mcp"],
"env": {
"HA_URL": "http://homeassistant.local:8123",
"HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
}
}
}
}d. Replace YOUR_LONG_LIVED_TOKEN with your actual Home Assistant long-lived access token
e. Update the HA_URL:
If running Home Assistant on the same machine: use http://host.docker.internal:8123 (Docker Desktop on Mac/Windows)
If running Home Assistant on another machine: use the actual IP or hostname
f. Save the file and restart Claude Desktop
The "Hass-MCP" tool should now appear in your Claude Desktop tools menu
Go to Cursor Settings > MCP > Add New MCP Server
Fill in the form:
Name: Hass-MCP
Type: command
Command:
docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcpReplace YOUR_LONG_LIVED_TOKEN with your actual Home Assistant token
Update the HA_URL to match your Home Assistant instance address
Click "Add" to save
To use with Claude Code CLI, you can add the MCP server directly using the mcp add command:
Using Docker (recommended):
claude mcp add hass-mcp -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcpReplace YOUR_LONG_LIVED_TOKEN with your actual Home Assistant token and update the HA_URL to match your Home Assistant instance address.
For deployments that can't use stdio — running behind an MCP gateway, hosting on Smithery, sharing one server across multiple clients, or connecting from network-based tools like LibreChat or OpenWebUI — Hass-MCP supports the MCP streamable HTTP transport. The server runs in stateless mode (no Mcp-Session-Id, JSON responses), suitable for horizontally-scaled hosts.
HTTP mode exposes full Home Assistant control over the network. Anyone who can reach the port can call any tool — turn off lights, unlock doors, trigger automations, restart HA. The MCP spec does not yet ship a built-in auth layer in this server. Until it does, you must put it behind one of:
A reverse proxy (nginx, Caddy, Traefik) doing basic-auth or bearer-token validation
A VPN or zero-trust network (Tailscale, WireGuard, Cloudflare Access)
Localhost binding only (the default — change --host only if you know what you're doing)
Do not expose :8000 to the open internet without auth.
Using uvx:
HA_URL=http://homeassistant.local:8123 \
HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
uvx hass-mcp --http --port 8000The server binds 127.0.0.1 by default. Override with --host 0.0.0.0 only when you've also configured auth in front of it.
docker run --rm -p 8000:8000 \
-e HA_URL=http://homeassistant.local:8123 \
-e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
voska/hass-mcp:latest --http --host 0.0.0.0 --port 8000--host 0.0.0.0 is required inside Docker so the port is reachable through the bridge. Bind the publish (-p) to 127.0.0.1:8000:8000 if you only want it reachable from the host, or put a reverse proxy in front.
The MCP endpoint is at /mcp. Point your client at http://<host>:<port>/mcp.
The server honors the PORT environment variable (Smithery's convention) in addition to MCP_PORT. Smithery deployment requires --http mode and reads PORT automatically.
If your Home Assistant instance serves a certificate signed by your own CA (step-ca, smallstep, homelab OpenSSL), hass-mcp can verify it without disabling TLS:
Locally: install the CA root in your OS trust store (macOS Keychain, Windows Cert Store, or update-ca-certificates on Linux). hass-mcp picks it up automatically via truststore.
In Docker (or any sandboxed runtime): bind-mount the CA file and point SSL_CERT_FILE at it.
docker run --rm \
-v /path/to/your-ca.crt:/etc/ssl/certs/your-ca.crt:ro \
-e SSL_CERT_FILE=/etc/ssl/certs/your-ca.crt \
-e HA_URL=https://homeassistant.example.internal:8123 \
-e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
voska/hass-mcp:latestSSL_CERT_FILE always takes precedence over the OS store when set. verify=False is intentionally not supported — use HA_URL=http://... if you genuinely want unencrypted local LAN traffic.
Here are some examples of prompts you can use with Claude once Hass-MCP is set up:
"What's the current state of my living room lights?"
"Turn off all the lights in the kitchen"
"What's the temperature in the master bedroom?"
"List everything in the guest room"
"List all my sensors that contain temperature data"
"Give me a summary of my climate entities"
"Create an automation that turns on the lights at sunset"
"Help me troubleshoot why my bedroom motion sensor automation isn't working"
"Search for entities related to my living room"
"Show me the last 50 ERROR lines from the Home Assistant log"
"What's been failing on the mqtt integration today?"
"Show me power usage by day for the last month"
"What happened with the front door sensor last Tuesday?"
Hass-MCP provides several tools for interacting with Home Assistant:
get_version: Get the Home Assistant version
get_entity: Get the state of a specific entity with optional field filtering
entity_action: Perform actions on entities (turn on, off, toggle)
list_entities: Get a list of entities with optional domain filtering and search
search_entities_tool: Search for entities matching a query
domain_summary_tool: Get a summary of a domain's entities
list_automations: Get a list of all automations
call_service_tool: Call any Home Assistant service
restart_ha: Restart Home Assistant
get_history: Get the state history of an entity (last N hours)
get_history_range: Get state-change history for an entity over an
explicit date/time range (start_time / end_time, ISO-8601)
get_statistics: Get long-term aggregated statistics (mean / min / max
per bucket) for an entity over the last N hours — works for data older
than the recorder's short-term retention window
get_statistics_range: Same, but for an explicit date/time range —
useful for monthly / yearly trend queries
get_error_log: Get the Home Assistant error log, with optional
level / integration / search_term / lines filters applied
server-side so noisy logs don't blow Claude's context
get_entities_by_area: List entities in a specific area / room
Read and live-edit dashboards over Home Assistant's WebSocket API. Saving pushes the change to every open browser instantly — no restart.
list_dashboards: List dashboards (the default plus any user dashboards),
each with its url_path and mode (storage / yaml)
get_dashboard_config: Get a dashboard's full config
set_dashboard_config: Replace a dashboard's full config (low-level)
add_card / update_card / remove_card / move_card: Edit cards within
a view (the view is selected by index, or by its path / title)
list_view_sections: List the sections of a "sections"-type view
add_view / remove_view / update_view: Edit a dashboard's views
list_dashboard_backups / restore_dashboard: List and roll back to the
automatic pre-save backups
Sections views: Home Assistant's modern view type (type: sections) stores
its cards inside sections rather than a single top-level list. For those views,
call list_view_sections and pass the section argument (index, title, or
heading) to the card tools. Card edits on a sections view without a section
are rejected with the list of available sections — rather than silently saving
a card where it would never render.
Every editing tool accepts dry_run=true to preview the resulting config and
a change summary without saving.
Important notes:
Admin token required. Saving Lovelace config requires the long-lived token to belong to an admin user.
Storage-mode only. Only UI-managed ("storage") dashboards can be edited. YAML-mode dashboards are detected and rejected with a clear message — edit their YAML files directly instead.
Whole-config writes. Home Assistant has no partial-edit API; every change is a read-modify-write of the entire dashboard. The high-level card/view tools handle this for you.
Automatic backups. Before each write, the current config is saved to
HASS_MCP_BACKUP_DIR (default ~/.hass-mcp/dashboard-backups/). When running
in Docker, mount a volume at this path or backups are lost when the
container is recreated.
Hass-MCP includes several prompts for guided conversations:
create_automation: Guide for creating Home Assistant automations based on trigger type
debug_automation: Troubleshooting help for automations that aren't working
troubleshoot_entity: Diagnose issues with entities
routine_optimizer: Analyze usage patterns and suggest optimized routines based on actual behavior
automation_health_check: Review all automations, find conflicts, redundancies, or improvement opportunities
entity_naming_consistency: Audit entity names and suggest standardization improvements
dashboard_layout_generator: Create optimized dashboards based on user preferences and usage patterns
Hass-MCP provides the following resource endpoints:
hass://entities/{entity_id}: Get the state of a specific entity
hass://entities/{entity_id}/detailed: Get detailed information about an entity with all attributes
hass://entities: List all Home Assistant entities grouped by domain
hass://entities/domain/{domain}: Get a list of entities for a specific domain
hass://search/{query}/{limit}: Search for entities matching a query with custom result limit
uv run pytest tests/Call any Home Assistant service (low-level API access)
Args: domain: The domain of the service (e.g., 'light', 'switch', 'automation') service: The service to call (e.g., 'turn_on', 'turn_off', 'toggle') data: Optional data to pass to the service (e.g., {'entity_id': 'light.living_room'})
Returns: A dictionary with success status, the domain/service called, and the list of affected entity states returned by Home Assistant.
Examples: domain='light', service='turn_on', data={'entity_id': 'light.x', 'brightness': 255} domain='automation', service='reload' domain='fan', service='set_percentage', data={'entity_id': 'fan.x', 'percentage': 50}
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| domain | Yes | ||
| service | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the return value and provides examples, but does not disclose potential side effects (e.g., destructive mutations), authentication needs, or error handling. Given no annotations, more transparency about the generic nature and risks would improve score.
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 separate sections for description, args, returns, and examples. It is moderately concise; the examples are useful and not overly verbose.
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 provides a good overview of purpose, parameters, return value, and examples. For a tool that calls arbitrary services, it covers the necessary context without requiring additional information from output schema or annotations.
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 compensates well by explaining each parameter (domain, service, data) and giving concrete examples. It adds meaning beyond the schema's title-only definitions.
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 'Call any Home Assistant service (low-level API access)' with specific verb and resource. It distinguishes from sibling tools like get_entity or list_entities which are higher-level or more specific operations.
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 as a low-level access for arbitrary service calls, but does not explicitly state when to use this tool versus alternatives. No exclusions or when-not-to-use guidance is provided.
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 specific domain
Args: domain: The domain to summarize (e.g., 'light', 'switch', 'sensor') example_limit: Maximum number of examples to include for each state
Returns: A dictionary containing: - total_count: Number of entities in the domain - state_distribution: Count of entities in each state - examples: Sample entities for each state - common_attributes: Most frequently occurring attributes
Examples: domain="light" - get light summary domain="climate", example_limit=5 - climate summary with more examples Best Practices: - Use this before retrieving all entities in a domain to understand what's available
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | ||
| example_limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It describes the tool as a read-summary operation with no side effects, and specifies the exact return structure (total_count, state_distribution, examples, common_attributes). No contradictions or missing critical behavioral details.
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 well-structured with a main sentence, Args, Returns, Examples, and Best Practices sections. Every section is informative and concise, 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 simple tool with 2 parameters and an output schema, the description fully covers input semantics, output structure, and usage guidance. No missing elements.
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, so description compensates by explaining 'domain' with examples and 'example_limit' with purpose and default context. The Args section adds meaning beyond type and default.
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 gets a summary of entities in a specific domain, using a specific verb and resource. It distinguishes from sibling tools like list_entities and get_entity by focusing on summary statistics.
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?
Includes a Best Practices section advising to use this before retrieving all entities, which provides clear context for when to use it. Does not explicitly contrast with sibling tools but implies an alternative.
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: The entity ID to control (e.g. 'light.living_room') action: The action to perform ('on', 'off', 'toggle') params: Optional dictionary of additional parameters for the service call
Returns: The response from Home Assistant
Examples: entity_id="light.living_room", action="on", params={"brightness": 255} entity_id="switch.garden_lights", action="off" entity_id="climate.living_room", action="on", params={"temperature": 22.5}
Domain-Specific Parameters: - 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)
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| params | No | ||
| entity_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses optional params and domain-specific details, but does not mention side effects, permissions, or async behavior. Adequate for basic actions.
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 clear sections, examples, and domain-specific info. Front-loaded purpose, no redundant sentences.
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 main actions, examples, and domain-specific params. Could mention error handling or constraints, but overall complete for typical 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?
Schema coverage is 0%, description compensates fully. Explains entity_id, action values, and provides extensive domain-specific parameter details (brightness, color_temp, etc.) for params.
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 verb 'Perform an action' and resource 'Home Assistant entity', with specific action values (on, off, toggle). Distinguishes from siblings like call_service_tool.
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 domain-specific parameters, giving strong implicit guidance. Does not explicitly state when not to use or compare to alternatives, but examples clarify typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all entities assigned to a specific Home Assistant area (room).
Area lookup is case-insensitive and matches the area's name as configured in Home Assistant (e.g., "Kitchen", "Living Room"). Entities inherit their area from their parent device when no area is set directly, matching HA's own resolution behavior.
Args: area: Name of the area to filter by (case-insensitive) domain: Optional domain to further filter results (e.g., 'light') lean: If True (default), returns token-efficient entity records
Returns: A dictionary containing: - area: The matched area name (as canonicalized by HA) - count: Number of matching entities - entities: List of entity records with their state and area
Examples: get_entities_by_area(area="Kitchen") - everything in the kitchen get_entities_by_area(area="Living Room", domain="light") - lights only
| Name | Required | Description | Default |
|---|---|---|---|
| area | Yes | ||
| lean | No | ||
| domain | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the burden of behavioral disclosure. It explains area resolution behavior (inheritance from parent device), case-insensitivity, and the lean parameter effect. The return structure is also described, providing good transparency.
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 mostly concise and front-loaded with the main purpose. It includes structured parameter explanations and examples, which are helpful but add length. Could be slightly tighter, but overall well-organized.
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 has 3 parameters, no annotations, and an output schema, the description covers all necessary aspects: area matching behavior, optional filtering, return dictionary structure, and usage examples. It is complete for an agent to correctly invoke the 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 0% description coverage, but the description explains all three parameters: area (mandatory, case-insensitive), domain (optional filter), and lean (default true, token-efficient). This adds significant meaning beyond the schema types and defaults.
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 gets all entities assigned to a specific Home Assistant area (room). It specifies the verb 'get', the resource 'entities by area', and distinguishes from siblings like 'list_entities' and 'search_entities_tool' by focusing on area-based filtering.
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 usage context with examples and explains the case-insensitive area lookup. It implicitly tells when to use this tool (filter by area) but does not explicitly mention when not to use it or suggest alternatives like search_entities_tool for name-based search.
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: The entity ID to get (e.g. 'light.living_room') fields: Optional list of fields to include (e.g. ['state', 'attr.brightness']) detailed: If True, returns all entity fields without filtering
Examples: entity_id="light.living_room" - basic state check entity_id="light.living_room", fields=["state", "attr.brightness"] - specific fields entity_id="light.living_room", detailed=True - all details
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | ||
| detailed | No | ||
| entity_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It describes the operation as getting state with optional filtering, but does not mention that it is read-only, nor any permissions or side effects. Adequate but not exhaustive.
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 sentence followed by args and examples. It is slightly verbose but each part 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 no output schema, the description does not explicitly describe the return value format. However, it implies the state is returned, and for a simple get tool this is mostly complete. Could be improved by stating return structure.
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%, yet the description provides detailed docstring for each parameter (entity_id, fields, detailed) and examples. This adds significant value 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 'Get the state of a Home Assistant entity with optional field filtering', using a specific verb and resource. This distinguishes it from sibling tools like call_service_tool or domain_summary_tool.
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 args, but does not explicitly state when to use this tool versus alternatives like get_history or list_entities. Implicit guidance is present, but no explicit differentiation.
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 for troubleshooting.
All filters are optional and combine (AND semantics). Stats (error_count, warning_count, integration_mentions, total_lines) are computed over the filtered output so they match what's returned.
Args:
level: Filter to lines containing this log level — ERROR, WARNING,
INFO, or DEBUG. Case-insensitive.
integration: Filter to lines mentioning this integration. Matches
[name] or [homeassistant.components.name].
Case-insensitive.
search_term: Case-insensitive substring filter applied per line.
Useful for entity IDs, exception names, etc.
lines: Return only the most recent N lines (applied after other
filters). Useful when you only care about the tail.
Returns: A dictionary containing: - log_text: The (possibly filtered) error log text - error_count: Number of ERROR entries in the filtered output - warning_count: Number of WARNING entries in the filtered output - integration_mentions: Map of integration names to mention counts - total_lines: Number of lines in the filtered output - filters_applied: Map of which filter args were supplied - error: Error message if retrieval failed
Examples: get_error_log() # full log get_error_log(level="ERROR") # errors only get_error_log(integration="zwave_js") # one integration get_error_log(search_term="light.kitchen") # specific entity get_error_log(level="ERROR", lines=50) # last 50 errors
Best Practices:
- Filter on the server side (here) rather than pulling the full
log into Claude's context — saves tokens on noisy logs.
- Combine integration + level="ERROR" to triage a single
integration that's misbehaving.
- Use lines to bound output when scanning a long-running HA.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | ||
| lines | No | ||
| integration | No | ||
| search_term | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations exist, the description fully describes behavior: filters combine with AND, stats are computed over filtered output, case-insensitive matching for level, integration, search_term. Return structure is detailed. No side effects mentioned but tool is read-only. Could mention error conditions more broadly.
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 Args, Returns, Examples, Best Practices. Purpose is front-loaded. Slightly lengthy but all sections are informative and earn their 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?
Covers purpose, all parameters, return format, usage guidance, and examples. No gaps given the tool's complexity and presence of output schema in description.
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, so description provides all semantics: level specifies exact values, integration matching pattern, search_term as substring, lines for tail. Examples demonstrate usage. Completely compensates for schema lack.
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 the Home Assistant error log for troubleshooting. It specifies the action ('get') and resource ('error log') and distinguishes itself from sibling tools like get_entity or call_service_tool.
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?
Best practices are provided, such as filtering server-side to save tokens and combining integration with level='ERROR'. The AND semantics of filters are explained. However, no explicit when-not-to-use or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the history of an entity's state changes
Args: entity_id: The entity ID to get history for hours: Number of hours of history to retrieve (default: 24)
Returns: A dictionary containing: - entity_id: The entity ID requested - states: List of state objects with timestamps - count: Number of state changes found - first_changed: Timestamp of earliest state change - last_changed: Timestamp of most recent state change
Examples: entity_id="light.living_room" - get 24h history entity_id="sensor.temperature", hours=168 - get 7 day history Best Practices: - Keep hours reasonable (24-72) for token efficiency - Use for entities with discrete state changes rather than continuously changing sensors - Consider the state distribution rather than every individual state
| Name | Required | Description | Default |
|---|---|---|---|
| hours | No | ||
| entity_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It details output structure, parameter semantics, and includes caution about usage. No mention of destructive effects or auth, but appropriate for a read-only history 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?
Well-structured: purpose, args, returns, examples, best practices. Front-loaded with action, no wasted sentences. 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?
Complete for a history retrieval tool: covers input, output, usage recommendations, and efficiency. Output schema exists but description already details return fields, making it self-sufficient.
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 each parameter clearly: entity_id as target, hours with default and example. Examples add practical 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 'Get the history of an entity's state changes', specifying the precise verb and resource. It distinguishes from sibling get_history_range by using hours-based retrieval.
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 best practices on hour limits, ideal use cases (discrete state changes), and data interpretation. Does not explicitly exclude alternatives or mention get_history_range, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get raw state-change history for an entity over a date/time range.
Like get_history, but takes an explicit window instead of "N hours
from now". Useful for inspecting what happened on a specific day or
correlating with an external event.
Args:
entity_id: The entity to fetch history for.
start_time: ISO-8601 start (e.g. 2026-05-15 or
2026-05-15T08:00:00Z). Treated as UTC if no offset.
end_time: ISO-8601 end. Defaults to now (UTC).
Returns:
Same shape as get_history: entity_id, states, count,
first_changed, last_changed.
Examples: get_history_range("light.kitchen", "2026-05-15") get_history_range("sensor.power", "2026-05-15T00:00:00Z", "2026-05-16T00:00:00Z")
Best Practices:
- Bound the window — wider ranges return more data and more tokens.
- For aggregated long-term data, prefer get_statistics_range.
| Name | Required | Description | Default |
|---|---|---|---|
| end_time | No | ||
| entity_id | Yes | ||
| start_time | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description mentions that the tool returns 'raw state-change history' and warns about token usage, but it does not explicitly disclose behavioral traits such as mutation risk, authentication needs, rate limits, or data freshness. The description adds some value beyond annotations (which are absent) but is not comprehensive.
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 front-loaded with the purpose, followed by comparisons, parameter explanations, return shape, examples, and best practices. It is structured and each section adds value. However, it is slightly verbose with repeated ISO-8601 details; could be more concise without losing clarity.
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 that the tool has an output schema (true) and the description references the return shape ('Same shape as get_history: entity_id, states, count, first_changed, last_changed'), the description is sufficiently complete. It covers parameters, usage, alternatives, and examples. It is well-rounded for a history 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?
The input schema has 0% description coverage, so the description must explain parameters. It does so thoroughly: entity_id is 'the entity to fetch history for', start_time includes format 'ISO-8601 start' with examples and note about UTC, and end_time is 'ISO-8601 end. Defaults to now (UTC).' This adds 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 tool's purpose: 'Get raw state-change history for an entity over a date/time range.' It specifies the verb (Get), the resource (raw state-change history), and the scope (over a date/time range). The description also distinguishes itself from the sibling tool `get_history` by noting that `get_history_range` takes an explicit window instead of 'N hours from now', which helps the agent differentiate between the two.
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 explicit usage context: 'Useful for inspecting what happened on a specific day or correlating with an external event.' It also includes best practices: 'Bound the window — wider ranges return more data and more tokens. For aggregated long-term data, prefer get_statistics_range.' This gives clear guidance on when to use this tool and when to use an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get long-term aggregated statistics for an entity over the last N hours.
Uses HA's recorder statistics (over WebSocket) — aggregated buckets
(mean / min / max per period) that survive the short-term retention
window. Use this instead of get_history when:
- You want data older than the recorder's default 10-day window.
- You want aggregated values rather than every individual change.
- The entity is a high-frequency sensor (temperature, power) and
raw history would be too many tokens.
Args:
entity_id: The entity (must have a state_class HA records as
statistics — measurement, total, total_increasing).
hours: How far back from now. Defaults to 24.
period: Bucket size — 5minute, hour, day, week, month.
Defaults to hour.
Returns:
entity_id, period, start_time, end_time, statistics
(list of {start, end, mean, min, max, ...} points).
Examples: get_statistics("sensor.power_usage", hours=168, period="day") get_statistics("sensor.temperature", hours=24)
| Name | Required | Description | Default |
|---|---|---|---|
| hours | No | ||
| period | No | hour | |
| entity_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes that it uses HA's recorder statistics and returns aggregated buckets (mean/min/max). Discloses that it survives short-term retention window. Does not explicitly state read-only nature, but purpose implies no modification. No annotations to contradict.
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 yet informative. Front-loaded with main purpose, then structured bullet points for usage, Args, Returns, Examples. Every sentence adds value. No unnecessary repetition.
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 output schema exists, the description still provides a summary of return structure (entity_id, period, start_time, end_time, statistics). Covers all needed context: what it does, when to use, parameters, and returns. 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 has 0% description coverage, but the description compensates by explaining each parameter: entity_id requires a state_class, hours defaults to 24, period with allowed bucket sizes. Provides examples. Adds meaning beyond 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?
Clearly states it gets long-term aggregated statistics for an entity over the last N hours. Distinguishes from sibling get_history by specifying use cases for older data or aggregated values. Includes examples and mentions HA recorder statistics.
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 three conditions when to use instead of get_history: for data older than 10-day window, for aggregated values, and for high-frequency sensors. Also implies when not to use (short-term or raw history).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get long-term aggregated statistics for an entity over a date/time range.
Same data source as get_statistics, but with an explicit window —
useful for "what was my power usage from Jan 1 to Jan 31?" type
questions. Aggregated bucket data survives the short-term retention
window, so this works for data months/years old.
Args:
entity_id: The entity (must be statistics-tracked).
start_time: ISO-8601 start (2026-01-01 or
2026-01-01T00:00:00Z). UTC if no offset.
end_time: ISO-8601 end. Defaults to now.
period: 5minute, hour, day, week, or month.
Returns:
entity_id, period, start_time, end_time, statistics.
Examples: get_statistics_range("sensor.energy", "2026-01-01", "2026-02-01", period="day") get_statistics_range("sensor.temperature", "2026-05-01", period="hour")
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | hour | |
| end_time | No | ||
| entity_id | Yes | ||
| start_time | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that it uses aggregated bucket data that survives the short-term retention window, indicating behavior for old data. It doesn't mention idempotency or rate limits, but the read-only nature is clear from context and sibling names.
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 Args, Returns, and Examples sections. Each sentence adds value, though the description is slightly longer than minimal. The examples are particularly helpful.
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 4 parameters, no annotations, and an output schema existing, the description covers all parameter semantics, return structure, and retention behavior. Examples complete the picture, making the tool's usage fully understandable.
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, yet the description explains all four parameters in detail: entity_id (must be statistics-tracked), start_time (ISO-8601), end_time (ISO-8601, defaults to now), and period (enum of five values). 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?
Description clearly states 'Get long-term aggregated statistics for an entity over a date/time range' with a specific verb and resource. It distinguishes itself from the sibling tool `get_statistics` by emphasizing the explicit date window and retention behavior.
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 mentions 'Same data source as get_statistics, but with an explicit window' and provides a concrete use case example ('what was my power usage from Jan 1 to Jan 31?'). Also explains that it works for older data due to retention, helping the agent choose correctly.
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
Returns: A string with the Home Assistant version (e.g., "2025.3.0")
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses behavior: returns a string version. It is read-only and non-destructive, which is clear from context. Example output is given.
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 short: two sentences. Front-loaded with purpose. No unnecessary words. 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 no parameters and a simple return value (string), the description is complete. Output schema exists, and description provides an example. No missing information.
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?
No parameters exist, so schema coverage is 100%. Description doesn't need to add parameter info; baseline of 4 for zero parameters.
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 Home Assistant version', using a specific verb and resource. It distinguishes itself from sibling tools which are action-oriented or entity-related.
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?
While no explicit when-not or alternatives are given, the purpose is so straightforward that usage context is implicit. The tool is for retrieving version info, distinct from other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of all automations from Home Assistant
This function retrieves all automations configured in Home Assistant, including their IDs, entity IDs, state, and display names.
Returns: A list of automation dictionaries, each containing id, entity_id, state, and alias (friendly name) fields.
Examples: Returns all automation objects with state and friendly names
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool returns a list of automation dictionaries with specific fields, but does not mention any potential side effects, permissions, or limitations. It provides basic behavioral context but not comprehensive transparency.
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 fairly concise and front-loaded, but includes a Returns section and example that partially repeat information. It earns its place with clear structure, though minor redundancy exists.
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, output schema exists), the description covers the basic functionality and return format adequately. It is complete enough for an agent to understand the tool's purpose and output.
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?
Input schema has zero parameters; baseline is 4. Description does not add parameter information as there are none, but this is consistent and sufficient.
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 a list of all automations' with a specific verb and resource. It distinctly identifies the tool's purpose, and among siblings like list_entities, it uniquely addresses automations.
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 explicit instructions on when or when not to use this tool versus alternatives. While the tool is simple and self-explanatory, the description lacks guidance on context or prerequisites, making it adequate but not proactive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of Home Assistant entities with optional filtering
Args: domain: Optional domain to filter by (e.g., 'light', 'switch', 'sensor') search_query: Optional search term to filter entities by name, id, or attributes (Note: Does not support wildcards. To get all entities, leave this empty) limit: Maximum number of entities to return (default: 100) fields: Optional list of specific fields to include in each entity detailed: If True, returns all entity fields without filtering
Returns: A list of entity dictionaries with lean formatting by default
Examples: domain="light" - get all lights search_query="kitchen", limit=20 - search entities domain="sensor", detailed=True - full sensor details
Best Practices: - Use lean format (default) for most operations - Prefer domain filtering over no filtering - For domain overviews, use domain_summary_tool instead of list_entities - Only request detailed=True when necessary for full attribute inspection - To get all entity types/domains, use list_entities without a domain filter, then extract domains from entity_ids
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| domain | No | ||
| fields | No | ||
| detailed | No | ||
| search_query | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses that search_query doesn't support wildcards, defaults (limit=100), and that returning 'lean formatting' by default vs detailed. But it doesn't mention pagination behavior, potential errors, or output structure beyond 'entity dictionaries'. The disclosure is adequate but not thorough.
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 structured into Args, Returns, Examples, and Best Practices sections. It is front-loaded with the core purpose. While somewhat lengthy, every section provides valuable information without being excessively verbose. It could be slightly streamlined but is well-organized.
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 presence of an output schema (not provided), the description adequately covers return format and usage scenarios. It includes best practices and comparisons to an alternative tool. It addresses all 5 parameters and provides examples. However, it doesn't mention pagination or maximum limits for the limit parameter, leaving minor 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%, but the description's 'Args' section explains each parameter with details (e.g., 'Does not support wildcards' for search_query, default values, types). It adds significant meaning beyond the schema's type/default-only information, though it could be more concise for some parameters.
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 a list of Home Assistant entities with optional filtering', specifying both the verb and resource. It mentions an alternative (domain_summary_tool) for domain overviews, providing some sibling differentiation. However, it does not explicitly distinguish from other similar siblings like search_entities_tool or get_entities_by_area, so it loses a point for full differentiation.
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 includes a 'Best Practices' section that advises when to use this tool vs domain_summary_tool, and provides guidance on preferring domain filtering and using lean format. It also tells how to get all entities by leaving the search query empty. However, it doesn't cover all sibling tools (e.g., search_entities_tool) so it's not fully comprehensive.
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 Home Assistant operations
Returns: Result of restart operation
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly warns that it 'Temporarily disrupts all Home Assistant operations,' providing critical behavioral insight. With no annotations, this disclosure is valuable, though it could mention authentication 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 extremely concise with only three lines, front-loading the purpose and warning. Every sentence adds value, making it 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?
Despite its brevity, the description covers the core purpose and the main behavioral warning. An output schema exists, so return details are likely covered there. Some might want more detail about the disruption nature, but overall it's adequate for a simple 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?
No parameters exist, so the baseline score is 4. The description adds no parameter details, which is acceptable since none are 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', specifying the exact verb and resource. It is distinct from siblings like get_version or get_error_log, which have different purposes.
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. The description lacks context about prerequisites, expected outcomes, or situations where restart is appropriate.
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
Args: query: The search query to match against entity IDs, names, and attributes. (Note: Does not support wildcards. To get all entities, leave this blank or use list_entities tool) limit: Maximum number of results to return (default: 20)
Returns: A dictionary containing search results and metadata: - count: Total number of matching entities found - results: List of matching entities with essential information - domains: Map of domains with counts (e.g. {"light": 3, "sensor": 2})
Examples: query="temperature" - find temperature entities query="living room", limit=10 - find living room entities query="", limit=500 - list all entity types
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the return structure (count, results, domains), states the search scope (IDs, names, attributes), and mentions the lack of wildcard support. It does not reveal case-sensitivity or pagination, but overall provides adequate behavioral transparency for a read-only search 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-structured with clear sections (Args, Returns, Examples) and uses concise language. It is appropriately sized for the information conveyed, though minor redundancy exists in examples. Overall efficient and scannable.
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 presence of an output schema, the description provides complete coverage of parameters and return structure. It addresses the query behavior and limits, and notes a key limitation (no wildcards). It lacks details on matching semantics (exact vs partial) and ordering, but is sufficient for typical 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?
The schema description coverage is 0%, so the description fully compensates. It adds detailed meaning for both parameters: query explanation includes matching scope and wildcard limitation with alternative, and limit explains its purpose and default value. This significantly aids correct parameter 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 the tool searches for entities matching a query string. It differentiates from the sibling tool list_entities by explicitly noting that to get all entities, one can leave query blank or use list_entities. This distinguishes from other entity-related tools.
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 on when to use the tool, specifically when a query string is available. It gives an alternative (list_entities) for listing all entities and notes that wildcards are not supported. Examples illustrate common use cases, but it does not explicitly exclude other scenarios or compare with other search-oriented siblings like get_entities_by_area.
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 entire Home Assistant system
Returns: A dictionary containing: - total_entities: Total count of all entities - domains: Dictionary of domains with their entity counts and state distributions - domain_samples: Representative sample entities for each domain (2-3 per domain) - domain_attributes: Common attributes for each domain - area_distribution: Entities grouped by area (if available)
Examples: Returns domain counts, sample entities, and common attributes Best Practices: - Use this as the first call when exploring an unfamiliar Home Assistant instance - Perfect for building context about the structure of the smart home - After getting an overview, use domain_summary_tool to dig deeper into specific domains
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It implies a read-only operation via 'Get' and the return of data without mentioning side effects, which is sufficient but could explicitly state no system modification.
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 well-structured with a clear purpose, return structure, examples, and best practices. All sections are concise and front-loaded, wasting no 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 zero parameters, an existing output schema, and a simple read operation, the description fully covers the tool's purpose, return structure, and usage context. No 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?
Tool has zero parameters and 100% schema coverage. The description appropriately omits parameter details, adding no extra burden. Baseline is 3 but the absence of parameters means the description is optimal.
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 a comprehensive overview of the entire Home Assistant system', using a specific verb and resource. It distinguishes itself from siblings like domain_summary_tool by positioning itself as a high-level overview.
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?
Best Practices explicitly say to use this as the first call for unfamiliar instances and to follow up with domain_summary_tool for deeper dives. This provides clear when-to-use and alternative guidance.
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. Entity action vs call_service are differentiated by abstraction level. Query tools (get_entity, list_entities, search, domain_summary) serve different scopes. History and statistics tools are clearly separated for raw vs aggregated data and relative vs absolute time ranges.
Most tools follow a consistent snake_case verb_noun pattern (e.g., get_entity, list_entities, search_entities_tool). Exceptions like 'entity_action' and 'domain_summary_tool' deviate from the predominant pattern, causing minor inconsistency.
With 16 tools, the server covers a broad but focused set of capabilities for Home Assistant: entity control, querying, history, statistics, system management, and error logs. The count is well-proportioned—neither sparse nor bloated.
The tool set covers primary Home Assistant workflows: entity control, state retrieval, history/statistics, automation listing, and system operations. Minor gaps exist, such as no tools for creating or modifying automations/scripts, but the core monitoring and control use cases are well supported.
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…
A Model Context Protocol server for Wix AI tools
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/voska/hass-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
