Loading ToolBench
AI Agent API for Home Assistant - enables AI assistants (Cursor AI, VS Code + Copilot) to manage HA configuration
The server provides 25 tools with adequate naming conventions and reasonable descriptions, but exhibits significant gaps in schema completeness, parameter documentation, and error handling guidance. Tool names follow verb_noun patterns well (list_*, get_*, create_*, etc.), but input schemas are inconsistently documented. Many parameters lack type information in the visible source code. Descriptions are present but often generic, lacking actionable guidance for LLM selection and error recovery. Output schemas are undocumented. Risk annotations exist (READ_ONLY, WRITE, DESTRUCTIVE) but are not formalized in schema. The server sits in the 'fair to poor' range, functional but requiring significant refinement for production agent use.
Call a Home Assistant service. Examples: Set number value, Turn on light, Set climate temperature.
Create new automation via Home Assistant API. After creation, the automation state is exported to Git for versioning. Automations can be created regardless of file structure (packages, UI, etc.).
Create backup (Git commit) of current state. If message is provided, commits immediately with that message. If message is None and git_versioning_auto=false, returns suggested commit message. If message is None and git_versioning_auto=true, commits with auto-generated message.
Create checkpoint with tag at the start of user request processing. Saves current state with a commit, creates a tag with timestamp and user request description, and disables auto-commits during request processing.
Delete automation by ID via Home Assistant API. Works for automations from any source (files, packages, UI). After deletion, the automation state is exported to Git for versioning.
Missing input schemas for most tools. Source code shows parameter descriptions (slug, lines, etc.) but no visible JSON Schema definitions with types, required fields, or constraints. This violates the pattern:constrained-input pattern and prevents LLMs from understanding valid input ranges, enums, or required vs optional parameters.
No documented output schemas. Tools return data but descriptions do not specify the structure, field types, or available fields. LLMs cannot infer what fields to expect, making it impossible to plan downstream tool calls or extract needed data. This violates pattern:response-shaper.
Insufficient error handling guidance. Tool descriptions mention when operations are destructive (uninstall_addon, delete_automation, rollback_to_commit) but do not provide recovery guidance or error classification. A failed operation does not tell the LLM whether to retry, ask the user, or abort. This violates pattern:recovery-guide and pattern:error-classification.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 57 | <=2025-11-25 | v2 |
| 2026-03-09 | D | 51 | - | v1 |
End request processing - re-enable auto-commits. This should be called at the end of user request processing.
Get detailed information about a specific add-on. Returns detailed information including Name, description, version, Installation status, Configuration options, State (started/stopped), Resource usage.
Get add-on logs. Returns plain text logs.
Get complete instructions for AI assistants (like Cursor AI). Instructions are loaded from markdown files. Provides safety protocols, step-by-step workflow, best practices, error handling guidelines, and dashboard generation guides. Returns plain text for easy consumption by AI.
Get configuration for a single automation from Home Assistant (via API). Works for automations from any source (automations.yaml, packages/*.yaml, or UI-created).
Get diff between commits or current changes. Examples: /api/backup/diff - Current uncommitted changes, /api/backup/diff?commit1=a1b2c3d4 - Changes since commit, /api/backup/diff?commit1=a1b2c3d4&commit2=e5f6g7h8 - Between two commits.
Get specific entity state.
Get backup history (Git commits). Returns list of commits with details.
Install an add-on. Installation can take several minutes depending on add-on size. The endpoint will wait for installation to complete.
List all automations from Home Assistant (via API). Returns ALL automations that HA has loaded, regardless of source: From automations.yaml, From packages/*.yaml files, Created via UI (stored in .storage). Supports ids_only parameter for optimized retrieval.
List all available add-ons (installed and available to install). Returns add-ons from all repositories including Official add-ons (core, community), Custom repository add-ons, and Installation status for each.
Get entities with optional filters, pagination and lightweight modes. Designed to be LLM-friendly for installations with many entities by supporting filtering, pagination and lightweight formats to avoid overloading the model context.
List only installed add-ons. Returns add-ons that are currently installed on the system.
Get all available Home Assistant services. Returns complete list of services with descriptions.
List ALL add-ons from add-on store (full catalog). Returns complete catalog of add-ons from all connected repositories. Use this for browsing available add-ons and making recommendations.
Rename an entity.
Rollback configuration to specific commit. If the commit contains exported automations/scripts (export/automations/*.yaml, export/scripts/*.yaml), they will be restored via Home Assistant API. Regular files (automations.yaml, scripts.yaml, packages/*) will be restored as files (for backwards compatibility with old commits). Warning: This will overwrite current configuration!
Start an add-on.
Uninstall an add-on. Warning: This will remove the add-on and its data!
Update existing automation via Home Assistant REST API. Home Assistant automatically updates the automation in its original location. After update, the automation state is exported to Git for versioning.
Parameter descriptions lack granular constraints. Parameters like 'slug', 'lines', 'limit', 'page', 'page_size' are described but do not state min/max bounds, regex patterns, or enum values. For example, 'lines' defaults to 100 but no max is specified; 'page_size' caps at 500 but this is only mentioned in one tool description, not all. This violates pattern:constrained-input.
Ambiguous parameter naming in complex tools. create_automation and update_automation both accept 'trigger', 'condition', 'action' as arrays, but descriptions do not specify the expected structure of trigger objects, condition objects, or action objects. LLMs must infer or guess, inviting invalid payloads. This violates pattern:tool-description.
No tool annotations for idempotency or safety. Risk labels (READ_ONLY, WRITE, DESTRUCTIVE) are provided in the list but are not formalized as JSON Schema annotations (readOnlyHint, destructiveHint, idempotentHint per MCP spec 2026-07-28). LLMs cannot rely on these attributes for planning. This violates Spec Alignment for tool annotations.
Missing pagination metadata. list_entities supports pagination (page, page_size) but does not specify whether the response includes total_count, next_cursor, or has_more flags. Without these, LLMs cannot determine if more results exist or how to continue iteration. This violates pattern:paginated-result.
Undocumented parameter dependencies. update_automation requires both 'automation_id' (path) and 'id' (body), with a note that they 'must match'. This dependency is not enforced by the schema and is easy to miss, leading to invalid requests. This violates review:param-relationships.