Home Assistant MCP Server
OfficialServer Quality Checklist
Latest release: v8.2.0
- Disambiguation4/5
Despite 78 tools covering overlapping domains like automations, scripts, scenes, helpers, and dashboards, each tool has a clearly distinct purpose aided by consistent naming (e.g., ha_config_* for configuration, ha_manage_* for management) and detailed descriptions. Some pairs like ha_config_get_scene and ha_get_scene could cause minor confusion, but overall ambiguity is low.
Naming Consistency5/5All tools follow a strict ha_<verb>_<noun> pattern with optional config_ sub-prefix for configuration tools. Verbs like get, set, remove, manage, call, search are used consistently across domains. No mixing of conventions (e.g., no camelCase or inconsistent verb styles).
Tool Count3/578 tools is high but arguably justified for the vast Home Assistant domain covering automations, scripts, scenes, helpers, dashboards, entities, devices, integrations, updates, backups, energy, HACS, cameras, calendars, zones, labels, categories, templates, pipelines, radios, and more. However, the count pushes the upper bound of what is manageable, and some tools could potentially be consolidated (e.g., multiple set tools for different entity types).
Completeness5/5The tool surface is remarkably comprehensive, covering nearly every major Home Assistant feature: state, services, automations, scripts, scenes, helpers, dashboards, devices, entities, integrations, updates, backups, energy, HACS, calendars, cameras, zones, labels, categories, templates, pipelines, radios, and more. The inclusion of less common features like energy preferences and radio management makes this exceptionally complete.
Average 4.6/5 across 78 of 78 tools scored. Lowest: 2.3/5.
See the Tool Scores section below for per-tool breakdowns.
- 270 of 270 community issues answered or closed in the last 6 months
- 924 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set destructiveHint=true, so the destructive nature is known. The description adds 'WebSocket tracking' but doesn't explain behavioral traits like whether operations are atomic or rollback behavior. With annotations present, the description adds minimal context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is too brief. It lacks structure and fails to provide necessary details, sacrificing completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description omits critical info about parameters and behaviors. For a destructive tool with nested input schema, it should explain how to form operations and the effect of parallel execution.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 2 parameters with 0% description coverage. The description does not explain the 'operations' array or 'parallel' boolean. This leaves the agent unable to construct valid inputs without external knowledge.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states it 'controls multiple devices' with bulk and WebSocket tracking, which gives a general idea but doesn't specify device types or supported operations. It's not a tautology, but lacks specificity to distinguish from sibling tools like ha_set_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 (e.g., individual entity control). No mention of prerequisites or scenarios where bulk control is appropriate or not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral details: pagination via 'one page' and 'total_count'/'has_more', preview for inline resources to save tokens, and summary fields. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences) with the main purpose in the first sentence. Every sentence provides essential information without redundancy. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 covers key return fields (total_count, has_more, inline_count, by_type) and explains inline resource behavior. It is sufficient for an agent to use the tool correctly, though it does not detail every field in the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description enhances parameter understanding by explaining the practical effect of 'include_content' (preview vs. full content to save tokens), adding context not in the schema. This adds meaningful value beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Lovelace dashboard resources and specifies types (custom cards, themes, CSS/JS). It is distinct from sibling list tools like ha_config_list_helpers, but lacks explicit differentiation. However, the purpose is unambiguous and well-communicated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (listing registered resources) but does not provide explicit when-to-use or when-not-to-use guidance. It does not mention alternatives like ha_config_set_dashboard_resource or ha_config_delete_dashboard_resource, leaving the agent to infer appropriate contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description adds key behavioral details: that empty strings clear nullable fields, that make_preferred requires an extra websocket call, and it shows creation is based on cloning. This enriches the agent's understanding beyond the annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, action list, and commented examples. It is not overly verbose given the tool's complexity (16 parameters), but it 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high parameter count and existence of an output schema, the description covers the main use cases, including special behaviors like clearing fields and cloning. It does not repeat output schema details, which is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds slight extra context (e.g., nullable field clearing) but does not significantly expand on the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages Home Assistant Assist pipelines and lists five distinct actions (list, get, create, update, set_preferred). This specific verb+resource combination distinguishes it from sibling tools like ha_get_entity or ha_manage_addon.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples for each action, showing how to use the tool in practice. However, it does not explicitly state when not to use this tool or compare it to alternatives among siblings, leaving the agent to infer the scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveness, and the description adds the return value behavior and a warning about permanent deletion. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear front-loaded purpose, followed by return value explanation, examples, and warning. No unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deletion tool with annotations and output schema, the description covers purpose, return behavior, examples, and warning. Could mention error handling or prerequisites but is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers both parameters fully, so baseline is 3. The description adds explanation of the return value depending on identifier but does not elaborate on the 'wait' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a Home Assistant automation, with specific verb and resource. It distinguishes from sibling tools by targeting automations specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for deleting automations and provides examples, but does not explicitly state when to use this vs other removal tools, nor any prerequisites or 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and idempotent behavior. Description adds critical context: the tool fails with 405 for YAML scenes and may cause automation failures if referenced. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with examples, an important limitation section, and a warning. Each element adds value, though the description could be slightly tighter without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description adequately covers purpose, limitations, and caveats. It addresses the key behavioral aspects and constraints, making it sufficiently complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description does not add new meaning beyond what the schema provides, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Delete a Home Assistant scene.' This is a clear verb+resource pair. It distinguishes the tool's scope (scenes) from sibling tools that remove other entities, though it doesn't explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: only UI-created scenes can be deleted; YAML-defined scenes require editing configuration. Also warns about references in automations/scripts causing failures. This clearly tells the agent when to use and 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals the tool can create or update, implying mutation. This aligns with the destructiveHint=true annotation. It adds context about domain scoping and update behavior (providing category_id updates). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: summary, explanation, and examples. It is front-loaded with the core purpose and is not overly verbose. The examples add length but are helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 does not need to explain return values. It covers creation vs update, scoping, and provides examples for typical use cases. It also references a related tool (ha_set_entity) for assigning categories, making it complete for the user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema handles basic meaning. The description adds value through examples that clarify usage of icon and category_id, and emphasizes the create/update distinction. While schema already describes each parameter, the examples provide practical context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates or updates a Home Assistant category, specifying the resource (category) and action (create/update). It distinguishes from labels by noting categories are domain-scoped, but does not explicitly differentiate from sibling tools like ha_config_get_category or ha_config_remove_category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the tool: create new (no category_id) or update existing (with category_id). It includes examples for each case and references ha_set_entity for assigning categories. However, it does not explicitly state when not to use it or mention alternatives beyond the label comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, covering safety and idempotency. The description adds useful context: it uses the WebSocket 'calendar/event/delete' command, returns success status and confirmation, and clarifies that delete is only available via WebSocket. This supplements the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear title, short purpose statement, detailed parameter list, example usage, a note on prerequisite, and return value. Every sentence serves a purpose, and the format is easy to scan. It is appropriately sized for a tool with 4 parameters and an output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, 2 required, output schema exists), the description covers the essential workflow: obtaining the UID, using required and optional parameters, and understanding the return. It could benefit from mentioning error handling or permission requirements, but overall it is sufficiently complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so baseline is 3. The description repeats parameter descriptions exactly as in the schema and includes examples demonstrating usage. While examples are helpful, they do not add new semantic information beyond what the schema already provides (e.g., recurrence_range values are already documented).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an event from a calendar', using a specific verb and resource. It distinguishes itself from sibling tools like ha_config_get_calendar_events (get events) and ha_config_set_calendar_event (set/create event) by explicitly focusing on deletion. The mention of the WebSocket command further clarifies the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite note: use ha_config_get_calendar_events to obtain the event UID before deletion. It also explains that delete operations only exist on WebSocket, contrasting with REST services for create/get. However, it does not explicitly exclude usage for modifications or specify when not to use this tool, leaving a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true. The description adds crucial context: 'This will also remove the category assignment from all entities in that scope' and 'This action cannot be undone.' This goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a clear opening sentence, followed by effect, example, reference to get_category, and warning. Every sentence adds value and the structure is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 shown), the description adequately covers the delete operation's effect and irreversibility. It does not mention error conditions, but this is acceptable for a simple destructive tool with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds example usage with parameter names but no additional semantic details beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a Home Assistant category' with specific verb+resource. Among sibling tools, it is distinct from other removal tools like ha_remove_zone or ha_remove_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the scope of use (category registry, given scope) and provides an example. It advises using ha_config_get_category() to find IDs. It could be more explicit about when not to use this tool versus alternatives, but gives sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint: true, confirming mutation. The description adds details about create/update modes and parameter behaviors but does not disclose potential side effects, permissions required, or reversibility. It provides adequate context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (create mode, update mode, examples, note) and front-loads the main action. While somewhat lengthy due to multiple examples, every sentence adds value and the structure aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 params, two modes), the description covers all key aspects: mode behavior, required/optional params, integration limitations, and examples. With full schema coverage and an output schema present, no return value explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant value by explaining param relationships (summary vs rename, due_datetime override), mode-switching via 'item', and providing concrete examples that clarify parameter usage beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create or update a todo item in Home Assistant' and distinguishes two modes (create vs update) based on the 'item' parameter, which differentiates it from sibling tools like ha_remove_todo_item and ha_get_todo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use create mode (no item) vs update mode (with item), provides detailed examples for each scenario, and notes limitations across integrations. However, it does not explicitly state when to avoid this tool (e.g., for deletion or listing).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint. Description adds that it returns complete config including entities dict and other settings. No contradictions. Sufficiently transparent beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences for main description, plus examples and related tools in a well-structured format. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists and annotations are rich, description is complete for a read-only retrieval tool: purpose, return fields, examples, and related modifications covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with clear description for scene_id. Examples reinforce usage but description adds little beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'Retrieve Home Assistant scene configuration' with clear verb and resource. Distinguishes from sibling ha_config_set_scene. Specifies return fields (entities, name, icon, id).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides examples and related tools section pointing to ha_config_set_scene and mentions passing config_hash for updates. Though no explicit 'when not to use', the context and examples give sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds behavioral details: the two modes, return structures (entity_id, friendly_name, state for lists; uid, summary, status, description, due for items), and how the status filter works. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headings, bullet points, and examples. It is front-loaded with a clear summary. While somewhat lengthy, every section adds value, and the structure aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (two modes) and high schema coverage, the description covers the tool's behavior, return structure, and common use cases. It does not rely on an output schema (though one exists) but explains return values explicitly. No critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the effect of each parameter (e.g., 'entity_id' lists all lists when omitted, 'status' filter values with defaults) and provides examples that clarify usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets todo lists or items, with two distinct modes: listing all lists (no entity_id) and getting items from a specific list (with entity_id). It is specific, uses a verb+resource structure, and distinguishes from sibling tools like ha_remove_todo_item or ha_set_todo_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to omit vs. provide entity_id, and optionally filter by status. It includes examples and use cases. It does not explicitly mention when not to use this tool vs. mutation siblings, but annotations (readOnlyHint=true) and the read-only nature make it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and idempotentHint, so the safety profile is clear. The description adds context about pagination, response control, and the relationship to ha_call_service, which goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff. The first sentence defines action and options, the second links to another tool, and the third gives usage defaults—efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, pagination, filtering, and an output schema), the description covers all essential aspects: what the tool does, how to narrow results, detail control, and its role in the service call workflow. No important context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description summarizes key parameters (domain and query filters, detail level) but doesn't add significant new meaning beyond what the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists available Home Assistant services with optional pagination and detail control. It distinguishes itself from sibling tools like ha_call_service by noting that it discovers services that can be called, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using domain or query filters to narrow results and defaults to summary mode for compact responses. It implicitly guides usage before calling services but does not explicitly state when not to use it or list alternatives, though no direct alternative exists among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds valuable context: entities/devices are unassigned (not removed), floors unassign areas, and automations may break. This goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with no wasted words. Main purpose is front-loaded, followed by necessary details. Every sentence is informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, presence of output schema, and annotations, the description is complete. It explains side effects, risks, and how to find IDs, meeting all needs for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented. The description adds a helpful hint for the id parameter: 'use ha_list_floors_areas to find IDs', which adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it removes a Home Assistant area or floor, with specific verbs and resource. It distinguishes from sibling tools like ha_set_area_or_floor (create/update) and ha_list_floors_areas (list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It says what the tool does but does not explicitly tell when not to use or recommend alternatives. It is clear for its intended use but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds significant behavioral context: bulk mode with parallel requests, deduplication, partial-success handling, fields projection behavior, and warnings for attribute_keys no-effect. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections and examples, but slightly verbose. It front-loads the core purpose and uses clear formatting, earning its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all modes, edge cases (partial success, no-effect warnings), and provides examples. With an output schema existing, return values are covered. Complete for a complex tool with 3 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaning beyond the schema by explaining fields projection behavior in detail, attribute_keys dependency, and warnings. It clarifies the interaction between parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get current status, state, and attributes of one or more entities'. It specifies the verb 'Get' and the resource 'state of entities', and distinguishes it from siblings by being a read-only state retrieval tool, unlike other tools like ha_get_entity or ha_get_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed guidance on single vs multiple entities, fields projection, and attribute_keys, with examples. It does not explicitly mention when not to use or alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint: true, and the description confirms modification behavior. It adds specific constraints: only specified fields change on update, defaults for radius and passive on create, and the home zone restriction. This goes beyond the annotation's general destructiveness hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear first sentence, followed by bullet-like paragraphs summarizing create vs update, then examples, and a final note. Every sentence adds value, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (create/update, 7 params) and the presence of an output schema, the description is fairly complete. It covers key behavioral aspects, required fields, defaults, and a notable restriction. Lacks details on error handling or edge cases like invalid coordinates, but schema validation likely covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all 7 parameters with descriptions (100% coverage). The description adds semantic value by clarifying which parameters are required for create (name, latitude, longitude) and showing usage via examples. It also states default values (radius 100, passive False) that are not explicitly in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'Create or update a Home Assistant zone', which is a specific verb+resource. It distinguishes itself from sibling tools like ha_get_zone (read) and ha_remove_zone (delete) by explicitly covering both creation and update operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each mode: omit zone_id for create, provide for update. It also notes the limitation that the 'home' zone cannot be modified. Examples illustrate typical usage, and it references sibling tool ha_get_zone for finding zone IDs. However, it does not explicitly compare to alternatives like ha_remove_zone for deletion, though that is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool modifies state (create/update), consistent with destructiveHint annotation. It adds context about the purpose of labels and how assignments work, going beyond the annotation's simple destructive flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loading the core action, followed by a brief explanation and well-structured examples. Every sentence is useful with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema coverage, annotations, and presence of an output schema, the description is complete. It explains the create/update behavior, provides examples for all parameters, and links to a related tool for assignment.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 5 parameters with descriptions (100% coverage). The tool description adds value through concrete examples showing how to use parameters like color, icon, and description in context, which aids understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates or updates a Home Assistant label, with explicit differentiation between create (no label_id) and update (with label_id). It distinguishes from siblings like ha_config_get_label and ha_config_remove_label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use create vs update based on label_id presence, and provides examples for various use cases. It also advises on subsequent steps (use ha_set_entity to assign). While it doesn't explicitly state when not to use it, sibling tools cover other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, openWorldHint. Description adds context about access to all HA states, security model, timeouts, and performance impact. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and examples, but overly verbose with a large catalog of common template functions. Could be more concise while retaining essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage guidelines, parameter details, common functions, examples, and important notes. Output schema exists, so return values need not be described. Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates with a 'Parameters:' section giving clear one-line explanations for each parameter (template, timeout, report_errors). Adds meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Evaluate Jinja2 templates using Home Assistant's template engine', with specific verb and resource. Distinguishes from sibling tools like ha_get_state and ha_search by explicitly stating when not to use for plain state queries and providing alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (one-shot derived answers, template testing) and when-not-to-use (automation/script logic) guidance, with specific alternatives for native constructs. Includes examples and references to ha_get_skill_guide for best practices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It explains pagination behavior, fields projection, special always-emitted fields (settings_url, ha_mcp_update), sidecar URL conditions, and update check logic. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose but well-structured with clear sections. It front-loads the core purpose but includes lengthy details about settings_url and ha_mcp_update. Could be more concise without losing essential information, hence a score of 3.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (10 parameters, pagination, multiple modes, special fields) and the presence of an output schema, the description covers virtually all aspects: detail levels, pagination, field projection, always-emitted fields, and update checks. It is thorough and leaves minimal gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds value by explaining interactions between detail_level, limit, offset, and fields, and clarifying that domain counts and states_summary are always complete. This exceeds the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get AI-friendly system overview with intelligent categorization' and lists the specific information returned (base_url, version, location, etc.). It distinguishes this broad overview from the many specific sibling tools like ha_get_scene, ha_get_state, etc., making the purpose unique and well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use different detail levels ('Use minimal for most queries'), fields projection to reduce payload, and how to handle settings_url and ha_mcp_update. It lacks explicit exclusions or alternative tool mentions, but the context of sibling tools makes the scope clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include openWorldHint and destructiveHint, and the description adds valuable context: overwrite=true triggers reload of automations/scripts, conversion of URLs to raw, and return of error details. No contradiction. The description supplements the annotations effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (overview, examples, supported sources, returns). Every sentence serves a purpose, and the length is appropriate for the tool's complexity. No extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema, the description still explains return values (import result, metadata, overrides_existing, error details). It covers input, behavior, output, and examples comprehensively for a moderately complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions. The description adds examples of URL formats, explains the overwrite flag's effect, and lists supported sources. Despite high schema coverage, the description provides substantial additional meaning beyond the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Import a blueprint from a URL', specifying the verb (import), resource (blueprint), and source (URL). It distinguishes from sibling tools like ha_get_blueprint (which retrievs existing blueprints) and ha_manage_hacs. No tautology; the 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (importing blueprints from various sources) and provides examples and supported sources. It also describes the overwrite behavior and re-import action. However, it lacks explicit when-not scenarios or direct comparisons to alternatives, which would earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds value beyond annotations by explaining config_hash stability across reads, automation_id resolution with fallback, and that it returns the complete config. No contradictions with readOnlyHint and idempotentHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for examples and details. Slightly verbose but not excessive; every sentence adds value. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema existence and annotations, the description fully explains return fields (config_hash, automation_id) and behavior. No gaps for a get config tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds meaning by describing identifier as 'Automation entity_id (e.g., 'automation.morning_routine') or unique_id' with examples. Well-explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve Home Assistant automation configuration' and details what is returned (triggers, conditions, actions, mode). It distinguishes from sibling tools like ha_config_set_automation (write) and ha_config_remove_automation (delete) by being a read operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides examples for calling with entity_id or unique_id, and directs to ha_get_skill_guide for comprehensive docs. While not explicitly stating when not to use, the read-only nature is clear, and examples cover typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds important behavioral warnings beyond annotations: automations may fail, YAML groups reappear after restart, only removes old-style groups. Annotations already indicate destructiveHint, but description provides specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, warnings, and an example. Front-loaded with main purpose, then conditional guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, behavioral traits, and mentions runtime behavior. Missing details on permissions or side effects beyond automations, but overall comprehensive given output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented. Description adds minimal value beyond schema (only an example usage of object_id). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (remove), resource (service-based Home Assistant entity group), and method (via group.remove service). Differentiates from sibling tools by specifying which groups are covered.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When NOT to use' with reference to sibling tool ha_remove_helpers_integrations, and 'When to use' with examples. Also suggests listing groups first with ha_config_list_groups().
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true, but the description adds critical behavioral details: the tool only works on UI-created scripts and may break automations. It does not discuss idempotency, but overall adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with sections (examples, limitation, warning). Each part adds value, though slightly verbose. Could be more concise but remains clear and organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, limitations, side effects, and examples. Given the tool's simplicity (2 params, destructive) and presence of output schema, the description is thorough and leaves no important gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds meaning: explains script_id can be bare key or entity_id with prefix stripping, and clarifies wait default. This extra context merits a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a Home Assistant script' and distinguishes it from sibling tools like automation or scene removal by specifying scripts. The limitation about UI vs YAML-created scripts adds further specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use (deleting UI-created scripts) and when not to (YAML-defined scripts, instructing to edit configuration directly). Warns about potential automation failures, giving clear context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses critical behavior: the `config` key is only available with the ha_mcp_tools custom component. Annotations already indicate readOnly, idempotent, open world, and description adds no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for general description, mode explanation, examples, and return values. Front-loaded with main purpose. Slightly long but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully covers the tool's complexity: two modes, conditional behavior of `config`, return structures. No gaps given the output schema exists and is described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The description adds context by explaining the effect of each parameter (e.g., path omission triggers listing) and provides examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool gets blueprint information, distinguishing between listing all blueprints and getting details for a specific one. The verb and resource are explicit, and it differentiates from sibling tools like ha_import_blueprint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use without path (list all) and with path (get details), with concrete examples. Does not explicitly compare to alternatives but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds substantial behavioral context: explains resolver mode behavior, details response fields including resolved-name enrichment, warns about aliases/device_class defaults in resolver mode, and provides guidance on using config_entry_id for helper configuration retrieval. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is long but well-structured with clear sections (RESOLVER MODE, RELATED TOOLS, EXAMPLES, RESPONSE FIELDS). Information is front-loaded with the core purpose. While some technical details could be compressed, the structure is logical and aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (4 parameters, output schema, annotations), the description is exceptionally complete. It explains all response fields, includes rich behavioral details, and links to complementary tools. The resolved-name enrichment caveat adds valuable context. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining resolver mode, mutual exclusivity of entity_id and unique_id, and the role of domain/platform filters. It does not repeat schema details but provides contextual meaning beyond the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get entity registry information for one or more entities.' It uses a specific verb ('get') and resource ('entity registry information'), and distinguishes from sibling tools like ha_set_entity (modify), ha_get_state (current state), and ha_search (find entities).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the resolver mode for unique_id, provides examples for single/multiple entities, and lists related tools with brief descriptions. However, it does not explicitly state when not to use this tool or when alternatives are preferred beyond the related tools list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by detailing the return structure for both listing and single-entity cases, explaining conditional enrichment when the ha_mcp_tools component is available, and noting which fields are absent otherwise. This fully discloses behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for general behavior, examples, and return values. It is slightly verbose due to detailed return info, but every sentence adds value. It is front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only 2 optional parameters and an output schema, the description covers all necessary aspects: multiple usage modes, filtering, conditional enrichment, and detailed return format. It is fully complete given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The tool description adds extra value by providing usage examples and explaining the effect of omitting entity_id (list vs specific), which enriches understanding beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets entity exposure settings, with two distinct modes: listing all entities or getting a specific entity. The verb 'get' and resource 'entity exposure' are specific and unambiguous. It distinguishes itself from sibling tools like ha_get_entity and ha_get_state by focusing exclusively on voice assistant exposure settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context through examples for listing all, filtering by assistant, and getting a specific entity. It implicitly differentiates from other entity tools by its specialized purpose, but lacks explicit 'when not to use' guidance or direct comparison with alternatives like ha_get_entity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and idempotentHint=true. The description adds behavioral context: 'No skill bundles are currently available... Calls return an empty listing; ask the operator to verify the skills-vendor submodule is initialized.' This provides transparency about current state and failure modes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but well-structured: a brief purpose, status note, usage guidance, and replacement info. Every sentence serves a purpose, though it could be slightly more compact. Still concise for the amount of useful information provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 optional parameters, no enums, output schema present), the description covers all necessary context: current state, usage timing, replacement info, and parameter hints. It is complete for an agent to decide when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description does not add significant meaning beyond what is in the schema (e.g., 'Skill name from the no-args listing' is already in schema). Baseline of 3 is appropriate as schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get bundled Home Assistant best-practice skill guides.' It specifies the resource (skill guides) and action (get), and distinguishes from siblings by focusing on skill guides, not other config entities. It also notes the current unavailability, which sets expectations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use BEFORE: creating or editing automations, scripts, scenes, helpers, or dashboards; ...' and lists specific tool calls. It also clarifies that it supersedes earlier tools (ha_list_resources, etc.), providing clear alternatives and exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description goes far beyond by detailing sorting order, handling of level=None, unassigned and orphaned areas, consistency guarantees with registries, and a legacy path caveat. This provides extensive behavioral context that annotations alone do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose. It is somewhat lengthy (5 sentences plus a paragraph on consistency), but each part contributes necessary behavioral detail. Could be slightly more concise, but it remains clear and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (floors, nested areas, unassigned, orphaned) and the presence of an output schema, the description covers all essential aspects: sorting, level handling, edge cases (None floors, orphaned areas), consistency guarantees, and response projection. No gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed descriptions for both parameters. The description adds value by explaining how to project responses with fields= and area_fields=, giving examples (e.g., ['area_id', 'name']), and listing available keys. It enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List floors sorted by level ascending, each with their assigned areas nested, plus areas without a floor.' It uses a specific verb ('list') and resource ('floors and areas'), and the unique scope (nested areas, unassigned, orphaned) clearly distinguishes it from sibling tools that handle individual entities or different domain objects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use for location-based reasoning where floor-to-area relationships matter, such as 'which rooms are on the ground floor' or operations scoped to a level.' It gives concrete use cases but does not explicitly state when not to use it or offer alternatives, though the sibling tool list implies other tools for other purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond annotations by detailing permanent deletion, bulk mode sequential behavior, return format ({removed, skipped, errors}), idempotency of not-found, and backup implications. Though annotations already mark it destructive/idempotent, the description adds valuable operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headings (WARNING, BULK MODE, EXAMPLES, NOTE, RELATED TOOLS) and front-loads the primary purpose. It is somewhat lengthy but each section earns its place given the tool's destructive nature and bulk mode details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: purpose, warnings, bulk mode behavior, return format, idempotency, backup implications, and relationship to other tools. With an output schema present, the return format description in bulk mode is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with a clear description for entity_id. The description adds bulk mode semantics (up to 100 items, sequential removal, return format) and examples, enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove one or more entities from the Home Assistant entity registry' with specific verb and resource. It distinguishes from related tools like ha_set_entity (disabling) and ha_search (finding entities), and provides examples for different use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends using only for orphaned or stale entries, warns about automatic re-addition, and suggests disabling as an alternative. It also lists related tools (ha_search, ha_get_entity) for verifying before removal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint: true. The description adds important behavioral context: warns that deleting used resources will cause custom cards to fail to load, which goes beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise: action stated first, warning, example, and note. No superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a single-parameter delete tool. Covers what happens, prerequisite, example, and warnings. Output schema exists for return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers resource_id with description. Description reinforces with example and advice to get ID from list function. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a dashboard resource' and explains it removes a resource from Home Assistant. It distinguishes from siblings like ha_config_set_dashboard_resource and ha_config_list_dashboard_resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context for when to use (to delete a resource), a warning about consequences, and an example. Mentions using ha_config_list_dashboard_resources() to find IDs, but doesn't explicitly state when not to use or mention alternatives beyond listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), the description details defaults for start/end, max_results, and the return format (list with fields). This adds operational context not captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, parameters, example, note, and returns. It is concise and front-loaded, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity, full schema coverage, and presence of output schema, the description is complete. It explains purpose, parameters, defaults, example usage, and suggests how to find entity IDs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description repeats schema descriptions but adds practical context through example usage and a note on finding entities, which provides extra meaning for an AI agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'calendar events' from a calendar entity. It is distinct from sibling tools 'ha_config_remove_calendar_event' and 'ha_config_set_calendar_event', making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a note on finding calendar entities via 'ha_search' and shows example usage. While it does not explicitly state when not to use, the context of read-only operation is clear from annotations and sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe, idempotent read. The description confirms read-only behavior (lists, returns configuration). Discloses domain-scoped nature. Does not contradict annotations. Adds details about optional icon, but could mention that the output schema exists (though not shown).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with sections (overview, properties, examples, related tools). About 10 sentences, but each sentence adds value. Could be slightly more concise by merging the examples into a list, but overall efficient and front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params) and the presence of an output schema (not shown but context indicates coverage), the description covers all behavioral aspects: parameter behavior, returned properties, usage examples, and even mentions external methods for creation and assignment. It is contextually complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters documented. The description adds significant value beyond the schema: clarifies behavior based on category_id presence, lists the returned properties (ID, Name, Icon) not in schema, and provides concrete examples showing parameter usage and expected outputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool lists categories for a scope or gets a specific one by ID. It distinguishes itself from sibling tools like ha_config_set_category (create/update) and ha_set_entity (assign to entities). The verb+resource is clear and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use guidance: without category_id lists all categories for a scope, with category_id returns specific. Includes multiple examples. References ha_config_set_category for creating/updating and ha_set_entity for assigning, giving alternatives and related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds rich behavioral details beyond annotations: config_hash stability contract, script_id resolution fallback, prefix stripping mechanism. The annotations already mark idempotent and read-only, which the description complements without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections and examples. The trailing keyword list ('read inspect fetch...') is slightly extraneous but does not detract from clarity. Overall concise and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema (not shown but assumed comprehensive), the description provides sufficient context on return values (config_hash, script_id) and behavior. Mentions skill guide for further help, completing the user's informational needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers script_id with 100% documentation, but the description adds significant value by explaining the returned script_id resolution, prefix stripping, and behavioral parity with ha_config_get_automation, enhancing the parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'Retrieve Home Assistant script configuration' and details the returned content (sequence, mode, fields). Distinguishes from sibling tools like ha_config_set_script and ha_config_remove_script by referencing them in the script_id resolution behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context with input examples and notes about prefix stripping. Mentions ha_get_skill_guide for detailed help. Does not explicitly state when not to use this tool, but the read-only nature and sibling relationships are implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds significant behavioral context: pagination (one page, limit/offset, total_count and has_more reporting), and the specific fields returned. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear opening sentence, a bullet list of returned fields, two examples, and a clarifying note. Every sentence is necessary and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, comprehensive annotations, and the description covering purpose, pagination, scope, and field list, the description is complete. No gaps are evident for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for limit and offset. The description adds value by explaining pagination behavior ('one page' and examples showing usage), which goes beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List Home Assistant entity groups with their member entities,' specifying the verb and resource. It differentiates from sibling tools by noting that this returns old-style groups created via group.set or YAML, while platform-specific groups are separate entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly provides usage context: it is for listing old-style groups, and platform-specific groups are not included. However, it lacks explicit 'when to use' vs alternatives or 'when not to use' guidance, though the note offers some differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that deleting a label removes it from all entities, devices, and areas, and that the action cannot be undone. This adds significant behavioral context beyond the annotations (destructiveHint true, idempotentHint true).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: clear purpose, then details, then example, then warning. Each sentence is informative and necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single required parameter, annotations, and presence of an output schema, the description fully covers what the tool does and its effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes label_id as 'ID of the label to delete' (100% coverage). The description adds value by mentioning where to find label IDs (ha_config_get_label()).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a Home Assistant label' and explains the action (remove from registry and assigned entities). It distinguishes itself from sibling tools like ha_config_set_label and ha_config_get_label by its delete operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an example command and suggests using ha_config_get_label() to find label IDs. It warns about irreversible removal, but does not explicitly state when to use this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description extensively discloses behaviors beyond destructiveHint: true, such as inline content being stored as data: URI, deterministic URLs, ~128KB limit, CSP blocking issues, and supported types per mode. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose but well-structured with sections, bullet points, and examples. It front-loads the core purpose. Some redundancy exists (e.g., examples could be condensed), but every sentence adds meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, output schema present), the description covers all aspects: purpose, modes, parameters, limitations, examples, and update mechanism. It is fully complete for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds significant value by explaining mutual exclusivity of url and content, inline mode limitations (supports only 'module' and 'css'), and the source of resource_id (from list). Examples demonstrate parameter combinations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create or update a dashboard resource (inline code or external URL).' It distinguishes two modes (inline vs URL) and specifies resource types, making the purpose specific and distinct from sibling tools like deletion or listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use guidance by detailing inline vs URL modes, including prerequisites for URL mode (e.g., files in /config/www/ for /local/) and alternatives for CSP-blocked environments. It lacks explicit 'when not to use' but sufficiently implies context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnlyHint and idempotentHint annotations by detailing the specific information returned for each mode (e.g., ingress, ports, options for single add-on; version/state for installed; search for available). It also explains that slug prefixes vary, advising to omit slug to discover the actual slug, which is valuable 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for each mode, bullet points, and examples. It is front-loaded with the core purpose and each section adds necessary detail without redundancy. Despite length, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all usage scenarios and return values comprehensively. Given that an output schema exists (though not shown), the description is complete enough for an AI agent to understand what to expect from each invocation mode.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds significant extra context, such as the dependency on repository for slug prefixes, the scope of 'include_stats' and 'query', and includes examples. This extra information raises the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves add-on information, distinguishing between listing installed, available, or getting details for a single add-on via the 'slug' parameter. It differentiates from sibling tools like ha_manage_addon by focusing on retrieval, not management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each mode (slug, installed, available) and notes that the tool only works with Home Assistant OS or Supervised installations. It implicitly suggests ha_manage_addon for management, but could be more explicit about when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds significant behavioral context: states the possible states, options behavior (redacted secrets, flattening of nested sections), log_level vs log_level_raw, and behavior of parameters like include_schema and include_diagnostics. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with clear sections, examples, and bullet points. It is front-loaded with the main purpose. A slight reduction in verbosity could improve conciseness, but the complexity justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (21 parameters, many optional) and presence of an output schema, the description covers all essential aspects: listing vs detail, pagination, options behavior, subentries, diagnostics, KNX project, and parameter interactions. No gaps observed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds substantial value beyond schema descriptions: examples of usage, distinction between include_options and include_schema, details on diagnostics_fields and diagnostics_data_path truncation, and KNX project specifics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get integration (config entry) information with pagination.' and contrasts list mode vs detail mode. It distinguishes from siblings like ha_set_integration and ha_get_addon via detailed examples and log_level format notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use each mode (without entry_id for list, with entry_id for details) and includes pagination, filtering, and parameter combinations. Lacks explicit 'do not use' statements, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations (readOnlyHint, idempotentHint) by detailing pagination, ordering behavior, default values, and source-specific behaviors (e.g., 'order' applies to time-ordered sources, ignored for 'logger'). It also explains that 'compact' strips attribute dicts and that 'slug' disambiguation is handled by the 'source' param. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections and bullet points, making the dense information scannable. However, it is somewhat lengthy (8 paragraphs) and could be trimmed slightly without losing clarity. Every sentence adds value, but the overall length might overwhelm an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters, no required fields, and an output schema present, the description covers all aspects: source selection, parameter applicability, default values, and ordering. It leaves no ambiguity about how to construct a valid request or interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 9% schema description coverage, the description fully compensates by explaining all 11 parameters: source, slug, level, limit, order, offset, search, compact, end_time, entity_id, hours_back. It provides context-specific semantics (e.g., 'search' matches integration domain for source='logger', 'order' sets read direction for raw-text sources).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets HA logs from six distinct sources, each with a specific purpose (e.g., 'logbook' for state change history, 'system' for structured errors). This verb-resource pairing is specific and differentiates from sibling tools like ha_get_history, which likely retrieves historical state changes rather than log sources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed guidance on when to use each source (e.g., 'supervisor' requires a slug, 'logger' confirms level changes). It shares common parameters and notes that some params are source-specific. However, it does not explicitly mention when to avoid this tool in favor of siblings or provide negative examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint, openWorldHint, and idempotentHint=true. The description adds significant behavioral context, including the return of the ha_mcp_update object, caveats about payload sizes for diagnostics, and that operations like config_check are read-only and idempotent. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy due to the tool's complexity, but it is well-structured with a clear lead sentence, a separate paragraph for the ha_mcp_update object, and bullet-point-like explanations for include options. While every sentence earns its place, some redundancy exists (e.g., repeating 'Only applies when include contains diagnostics'). Minor trimming could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, no schema coverage, no enums), the description is exceptionally complete. It covers all parameters, explains return values (including the ha_mcp_update object), provides workflow examples, and addresses edge cases (e.g., omission when version is unknown or HA_MCP_DISABLE_UPDATE_CHECK set). The presence of an output schema does not reduce the need for this detail, and the description delivers.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully explains all 9 parameters. It lists every possible value for include, describes the behavior of each parameter (e.g., diagnostics_data_path, diagnostics_truncate_at_bytes), provides examples, and clarifies dependencies (e.g., config_entry_id required for diagnostics). This exceeds the minimum required and compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get Home Assistant system health, including Zigbee (ZHA), Z-Wave JS, and per-integration diagnostics dumps.' It specifies the resource (system health) and the specific integrations covered, effectively distinguishing it from sibling tools that focus on individual integrations or other aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance for specific include options, such as 'Use this when triaging integration bugs or filing ha_report_issue for a specific integration' for diagnostics. It also hints at appropriate contexts for other options like dead_entities. However, it lacks a general statement on when to use this tool versus alternatives, which would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as readOnlyHint=true and idempotentHint=true. The description adds valuable context beyond that, such as listing zone properties, the behavior difference between with/without zone_id, and a detailed note about YAML-defined vs storage zones depending on component installation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: clear main statement, bulleted list of properties, examples, and a note. Every sentence serves a purpose without redundancy. It is concise yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 does not need to detail return values. It covers input behavior, properties, and special considerations. For a read-only tool with one optional parameter, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter. The description reinforces the parameter's role: 'Zone ID to get details for... If omitted, lists all zones.' This adds clarity beyond the schema's description, and examples illustrate usage. A score of 4 reflects the added value while acknowledging the schema already does heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get zone information - list all zones or get details for a specific one.' It distinguishes two modes based on the presence of a zone_id, and the title 'Get Zone' directly maps to reading operations, differentiating it from siblings like ha_remove_zone or ha_set_zone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use each mode: 'Without a zone_id: Lists all Home Assistant zones... With a zone_id: Returns detailed configuration for a specific zone.' It also provides examples. However, it does not explicitly mention when not to use this tool or suggest alternatives among siblings, which would improve the score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), the description discloses full-replace semantics, hash-locking behavior, admin-only permission, dry_run effects, error types (RESOURCE_LOCKED, RESOURCE_ALREADY_EXISTS, RESOURCE_NOT_FOUND, VALIDATION_FAILED), and non-idempotence. This adds substantial value over annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections and bullet points, but it is very long and wordy. Some caveats could be condensed without losing meaning. The front-loading of overall purpose is good, but the length detracts from conciseness, earning a mid-range score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, 1 required, 100% schema coverage, output schema present, annotations provided), the description covers all important aspects: operational modes, error cases, locking semantics, dry_run behavior, shape validation, and security constraints. It leaves no gaps for an agent to misunderstand.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While input schema has 100% description coverage (baseline 3), the description adds extra detail like config_hash accepting dict/object, source field requirements per type, and included_in_stat semantics. This extra context justifies a slight above-baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages Home Assistant Energy Dashboard preferences, enumerates all operation modes (get, set, add_device, remove_device, add_source), and differentiates itself from siblings by noting this is the only way to access the energy storage. It provides specific verb-resource pairs and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit WHEN TO USE and WHEN NOT TO USE sections, detailing each mode's purpose. It advises when to use convenience modes vs. set, and notes that underlying statistics must be created via other integrations first. Though alternatives aren't explicitly named, the guidance is comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description details that installs run asynchronously, take minutes, and require polling to monitor progress. It also clarifies read-only mode behavior. No contradictions with annotations; this adds significant value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: overview, scope, behavioral notes, examples, and return documentation. Every sentence adds value, and the key information is front-loaded. No unnecessary verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple actions, async execution, categories, return types), the description thoroughly covers all aspects. It explains return formats, mentions the ha_mcp_update status, and provides practical examples. No gaps remain for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds behavioral context beyond the schema, such as mutual exclusivity of entity_ids and categories for install, and the effect of include_release_notes on the response. It enhances understanding of parameter interactions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Manage Home Assistant updates -- list, read details, batch install, skip, or un-skip.' It lists the covered update domains (Core, OS, supervisor, apps, device firmware, HACS), making the scope explicit. This distinguishes it from sibling tools that handle different aspects of Home Assistant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each action (list, get, install, skip, clear_skipped) and provides examples. It notes read-only mode behavior and asynchronous installs with polling instructions. However, it does not explicitly exclude scenarios or compare to specific sibling tools, which would elevate to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description adds value by detailing what reload actions are available (target options) and the special behavior of entry_id (fast path for single integration). It does not repeat annotation info, but provides behavioral context beyond it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with sections, bullet points, and code examples, making it easy to scan. While somewhat lengthy due to the many target options, every sentence earns its place. Could be slightly more concise, but the structure aids comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 parameters (both optional), an output schema exists (so return values are covered), and no nested objects, the description is fully complete. It covers all possible parameter values, usage patterns, and links to sibling tool ha_get_integration for finding entry_id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage), but the description compensates fully by enumerating all 17 valid target options with explanations, and thoroughly explains entry_id usage including how to find the id and that combining with target is a validation error. This adds critical meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool reloads Home Assistant configuration without a full restart, using a specific verb ('reload') and resource ('core components'). It distinguishes from sibling ha_restart by emphasizing speed and avoiding full restart. The extensive target list further clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a dedicated 'When to Use' section listing specific scenarios (e.g., after editing automation YAML, modifying customize.yaml). It also explains entry_id usage and warns against combining it with an explicit target, providing clear guidance on proper invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes side effects (removes device entry, may remove associated entities), safe method (config entry removal), and multiple config entry requirement. Adds context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with warning, bullet points, example, and alternative. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, consequences, and alternatives. Output schema exists, so return values need not be described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an example usage, but the input schema already fully describes the device_id parameter. No additional semantic value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states it removes an orphaned device from the registry. Distinguishes from siblings like ha_set_device and ha_remove_entity by specifying orphaned condition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use (only for orphaned devices), when-not-to (active devices may be re-added), and an alternative (disable via ha_set_device).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description reinforces the permanent deletion with a warning. However, it does not explain the idempotent behavior (e.g., removing a non-existent item may not error), though the annotation covers it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headings (IDENTIFYING ITEMS, EXAMPLES, USE CASES, WARNING), is front-loaded with the core purpose, and every sentence adds meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (simple removal operation with two parameters), the description covers identification methods, examples, use cases, and a warning about permanence. Since an output schema exists, there's no need to detail return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds value by providing examples of how to use the 'item' parameter with UID or exact name, and 'entity_id' with a concrete example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove an item'), the resource ('Home Assistant todo list'), and specifies it is a permanent deletion. It distinguishes from the sibling 'ha_set_todo_item' by mentioning the alternative for marking as completed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance, including how to identify items (by UID or exact name) and specific use cases. It clearly directs users to use 'ha_set_todo_item' for marking items as completed instead of deleting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint=true, and the description discloses that the tool creates or updates records, implying overwriting. It also details validation behavior (cross-kind params rejected). However, it does not explicitly mention that updates replace existing data or any 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet complete, with a clear structure: purpose statement, parameter rules, and examples. Every sentence provides necessary information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers creation and update for both area and floor, includes cross-kind validation, and provides examples. Since an output schema exists, return values are not required. The description fully addresses the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by showing how parameters combine in examples (e.g., floor_id with kind='area'), which clarifies usage beyond individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state the tool creates or updates Home Assistant areas or floors. It distinguishes between the two kinds ('area' vs 'floor') and between create vs update operations, providing a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidelines for when to use kind='area' vs kind='floor', when to create (provide name) vs update (provide id), and warns that cross-kind parameters are rejected. Examples illustrate common use cases, making usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds critical details: permanent deletion, irreversibility, ID resolution behavior, and the restriction on default dashboard. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a clear warning, bullet-point-like explanation, an example, and a note. Every sentence contributes meaning without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, destructive operation) and the presence of output schema (not shown but indicated), the description covers all necessary aspects: purpose, limitations, parameter details, and an example. No missing information for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter url_path is fully covered by schema (100%), but the description adds important context: it accepts both URL path and internal ID, explains hyphens vs underscores, and notes the tool resolves to actual registry ID. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a storage-mode dashboard permanently, using a specific verb and resource. It distinguishes from siblings by specifying it works only on storage-mode dashboards, not YAML-mode, and mentions the default dashboard cannot be deleted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (delete storage-mode dashboards) and when not to (YAML-mode, default dashboard). It does not name alternative tools explicitly, but the context implies alternatives like editing config files for YAML-mode.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral context beyond annotations: search always fetches fresh config, YAML dashboards excluded for security, config_hash stability, depth bounds with warnings, view_path returns only that view with view_index, error behavior for unknown view_path. No contradiction with readOnlyHint/idempotentHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured into modes with clear headings. Every sentence adds value, but the description is lengthy. Could be slightly more concise, but the complexity of four modes justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completely covers all modes, return structures (list metadata, config, view, matches with paths, warnings), edge cases (YAML/strategy exclusion, unknown view_path error), and workflow example. No output schema, but description adequately documents return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with descriptions, but the description adds meaning beyond the schema by explaining parameter interactions (e.g., mode takes precedence over list_only/search params, list_only ignores url_path, include_config only in search mode). Examples illustrate parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves dashboard info from Home Assistant. It details four distinct modes (list, search, get, search all) with specific verbs and resources, and distinguishes it from sibling tools like ha_config_set_dashboard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use each mode (e.g., 'list_only=True to list all dashboards', 'search when entity_id/card_type/heading provided', 'get when no search params'). Includes examples, a workflow, and states when not to use (YAML/strategy dashboards not searchable).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond annotations (readOnlyHint, idempotentHint) by explaining trace storage limits, behavior of pagination, effect of parameters like detailed and deduplicate, and expected state field values. This fully discloses behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear headings (USAGE MODES, DEBUGGING EXAMPLES, NOTES), front-loaded purpose, and no redundant text. Every sentence adds value, making it easy to scan and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, automation debugging), the description covers all usage modes, parameter behavior, debugging scenarios, and limitations. An output schema exists, so return values are handled; the description is fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema by demonstrating parameter usage in concrete examples (e.g., omitting run_id for listing, providing it for details, using detailed=True for extra diagnostics). Schema coverage is 100%, but the description enriches each parameter's role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves execution traces for automations and scripts to debug issues, detailing what traces show (triggers, conditions, actions, errors, variables). It is unambiguous and distinct from sibling tools, which focus on logs, history, or other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive usage modes and debugging examples, guiding when to use each mode (list vs. detailed vs. logbook). However, it does not explicitly state when not to use this tool or mention alternatives, missing the full 'when-not' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavioral traits: it can be destructive (uninstall, remove repository), requires HA OS or Supervised, and provides warnings about boot mode failures. It does not contradict annotations (destructiveHint=true, readOnlyHint=false).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very long and includes extensive details (e.g., ESPHome API specifics, array-patch examples). While well-structured with sections, it lacks conciseness and could be trimmed to improve readability without losing essential guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (23 parameters, multiple modes, output schema), the description is thorough. It covers edge cases, error scenarios, and provides comprehensive examples, making it fully complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description adds significant value by explaining parameter relationships across modes, providing detailed examples, and clarifying nuances like the merge behavior of options. It far exceeds the baseline level of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages a Home Assistant add-on with five distinct operating modes (lifecycle, store-repository, config, proxy, array-patch). It uses specific verbs and resources, and distinguishes its purpose from sibling tools like ha_get_addon.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use each mode with conditions, prerequisites (e.g., repository must be registered), and exclusions (e.g., store-repository does not use slug). It provides clear guidance on when not to use certain options, such as boot mode failure when locked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveness (destructiveHint=true). Description adds context: restart duration (1-5 minutes), temporary unavailability of automations, and automatic config validation. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (warning, parameters, best practices, example, alternative). Every sentence provides value, no redundancy. Efficient yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all essential aspects: purpose, impact, parameter meaning, pre-check option, usage example, alternative. Additionally, output schema exists (though not shown), so description needn't explain returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but description fully explains the 'confirm' parameter: must be True, serves as safety measure. This adds critical meaning beyond schema's type/default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Restart Home Assistant' as the purpose, uses a specific verb and resource, and distinguishes from siblings by mentioning ha_reload_core as an alternative for config changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (restart instance) and when not (for config changes, use ha_reload_core). Includes best practices like notifying users and scheduling during low activity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral traits not in annotations: renaming device does not rename entities, labels replace existing ones, and how to disable/enable. Annotations only note destructiveHint=true, but the description adds rich context about the mutation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but well-structured: purpose statement, important note, workflow, parameter list, examples. It is front-loaded with critical info. Every section is valuable, though could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity, annotations (destructiveHint), and presence of output schema, the description covers all necessary aspects: parameters, important caveats, workflow, and examples. It is comprehensive enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a description. The narrative description adds value by explaining semantics like 'replaces existing labels' and 'empty string to unassign', and provides examples. This goes beyond the schema but slightly redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Update device properties such as name, area, disabled state, or labels.' It clearly distinguishes from sibling tools like ha_get_device (read) and ha_set_entity (entity operations) by noting that renaming a device does not rename entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: it describes a common workflow for full rename combining with ha_set_entity, and explains when to use each parameter (e.g., area_id with '' to unassign). It does not explicitly state when not to use, but the important note serves as a clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), the description reveals fire-and-forget behavior and that tool confirms bus acceptance but not subscriber action. This adds value and does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first sentence, usage guidelines section, and caveats. It is concise with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and output schema, the description covers purpose, usage, exclusions, and behavioral caveats. It is fully adequate 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description conveys the meaning of event_type (custom event type) and data (optional payload) through context, though it does not explicitly name or detail each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it executes a custom event on the Home Assistant event bus, providing a specific verb and resource. It also explicitly distinguishes itself from sibling tools like ha_call_service by stating when not to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use and when-not-to-use guidance, including specific alternatives (ha_call_service for entity control and automation triggering). It also describes the intended use case for event-triggered automations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral traits beyond annotations: pagination behavior, that it lists storage-backed helpers (except person), flow-type requirement for custom component, and the degraded case when entity registry read fails. No contradiction with annotations (readOnlyHint, idempotentHint).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and front-loaded with the main purpose. However, it is quite lengthy and contains some redundancy (e.g., repeating component requirement for 'all' mode). Still, the thoroughness is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (many helper types, pagination, storage vs flow, component dependency), the description is highly complete. It covers return values (including fields like id, entity_id, name), pagination, error cases, and cross-references. The output schema exists, so no need to detail return format further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds significant meaning: explains the difference between id and entity_id for renamed helpers, the meaning of offset/limit, and the component requirement for flow-based types and 'all' mode. The examples show concrete usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Home Assistant helpers of a specific type with their configurations. It distinguishes itself from sibling tools by focusing on helpers, listing supported types, and providing examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive usage guidelines: when to use (list helpers), differentiation between storage and flow-based types, component requirements, pagination, and references to related tools like ha_config_set_helper. It explicitly states when not to use (e.g., for flow types without the component) and gives examples for each helper type and 'all' mode.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, and the description reinforces this by detailing that updates are possible. Beyond annotations, it explains the return value (automation_id), warns about templates vs native solutions, mentions best practice warnings, and describes the two operational modes. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with clear section headers, bullet points, and examples. It front-loads critical info (purpose, native vs templates, modes) and then provides detailed examples. Some redundancy in examples, but the complexity of automation creation justifies the length. Could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple automation types, two modes, template guidelines, python transform security, output schema exists), the description covers all necessary aspects: return values, prerequisites, best practices, troubleshooting, and references to other tools. It is remarkably complete for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 88% schema description coverage, the schema already documents most parameters, but the description adds significant meaning: detailed examples for config, extensive security rules and examples for python_transform, explanation of identifier and config_hash usage, and the BestPracticeKey parameter. The description elevates understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create or update a Home Assistant automation.' It differentiates between creation and update, covers two modes (config and python_transform), and explicitly distinguishes from sibling tools like ha_config_set_scene and ha_config_set_helper by providing comparisons in the 'Before reaching for' section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive usage guidelines: when to use config vs python_transform, prerequisites for python_transform (identifier and config_hash), and alternatives for different use cases. It includes explicit 'when to use which mode' and 'Before reaching for' guidance, making it very clear for the agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, but the description adds crucial context: exclusive end date for all-day events, requirement for recurrence support, and failure modes for mixed date formats. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into clear sections (purpose, when not to, examples, notes, returns). Every sentence adds value without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, 4 required, and an output schema, the description covers all critical aspects: differences between event types, integration limitations, return values, and common pitfalls (date mixing, exclusive end). A complete guide for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds meaning through examples (all-day vs timed events, rrule format) and notes on exclusive end dates, which clarifies parameter interaction beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates calendar events, distinguishes between one-off and recurring, and explicitly contrasts with sibling tools for retrieval (ha_config_get_calendar_events) and deletion (ha_config_remove_calendar_event).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a dedicated 'When NOT to use' section naming specific alternatives, along with multiple examples and detailed notes on date format mixing and integration support. This is explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, and the description transparently explains creation/update behavior, index shifting after operations, storage-mode vs YAML-mode limitations, and provides detailed security info for python_transform. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, bullet points, and code examples. It's long but every section adds value. Could be slightly condensed, but overall earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 12 parameters and no output schema, the description covers usage, parameters, examples, edge cases, security, and limitations comprehensively. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite high schema coverage (92%), the description adds substantial meaning: explains python_transform security, config_hash for optimistic locking, best practice key attestation, and provides numerous examples and patterns. Goes well beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state 'Create or Update' a Home Assistant dashboard, with specific verbs and resource. It distinguishes from siblings by mentioning related tools like ha_config_get_dashboard, ha_config_delete_dashboard, and ha_config_set_yaml for YAML dashboards.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states prerequisites: 'MUST call ha_get_skill_guide OR refer to your locally installed skills first.' Provides clear guidance on when to use python_transform vs config mode, examples, and importantly clarifies what it does NOT cover (YAML-mode) and suggests alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations provide destructiveHint: true, the description adds critical context: groups are only removable via ha_config_remove_group (not ha_remove_helpers_integrations) and notes mutex condition among entities, add_entities, remove_entities. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (When NOT to use, When to use, For NEW groups, For EXISTING groups, EXAMPLES, NOTE). It is front-loaded with essential information, no unnecessary words, and each sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters and 1 required, the description covers all key use cases (create, update, add/remove entities) and addresses lifecycle considerations. It also notes the existence of an output schema (though not shown). The description is fully adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that entities is required for new groups, explaining the mutex condition, and providing examples that demonstrate parameter usage. This surpasses the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create or update a service-based Home Assistant entity group via the group.set service.' It uses specific verbs (create, update) and resource (group), and distinguishes itself from the sibling tool ha_config_set_helper for typical group creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when NOT to use (prefer ha_config_set_helper) and when to use (compatibility with existing groups, entity-registry membership unwanted). It also gives clear examples for new and existing groups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description extensively discloses behavioral traits beyond the `destructiveHint: true` annotation, including update semantics (preserves unpassed fields), the `action` fallback discriminator, silent ignoring of undeclared config keys, and how validation errors carry `data_schema` for self-correction. It also explains menu-handling with `next_step_id` as a list, which is non-obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Though long, the description earns its length given the tool's complexity. It is front-loaded with a one-line purpose, then organized into clear sections (SIMPLE/FLOW/CONFIG_SUBENTRY types, behavior notes, examples) so an agent can quickly navigate. No redundant content was found.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's high complexity (28 helper types, 43 parameters) and the rich schema/annotations, the description is impressively complete: it covers invocation patterns, disambiguation rules, failure modes (validation error data_schema), and includes concrete examples for non-obvious cases like template, group, tod, and config subentry. The output schema exists, so return values need not be described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 98%, so the schema already documents most parameters thoroughly. The description adds cross-cutting semantics (e.g., SIMPLE/FLOW types require `name` on create and `helper_id` on update, config subentry requires `entry_id`/`subentry_type`, flow updates require passing `entry_id` as `helper_id`). It does not cover `MandatoryBPS` (which also lacks a schema description), hence slight deduction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Create or update'), the resource ('Home Assistant helper entities and config subentries'), and the scope ('28 types, unified interface'). It distinguishes itself from sibling tools like ha_config_set_scene and ha_config_set_automation by focusing specifically on helper entities and config subentries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit prerequisites ('MUST call ha_get_skill_guide OR refer to your locally installed skills first'), clear differentiation between SIMPLE, FLOW, and CONFIG_SUBENTRY types, and concrete alternatives (e.g., 'To rename a flow helper, delete and recreate' instead of updating). Also gives a specific note on when to use `tod` instead of `schedule`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses destructive nature (destructiveHint true) and adds extensive behavior: optimistic locking, mutual exclusivity of parameters, infinite loop risk in python_transform, and a complete list of allowed/forbidden Python operations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, front-loaded with purpose and mode overview. The python_transform security section, while lengthy, is justified by the need for safe execution. Could trim slightly but maintains clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Handles tool complexity comprehensively: covers two modes, prerequisites, security, alternatives, and required preparatory steps (skill guide). With output schema present, return value documentation is unnecessary. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond schema (88% coverage): explains config shape (entities as dict, not list), provides python_transform examples and security rules, clarifies config_hash role, and describes BestPracticeKey protocol. Adds example and context for each key parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Create or update a Home Assistant scene', distinguishing from sibling tools like ha_call_service for runtime activation and ha_search for listing. Explicitly contrasts with ha_config_get_scene and ha_config_remove_scene by defining its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit WHEN TO USE and WHEN NOT TO USE sections, detailing two modes (python_transform vs config) with specific prerequisites (config_hash), and names alternative tools (ha_call_service, ha_search) and prerequisite calls (ha_get_skill_guide).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set destructiveHint=true. The description adds significant behavioral context: optimistic locking via config_hash, python transform security restrictions (allowed/forbidden operations), wait parameter for bulk operations, and best-practice checker that surfaces warnings. This exceeds annotation expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with sections, bullet points, and examples. It is front-loaded with critical usage guidance. Some redundancy exists (e.g., repeated examples), but given tool complexity, the structure is appropriate and earns a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, two modes, Python transform security, and integration with best-practice skills, the description covers all necessary aspects. Includes examples for both config and python_transform, references to related tools, and proactive skill content. Output schema exists, so return values are not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 88%, but description adds extensive meaning: explains config sub-keys (sequence, use_blueprint, alias, etc.), python_transform with examples and allowed patterns, wait behavior, category linking to other tools, and BestPracticeKey attestation. Every parameter is well-explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create or update a Home Assistant script', distinguishes two modes (config vs python_transform), and explicitly differentiates from sibling tool ha_config_set_automation via the 'SCRIPTS vs AUTOMATIONS' section. The verb and resource are specific, and examples confirm purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: python_transform for edits, config for new/full restructures. Requires config_hash for python_transform. Details prerequisites, best-practice preferences (native over templates), and when to use automation instead. Examples cover multiple scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnlyHint annotation by disclosing real-time WebSocket verification, shared timeout windows for bulk checks, concurrent polling, and per-item failure reporting. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, front-loaded with the primary function and expanding into modes and error handling with minimal redundancy. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with moderate complexity, the description covers single vs. bulk usage, timeout behavior, failure semantics, and provides clear alternatives. Combined with the existing output schema and annotations, it is thoroughly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes operation_id fully but timeout_seconds only has a default. The description compensates by explaining that timeout_seconds bounds both modes and that bulk checks share one window, adding meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets operation status via WebSocket verification, specifying both single and bulk modes. It distinguishes itself from the sibling ha_get_state by noting it is for operation tracking rather than current entity states.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: to track operations from ha_bulk_control or ha_call_service, and provides a direct alternative: use ha_get_state for entity states. This leaves no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint and openWorldHint annotations, the description adds crucial caveats: the need for restart after installing integrations, browser cache clearing for Lovelace cards, the fact that removing an integration leaves the module loaded until restart, and the 48-hour refresh interval. This context is not inferred from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with a summary, examples, and caveats. Every sentence adds value, though it could be slightly tightened without losing critical information. It is not needlessly verbose for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All actions, parameter combinations, and edge cases are covered. The caveats address real-world operational concerns, and the presence of an output schema means return values need not be explained. The description is self-sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema documents each parameter, the description adds meaningful semantics: it maps actions to parameters, clarifies that repository_id accepts numeric or owner/repo, and explains that add_repository requires owner/repo plus a matching category. Concrete examples illustrate correct usage beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages HACS with specific actions: install/update, remove, add repositories, and refresh. It also distinguishes itself from the read-only sibling tool ha_get_hacs_info, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: it names ha_get_hacs_info as the alternative for search/read, and explains when to use each action (e.g., update_information to surface a recent release because HACS refreshes every ~48 hours). This goes beyond mere function listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true. Description adds: destructive actions need confirm=True, long-running actions start and return with long_running=true, and S2 secure inclusion is not scriptable. These details go beyond the annotation signal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is appropriately sized — three paragraphs with front-loaded purpose and distinction. Every sentence adds meaningful information; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple radios, many actions, destructive/long-running behaviors, and output schema existing), the description covers when to use, behavioral caveats, error handling (unknown action returns list), and non-scriptable cases. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value by explaining that an unknown action returns the supported list for that radio, and that params are action-specific (e.g., code, pin). This extra context justifies above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Manage Home Assistant radios — Z-Wave, Zigbee, Matter, and Thread' and distinguishes read-only inspection (prefer other tools) from write actions. It uses specific verb+resource and differentiates from sibling tools like ha_get_device and ha_get_system_health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (writes and ping probe) versus alternatives (read-only inspection via ha_get_device/h_get_system_health). Also provides caveats: destructive actions require confirm=True, long-running actions return immediately, and interactive S2 inclusion is not scriptable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint, idempotentHint), the description discloses detailed behavioral traits: the missing-target contract with specific error codes, idempotency at the contract level, and transient connectivity failures. It also warns about consequences on automations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (WHEN NOT TO USE, SUPPORTED HELPER TYPES, ROUTING, MISSING-TARGET CONTRACT, EXAMPLES, WARNING) and front-loads the purpose. However, it is quite lengthy; while necessary for completeness, it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (three mechanisms, error handling, routing), the description covers all necessary context: usage conditions, error contracts, examples, and a warning about side effects. It also mentions an output schema (presumably detailed elsewhere).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3, but the description adds significant value: it explains routing paths based on helper_type, provides examples for each case, details the target parameter options, and clarifies the confirm parameter. This goes well beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Remove a Home Assistant helper or integration config entry.' It distinguishes itself from siblings like ha_remove_entity and ha_remove_device in the 'WHEN NOT TO USE' section, and explains its unified backend mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives, including a 'WHEN NOT TO USE' section that directs to ha_remove_entity for entity-only removal and advises on YAML-configured helpers. It also details routing paths and includes examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: warns about automations, home zone restriction, and references ha_get_zone for ID lookup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise 5 sentences with example, warning, note. Well-organized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, prerequisites, limitations, side effects. Output schema exists, so return values not needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter with schema coverage 100%. Description adds value by explaining how to find zone_id via ha_get_zone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Remove a Home Assistant zone.' Distinguishes from siblings like ha_set_zone and ha_get_zone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides example, warning about automations, note that 'home' zone cannot be removed, and suggests using ha_get_zone to find IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and idempotentHint=true, so the agent knows it's safe. The description adds significant behavioral context: it returns large diagnostic data, includes log entries, and explains the `fields` parameter to manage response size. This goes well beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with headings, bullet points, and clear sections, front-loading critical information. However, it is quite long; while every sentence is useful, some details could be trimmed without losing clarity. Still, it is structured effectively for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's complexity and the presence of an output schema, the description covers all necessary context: how to choose the appropriate template, when to use the `fields` parameter, what diagnostic fields are available, and even hints about missing tools. It is fully complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the two parameters. The description adds substantial meaning: for `fields`, it lists all available keys and provides usage examples; for `tool_call_count`, it explains the default and maximum and the reasoning behind them. This greatly enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates diagnostic information and templates for filing issue reports or feedback, and it distinguishes between two specific report types (Runtime Bug Report and Agent Behavior Feedback). This sets it apart from all sibling tools, none of which are for reporting issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit conditions for when to use the tool with concrete examples (e.g., 'I want to file a bug', 'This isn't working', 'You should have used [other tool]'). It also instructs the agent to ask the user for clarification if the report type is unclear, effectively guiding the agent's decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnly and idempotent. Description adds critical behavioral details: partial results meaning, count vs total_matches, pagination mechanics, and warnings about incomplete results. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with headings and examples. Front-loaded with purpose. Some redundancy (keyword list at end) but overall efficient for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (15 parameters, two search surfaces, output schema exists), the description is exhaustive. Covers caveats, pagination, partial results, and usage patterns, leaving no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but description adds rich context, examples for each parameter (e.g., query usage patterns, fields projection, result_fields enrichment keys). Goes well beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for entities and config definitions in one call. It distinguishes from sibling tools by listing specific alternatives (ha_get_state, ha_config_get_*, ha_get_addon) for different use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use ('whenever you need to find something in HA') and when not to use, referencing specific sibling tools. Also explains conditions for config-body search being skipped, aiding correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and destructive hints; the description adds critical behavioral details: enabling/disabling is registry-level (requires reload), rename doesn't update references, label operations semantics, and multi-domain options handling. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, bullet points, and examples. Front-loaded with a clear summary. Slightly verbose due to many examples, but every section serves a purpose. Could be trimmed slightly, but still very effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all 15 parameters, bulk restrictions, warnings (enabled=False, rename propagation), and cross-references sibling tools. With output schema present, it provides comprehensive context for complex entity registry operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description still adds significant value: explains label_operation enum, device_class 'Show As' usage, options multi-domain handling, expose_to valid assistants, rename limitations, and device rename combination. Goes far beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update entity properties in the entity registry' and lists specific modifiable aspects (area, name, icon, etc.). It distinguishes from siblings like ha_get_entity (read), ha_remove_entity (delete), and ha_set_device (device-level) by focusing on entity registry properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly covers when to use (single vs bulk), when not to use (e.g., enabled=False for automations/scripts, alternatives provided via ha_call_service()), and includes examples for each operation. Clearly differentiates single entity and bulk operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, and the description adds important behavioral context: adding an integration runs the full HA config flow and 'may pair devices, scan the network, create entities,' and flows requiring browser steps (OAuth) error out with a structured error. These caveats go well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Despite being longer than most, the description is well-structured with clear headings (modes, when-not-to-use, caveats, examples) and a front-loaded one-sentence summary. Every section earns its place, and the length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and that an output schema exists, the description is complete: it covers all operation modes, exclusions, prerequisites, side effects, and failure cases. The agent has enough information to select and invoke the tool correctly without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with detailed descriptions, so baseline is 3. The description adds value by clearly explaining the three operating modes and how parameters combine (entry_id+enabled vs domain+config vs entry_id+config) and includes concrete examples. This goes slightly beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Manage an integration (config entry): enable/disable, add, or update options,' which precisely states the verb, resource, and scope. It clearly distinguishes the tool from sibling tools by specifying what it is not for (helpers, config subentries, removal).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes an explicit 'WHEN NOT TO USE' section that names concrete alternatives (ha_config_set_helper, ha_remove_helpers_integrations) and advises using ha_get_integration to find entry IDs and inspect schemas before updating, providing clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the single destructiveHint, the description discloses wait semantics (waits for state change), result compaction behavior (strips context, metadata, heavy attributes), return_response handling (returned once as top-level service_response), and restrictions on WebSocket commands (streaming/two-phase/service-invoking rejected). It also warns about token bloat when using verbose. This is rich behavioral context with no contradiction to the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but front-loaded with the core purpose and examples, then organized into clear 'Key behavior' and 'WebSocket command escape hatch' sections. Every block adds necessary detail for a complex 10-parameter tool—examples, behavior, escape hatches, and warnings—without redundancy. The markdown headings and code snippets improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 params, multiple execution modes), the description is complete: it explains the standard service calling pattern, the wait/compaction/return_response behaviors, and the ws_command alternative. With an output schema present, not explaining return values is acceptable; the description covers the decision-relevant context (when to use which parameter, limitations) thoroughly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 40% schema description coverage, the description compensates by explaining all key parameters: domain/service pattern, entity_id, data, wait, return_response, verbose, result_fields, result_attribute_keys, and ws_command. It provides concrete examples for each and clarifies interactions (e.g., result_fields disables default compaction). This goes far beyond the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Execute Home Assistant services to control entities and trigger automations.' It explicitly positions itself as the universal control tool and distinguishes from sibling tools like ha_get_state (check state) and ha_search (find entity IDs), and points to ha_get_skill_guide for detailed docs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance: use ha_get_state() to check values before changes, use ha_search() to find entity IDs, and use ha_get_skill_guide for service details. It also gives a specific when-not case: for WebSocket-only commands like repairing issues, pass ws_command instead of domain/service. This covers when, alternatives, and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint, but description adds value by listing label properties and explaining dual behavior (list vs fetch). No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, examples. Every sentence adds essential information without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity, full schema coverage, and presence of output schema, description is complete with usage, alternatives, and examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds meaning: omitting label_id lists all, providing it fetches specific. Also lists returned properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it gets label info, lists all labels or a specific one by ID. Differentiates from sibling tools like ha_config_set_label and ha_set_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use with or without label_id, provides examples, and mentions alternative tools for create/update and assigning labels.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds further behavioral detail: images are returned in native format, token usage can be reduced via width/height, and only cameras exposed to HA are accessible. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections: description, parameters, use cases, example, notes, related services. Front-loaded with main purpose. Every sentence adds value—no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description explains return format (JPEG/PNG/GIF), authentication, camera availability, and token optimization. Covers all essential aspects for correct invocation and expectation setting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% parameter description coverage, so the description must compensate. It lists all three parameters with explanations (entity_id format, width/height purpose to 'reduce token usage') and provides example values inline, greatly enriching the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource: 'Retrieve a snapshot image from a Home Assistant camera entity.' It specifies the exact action and target, and given the sibling list includes many other HA tool types, this tool is well-distinguished as the only one focused on camera snapshots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases (security, pet monitoring, etc.) and example usage with code. Also lists 'Related Services' that contrast with this tool (e.g., camera.snapshot saves to file), giving the agent 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and idempotent. The description adds rich behavioral context: pagination behavior, default limits, mode switching via device_id/entity_id, integration-specific return fields (e.g., ieee_address, node_id), and detail level effects. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections, examples, and formatting. It is concise yet comprehensive, using bullet points and code blocks efficiently. No unnecessary text; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's complexity (multiple modes, many parameters, integration specifics), the description covers all aspects: pagination, filtering, detail levels, single lookup, integration details, and even a pointer to a sibling tool (ha_manage_radio). With an output schema present, the description is more than complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description enhances every parameter with real-world examples and contextual meaning. It explains how device_id/entity_id switch modes, how detail_level affects output, and what integration values imply. Examples like ha_get_device(offset=50) clarify pagination semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves device information with pagination, distinguishing between listing devices and single lookup. It specifies coverage of Zigbee, Z-Wave, and Matter integrations. While not explicitly differentiating from siblings, the purpose is highly specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage patterns: list vs single lookup, pagination examples, filtering by area/integration, and detail levels. It also notes when to use ha_manage_radio for radio management, offering clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, openWorld, idempotent. Description adds critical caveats: GitHub rate limits for info action, local cache for search, and format for repository_id. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with overview, usage guidance, dashboard tip, examples, and caveats. Every sentence adds value without redundancy. Efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, two modes, and existing output schema, description covers all necessary aspects: behavior, parameter details, constraints, and integration with ecosystem. Complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds substantial value beyond schema: explains actions, provides dashboard tip, examples, and caveats for repository_id. Demonstrates parameter usage effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves HACS data with two actions (search and info). It distinguishes from sibling tools like ha_manage_hacs for installation and non-HACS domain-specific tools, providing a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use search vs info, and when not to use this tool (e.g., for installation, use ha_manage_hacs; for non-HACS entities, use other tools). Includes a dashboard tip and examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true, but the description adds significant behavioral context: data retention durations (10 days for history, permanent for statistics), client-side slicing of limit/offset, per-entity application of pagination, and the fact that order is ignored for statistics. This goes well beyond the annotations to fully disclose tool behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for sources, shared/history/statistics params, warnings, and examples. It is front-loaded with the core purpose, uses bullet points for readability, and every sentence provides useful information. Despite its length, it is concise and avoids redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (two data sources, pagination, multiple parameter interactions), the description covers all essential aspects: default time ranges, offset limitations, client-side slicing, order behavior, and examples for both modes. With an output schema present, no further detail on return values is needed. The description is fully complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema already has 100% description coverage, the description adds substantial meaning by explaining parameter behavior across sources, providing defaults, and offering examples that illustrate parameter combinations. It clarifies interactions like limit and offset per entity, and which parameters are ignored in each mode, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves historical data from Home Assistant's recorder, specifying two distinct sources ('history' and 'statistics') and their use cases. This distinguishes it from sibling tools like ha_get_state or ha_get_entity, which handle current state or entity configuration. The purpose is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance for each source, with concrete examples like 'Troubleshooting why a value changed' for history and 'Tracking long-term trends beyond 10 days' for statistics. It also includes warnings about limit/offset behavior, offset constraints with multiple entities, and pagination hints, making it clear when and how to use the tool correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that snapshot restore restarts HA, snapshot delete is disabled by default with multiple safety layers (minimum age, not newest, not scheduled), progress heartbeats during large creation, and that edits restore creates a safety snapshot first. Adds extensive detail beyond the destructiveHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Despite length, the description is well-structured with a clear summary, table mapping scope+action to behavior, usage guidelines, special case notes, and examples. Every sentence adds value and is efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all (scope, action) combinations, safety guards, toggle behaviors, parameter usage, and provides comprehensive examples. With an output schema present, it does not need to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the 100% schema coverage, explaining parameter formats (e.g., backup_name format '<domain>.<entity_id>.<timestamp>.yaml'), the role of confirm, filtering by domain/entity_id, bulk-delete behavior of older_than_days, and the restore_database option.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it manages both full HA snapshots and per-edit auto-backups, distinguishing two scopes with specific actions. It differentiates from sibling tools (e.g., ha_config_set_automation) by focusing exclusively on backup operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Dedicated 'When to use which scope' section explicitly advises using 'edits' for undoing agent edits and 'snapshot' for system-wide recovery, and notes when the tool is not needed. Provides explicit guidance on when to use each action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that action='set' only changes the backend-selected default, not user-specific choices, and that theme names are validated at call time. Annotations indicate destructiveHint=true and idempotentHint=true, which align with the described behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (When NOT to use, When to use, Caveats, Examples). It is concise, front-loaded with purpose, and every sentence contributes valuable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, 100% schema coverage, output schema present, annotations provided), the description covers all necessary guidance: use cases, constraints, caveats, and examples. It is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are fully described in the schema (100% coverage). The description adds context: mode defaults to light, theme_name can be 'default' or 'none', and examples illustrate usage. This provides meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Manage Home Assistant frontend themes' and explains the two actions (list and set). It explicitly distinguishes from sibling tools like ha_manage_hacs and ha_config_set_yaml, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'When NOT to use' and 'When to use' sections, stating that themes are YAML files not creatable via API and that community theme installation goes through HACS. It also provides examples for each action scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/homeassistant-ai/ha-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server