hass-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation3/5
There are several overlapping tools for entity queries (list_entities, search_entities_tool, get_entities_by_area, domain_summary_tool, system_overview) and history (get_history, get_history_range, get_statistics, get_statistics_range). While each has a distinct primary purpose, the entity discovery/query tools especially overlap in what an agent might use to 'find entities,' requiring careful reading of descriptions to pick correctly. Dashboard tools and service/entity_action tools are more clearly distinct.
Naming Consistency3/5
Naming is inconsistent: many use snake_case verbs (list_entities, get_entity, add_card, remove_view) but several use different patterns: call_service_tool, entity_action, search_entities_tool, domain_summary_tool, system_overview, restore_dashboard, list_dashboard_backups. Mixed conventions like search_entities_tool/suffix '_tool' and camelCase-less words like 'system_overview' create inconsistency, though most are readable.
Tool Count3/5
29 tools is on the heavy side. The dashboard CRUD cluster (add_card, update_card, remove_card, move_card, add_view, remove_view, update_view, list_view_sections, restore_dashboard, set_dashboard_config, get_dashboard_config) plus history/statistics tools and system overview tools make the surface feel broad. While each tool serves a real purpose, the count is approaching the upper bound where agents may struggle to select among many options.
Completeness4/5
Core coverage is strong: entity reads, writes, service calls, dashboard CRUD with backups and restore, history and statistics queries, plus system diagnostics. Minor gaps: no explicit entity create/delete (though call_service_tool can cover some), no persistent state management, and no dashboard section mutation beyond listing. But the lifecycle for the stated domain (entity control, dashboard editing, history) is well covered.
Average 4.3/5 across 29 of 29 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 5 commits in the last 12 weeks
- No stable releases found
- 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.json to 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

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description makes the mutation explicit ('Replace a card') and mentions a dry_run preview, but there are no safety annotations, and it does not warn that replacing a card in a live dashboard may be destructive or irreversible. It also doesn't mention permissions or failure/success side effects beyond returning a backup_id.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a tight bulleted list, front-loads the main action, and every sentence adds cardinal-dashboard contextual junk; no filler or restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 params, 0 annotated, no annotation guidance, and live dashboard mutation risk, the description doesn't specify edge cases, side effects, concurrency with sibling tools (add_card, remove_card, move_card). Output schema + describes backup_id/dry_run result, which helps. It doesn't define implications on live dashboards, backup/restore behavior, or failure settings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides plain-language meaning for all six parameters: url_path, view (target index/path/title), card_index, card (new config dict), section, dry_run. It adds necessary constraints (e.g., card mustodeline requires a string 'type') and explains dry_run behavior beyond the raw schema. But it doesn't give detailed value formats or examples for nested object shapes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Replace') and resource ('a card in a dashboard view'), which is clear and mostly distinct from sibling tools like add_card and move_card. It could more strongly differentiate itself from update-style tools, but the core purpose is identifiable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists arguments and explains required fields (e.g., 'card' must include a string 'type'), and clarifies that 'section' is required for sections views. However, it does not explicitly state when to choose this tool over alternatives (e.g., add_card, move_card), nor does it note when not to use it.
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?
No annotations are provided, so the description carries the burden. It mentions 'live' in the title, indicating the operation is immediate, and mentions dry_run for preview. It also notes that the return includes a 'backup_id' or a dry-run preview, which is useful. However, it doesn't disclose potential side effects (e.g., whether the operation is reversible, if it affects other cards' indices, or if it requires specific permissions). The description adds some value but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It starts with a one-line summary, then lists parameters with brief explanations, and ends with a return description. It's front-loaded with the main purpose. No fluff, but it could be slightly more compact by integrating the return description into the summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, all optional, and an output schema. The description covers the parameters and return value, but given the complexity of reordering cards (e.g., what happens to indices, how sections work), it could be more complete. It doesn't explain the behavior of indices (e.g., whether new_index is relative or absolute, if it shifts other cards). The output schema exists, so return values are partially covered, but the description could add more context on the operation's effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does explain each parameter in the Args section: url_path, view, card_index, new_index, section, and dry_run. It clarifies that section is required for sections views and that dry_run previews without saving. This adds meaning beyond the schema, which only provides types and defaults. However, it doesn't provide examples or edge cases, so it's adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Reorder a card within a dashboard view (live)'. It specifies the action (reorder) and the resource (card within a dashboard view), and distinguishes it from sibling tools like add_card, update_card, and remove_card. However, it doesn't explicitly contrast with these siblings, so it's not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context by listing parameters and noting that 'section' is required for sections views, and that dry_run previews without saving. However, it doesn't explicitly state when to use this tool versus alternatives (e.g., when to use update_card instead) or provide exclusions. The guidance is implied through the parameter descriptions but not explicit.
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?
No annotations are provided, so the description carries the burden of behavioral disclosure. The description does mention the return value type (a string) and provides an example format, which is helpful. However, it does not disclose any potential side effects (unlikely), authentication requirements, or error behavior. For a simple read-only tool, this is somewhat acceptable, but it could be more explicit about being a read-only, non-mutating operation. With no annotations, a score of 3 is reasonable as the description adds value by specifying the output format, but it lacks deeper 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one line stating the purpose and one line describing the return value with an example. Every sentence earns its place. It is front-loaded with the purpose, making it easy for an agent to quickly understand what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is extremely simple: no parameters, no complex logic, and it has an output schema. The description is complete enough for an agent to understand what it does and what it returns. However, it lacks any guidance on when to use it (e.g., 'Use to verify connectivity' or 'Use before version-specific calls'). Given the complexity is low, this is nearly complete, but a small piece of usage context would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100% (auto). The description doesn't need to explain parameters. It does add meaning by describing the return value and providing an example, which is beneficial given the tool's simplicity. With no parameters, the baseline is 4, and the description meets that baseline by clarifying the output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to get the Home Assistant version. It uses a specific verb and resource, and it's distinct from the sibling tools (e.g., system_overview, get_error_log). The description could be improved by explicitly stating that it returns the core version string of Home Assistant, but the purpose is evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any specific context or prerequisites. For a simple version-check tool, some implied usage exists (e.g., checking compatibility before calling other tools), but it is not explicit. Given the sibling tools like system_overview or restart_ha, it might be useful to note that this tool is a lightweight way to confirm the Home Assistant instance is accessible and its version.
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?
No annotations are provided, so the description carries the full burden. It discloses the return structure and offers practical advice (e.g., keep hours 24-72 for token efficiency), but it does not explicitly state that the operation is read-only, what happens on invalid entity IDs, or any rate limits. This partial disclosure warrants a middle score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into Args, Returns, Examples, and Best Practices, with the core purpose front-loaded. It is slightly verbose in the return section, but every sentence adds useful context and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with a 2-parameter schema, the description covers purpose, parameters, output structure, examples, and performance guidance. However, it omits error conditions and does not clarify how this tool differs from the sibling get_history_range, leaving a contextual gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining entity_id and hours, including the default value and example usages. This goes far beyond the schema field names and provides clear operational semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the history of an entity's state changes' with a specific verb and resource, and the arguments define the scope. It does not explicitly contrast with the sibling get_history_range, so it cannot earn a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides 'Best Practices' about entity types and token efficiency, but it never states when to use get_history versus the alternative get_history_range or get_statistics. Without explicit exclusionary or alternative guidance, usage context remains unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description is the sole source of behavioral disclosure. It mentions the action and return value but does not disclose side effects, required permissions, error behavior for invalid actions or missing entities, or whether the operation is reversible. For a mutation tool, this is a safety-relevant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a one-line summary, argument breakdown, return statement, examples, and domain-specific details. It remains scannable, though the domain-specific section slightly duplicates what the examples already show (e.g., brightness appears in both). No unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description thoroughly covers parameter semantics but leaves important gaps: the return value is vaguely 'The response from Home Assistant', error and edge-case behavior is absent, and it does not clarify when to use this versus call_service_tool. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only source of parameter meaning. It explains each argument, provides concrete entity_id examples, enumerates valid action values, defines params as an optional dictionary, and gives domain-specific parameter details (brightness, temperature, position, etc.) — far exceeding the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence clearly states the tool's function: 'Perform an action on a Home Assistant entity (on, off, toggle)'. The examples with entity_id and action values make the scope unmistakable, and the domain-specific parameters distinguish it from read tools like get_entity and the broader call_service_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The examples and domain-specific parameter list imply usage contexts (lights, covers, climate, media players), but the description never explicitly compares this tool to sibling call_service_tool or states when to prefer one over the other. The usage guidance is mostly inferred rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the full burden of behavioral disclosure. It mentions 'low-level API access' but does not disclose potential side effects, permissions, reversibility, or error handling. Given the generic nature of the tool, this is insufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections (Args, Returns, Examples). It avoids unnecessary verbosity while providing essential usage information, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic service-call tool, the description provides sufficient context: what the tool does, how to use parameters, what to expect in the return value, and clear examples. It does not cover edge cases or failure modes, but given the broad scope ('any service'), the level of detail is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains each parameter (domain, service, data) with examples, adding meaning beyond the bare schema (which only has titles). It clarifies how to structure the data dictionary, though it does not exhaustively list allowed service names or data fields, which is reasonable for a generic tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: 'Call any Home Assistant service (low-level API access)'. It identifies the verb (call) and the resource (Home Assistant service), and distinguishes itself from sibling tools that are more specific (e.g., list, get, update).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples of usage but does not explicitly state when to use this tool versus more specific sibling tools. It implies it is a catch-all for services without dedicated tools, but this is not explicitly stated, leaving some ambiguity.
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?
No annotations are provided, so the description must convey side effects. It mentions 'remove' (implying destructive action) and includes a 'dry_run' parameter and a 'backup_id' in returns, which add transparency. However, it does not explicitly state irreversibility, permissions, or rate limits, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description starts with a concise one-sentence purpose, followed by a structured Args and Returns section. It is appropriately sized, though the Args list is somewhat lengthy; however, the structure is clear and front-loaded with the primary function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool of this complexity, the description is complete: it covers the action, parameters, and returns, and includes necessary edge-case details like 'Required for sections views'. It does not delve into broader dashboard context, but that is not essential for usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lists parameters without descriptions, but the description's Args section explains each parameter in detail (e.g., 'url_path: Dashboard URL path, or None for the default dashboard'). This fully compensates for the schema's lack of descriptions, covering all five parameters with meaningful context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: removing a card from a dashboard view. The verb 'remove' is specific and the resource 'card' is well-defined, distinguishing it from sibling tools like update_card or move_card.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It hints at parameter usage (e.g., 'section required for sections views') but does not compare with other tools or give selection criteria, leaving the decision to the agent.
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?
No annotations are provided, so the description must carry the burden of disclosing behavior. It states it returns a list of dictionaries with specific fields, which is useful. However, it does not mention that the operation is read-only (implied but not stated), any performance implications, or potential for large result sets. The description adds minimal behavioral context beyond the return structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description has redundancy: the first sentence 'Get a list of all automations' is repeated by 'This function retrieves all automations'. The 'Examples' section is not an example but a restatement of behavior. The Returns section is informative, but the overall structure could be more efficient without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no nested objects) and availability of an output schema, the description provides sufficient coverage: it states exactly what it returns and the fields included. It lacks details like ordering or pagination, but these are likely irrelevant for a list of automations. The description is complete enough for an agent to understand the tool's function and output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100% (vacuously). The description correctly omits parameter details since there are none. According to the calibration, a baseline of 4 is appropriate for 0 parameters, and the description does not need to compensate for anything missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the verb ('Get a list') and the resource ('all automations from Home Assistant'). The second sentence reinforces the scope and includes specific fields ('IDs, entity IDs, state, and display names'). This distinguishes it from sibling tools like list_entities or list_dashboards, which target different resource types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly communicates that this tool is for automations, not other entities, which distinguishes it from sibling tools. However, it does not explicitly state when not to use it or provide alternative guidance. Given the simplicity of the tool, the implied context is adequate but not fully explicit.
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 operation saves (with backup_id) and that dry_run prevents saving, providing behavioral context beyond annotations. It does not mention side effects like overwriting or restrictions, but given no annotations, this is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is clear and front-loaded with a one-line purpose, then an Args block. It is concise without explaining every schema detail, and each sentence earns its place. Slightly verbose but appropriate for 4 params.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, output schema exists), the description covers all parameters with examples and notes the return behavior (backup_id or preview). It lacks when-to-use guidance, but overall is sufficiently complete for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain params. It does: url_path (None for default), view_config (with example), position (insert index, default append), dry_run (preview without saving). This adds meaning beyond bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add a new view to a dashboard (live)' clearly states the action (add), the resource (new view to a dashboard), and the 'live' qualifier distinguishes it from a dry-run operation. It is specific and distinct from sibling tools like add_card or remove_view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you want to add a view) but does not explicitly state when to use it over alternatives or provide exclusion criteria. No mention of prerequisites or alternative tools, making it adequate but not explicit.
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?
No annotations are provided, so the description carries the full burden. It explains that aggregated bucket data survives the short-term retention window, which is useful. However, it does not disclose potential errors (e.g., if entity is not statistics-tracked beyond a general note), rate limits, or whether this is a read-only operation. Since the context implies a read-only query, but no explicit statement is made, the transparency is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, args, returns, and examples. It is detailed but not bloated. It includes exactly the necessary information without repetition. The only minor issue is the extra line about retention, which is useful but could be seen as slightly beyond essential, but it still earns its place. Overall it is efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a moderate complexity with 4 parameters, an output schema exists, and no annotations. The description covers the essential context: what it does, parameter semantics, examples, and a comparison to a sibling. The only missing piece is explicit error conditions or limitations (e.g., what if end_time is before start_time), but the provided info is sufficient for most use cases. Given the presence of an output schema, the description doesn't need to explain return values in detail. It is complete for a typical agent's needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides definitions for all four parameters: entity_id ('must be statistics-tracked'), start_time (ISO-8601 format with UTC default), end_time (defaults to now), and period (lists valid values). The examples also illustrate usage. This adds value beyond the schema, which only has titles. However, it doesn't add details like end_time inclusion/exclusion semantics or period effect on output granularity, so a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Get long-term aggregated statistics for an entity over a date/time range.' It names the resource (statistics for an entity) and the action (retrieve over a range), and distinguishes itself from the sibling `get_statistics` by clarifying it uses an explicit window. This clearly separates it from other tools like `get_history_range`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear comparison to `get_statistics` (same data source but with explicit window) and includes concrete use case examples ('what was my power usage from Jan 1 to Jan 31?'). It also notes the data survival beyond short-term retention, implying when to use this tool for historical data. While it doesn't explicitly say 'when not to use', the contrast with `get_statistics` and the focus on long-term range queries provide strong guidance.
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?
With no annotations provided, the description must convey the tool's behavior. It states it returns a summary, which implies a read-only operation, but it does not explicitly mention that it is non-destructive, any side effects, or permissions required. Given the read-only nature, a 3 is appropriate as it covers the essential behavior but lacks explicit guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-organized. It includes the purpose, parameter descriptions, return structure, an example, and a best practice—all in a compact format with no unnecessary verbiage. The structure is clear and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, arguments, return values, and a usage example, which is sufficient for a simple summary tool. It does not discuss error handling or edge cases, but these are not critical for the tool's primary function. The return structure is described in the 'Returns' section, making the output expectations clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are explained in the description: 'domain' is described as 'The domain to summarize' with examples, and 'example_limit' as 'Maximum number of examples to include for each state.' This provides sufficient meaning beyond the raw schema, though the concept of 'state' is not elaborated further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get a summary of entities in a specific domain.' It uses a specific verb ('get') and resource ('summary of entities'), and is distinct from sibling tools like list_entities or get_entity by focusing on aggregated summary data rather than individual records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a specific best practice: 'Use this before retrieving all entities to understand what's available.' This gives clear guidance on when to use the tool, though it does not explicitly mention when not to use it or compare with alternative tools. The example also demonstrates typical usage.
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?
With no annotations provided, the description carries the behavioral burden. It discloses the significant side effect of disrupting all operations and states the return type, which is key information for an agent deciding to invoke 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, containing only the essential elements: action, warning, and return. No redundant or extraneous text, and the structure is clear with a labeled warning and return.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behavior (restart), the side effect (temporary disruption), and the return (result). Given the tool's simplicity and lack of output schema, this is sufficiently complete without being verbose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description's silence on parameters is appropriate. According to the rubric, a baseline of 4 applies when no parameters exist, and no additional explanation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Restart Home Assistant') using a verb+resource format, and it is distinct from all sibling tools which focus on dashboards, entities, and other specific operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The warning about temporary disruption implies a maintenance context, but there is no explicit statement of when to use this tool versus alternatives (e.g., when a restart is needed vs. other recovery actions). The guidance is implicit rather than explicit.
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?
With no annotations provided, the description carries the full disclosure burden and largely succeeds: it reveals the non-obvious parent-device inheritance behavior, case-insensitive matching, and the meaning of the lean parameter's token efficiency. It clearly describes the return structure. Only minor gaps remain (e.g., behavior for nonexistent areas, pagination), keeping it just short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a one-line summary followed by standard docstring sections (Args, Returns, Examples) that are easily scannable. It is slightly verbose for a tool description, but every section earns its place, and the examples are instructive without being padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter query tool, the description is thorough: all parameters are documented with extra semantics, the return structure is specified, behavioral edge cases (inheritance, case folding) are covered, and actionable examples are provided. With an output schema available, nothing material is left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description must compensate — and it does thoroughly. It adds case-insensitivity semantics to 'area', clarifies 'domain' as a secondary filter with an example, and explains 'lean' as producing 'token-efficient entity records.' The examples further demonstrate parameter composition, adding meaning well beyond the bare boolean/string types in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
"Get all entities assigned to a specific Home Assistant area (room)" uses a specific verb+resource and clearly scopes the operation to area-based lookups, distinguishing it from siblings like get_entity (single entity), search_entities_tool, and domain_summary_tool. The opening line is immediately identifiable in purpose with no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides solid functional context (case-insensitive matching, parent-device inheritance) but never explicitly guides tool selection versus overlapping siblings like search_entities_tool, list_entities, or domain_summary_tool. Usage is implied through the detailed behavior rather than stated — no when-to-use or when-not-to-use guidance or named alternatives.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains optional field filtering, the meaning of detailed=True, and provides concrete examples. It does not discuss error behavior or permissions, but for a simple read-oriented getter the core behavior is transparently described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence summary, followed by a compact Args section and three illustrative examples. Every sentence adds value, and the structure makes the tool's behavior immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters, no output schema, and no annotations, the description covers the main usage patterns and return behavior reasonably well. It could be more explicit about the exact shape of the response for a basic state check, but the examples and detailed flag explanation make it sufficiently 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does thoroughly. Each parameter is explained with type context and examples: entity_id is shown as 'light.living_room', fields as ['state', 'attr.brightness'], and detailed is described as returning all fields without filtering. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get the state of a Home Assistant entity with optional field filtering.' This clearly distinguishes it from sibling tools like list_entities or search_entities_tool, which operate over collections rather than a single entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single entity's state, and examples clarify common calls, but it does not explicitly state when to prefer this tool over alternatives like list_entities or get_entities_by_area, nor does it mention exclusions. Usage guidance is only implied, not explicit.
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?
No annotations are provided, so the description carries the full transparency burden. It discloses that backups are written automatically before every dashboard write, flags the Docker volume-mount caveat, and specifies the return order ('oldest first'). This adds meaningful behavioral context beyond the schema and purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: purpose, mechanism, caveat, args, and returns each occupy one focused sentence or section. No redundant phrasing or repeated schema information exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one optional parameter and a provided output schema, the description covers the purpose, the backup generation behavior, a deployment-specific caveat, the parameter semantics, and the return shape. It provides enough context 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully documents the sole parameter: 'Dashboard URL path, or None for the default dashboard'. This clarifies both the meaning and the default behavior, compensating well for the sparse input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-plus-resource statement: 'List on-disk backups of a dashboard's config'. It clearly scopes the tool to on-disk backup listing and distinguishes it from sibling tools like restore_dashboard or get_dashboard_config.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied rather than explicit: the automatic-backup note suggests this tool is for inspecting backups before writes or restores, but no direct alternatives, exclusions, or 'use this when' guidance is provided. The purpose is clear enough, but the description does not name siblings or when-not-to-use scenarios.
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?
No annotations are provided, so the description carries the full burden. It explains the return structure in detail (dictionary with keys) and notes that area distribution is included 'if available'. While it doesn't disclose any side effects or performance implications, for a read-only overview tool this is adequate; a slight deduction for not noting potential size or latency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Returns, Examples, and Best Practices sections, and it is appropriately sized for the complexity. It is not overly verbose, but the 'Examples' line is redundant with the 'Returns' section, which costs one point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no parameters and an output schema is present, so the description's role is largely to explain the output semantics and usage context. It does both excellently: it enumerates all returned fields and gives clear guidance on when to use it. The output schema covers the structure, and the description adds the 'if available' nuance and the workflow suggestion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no param semantics to document. The description adds value by explaining the return structure, which the input schema cannot do. Baseline for 0 params is 4, and the description fully compensates by detailing what the output contains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb and resource: 'Get a comprehensive overview of the entire Home Assistant system.' It distinguishes from siblings by explicitly positioning it as the first call for exploration, and it lists the returned fields, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The Best Practices section explicitly says to use it as the first call when exploring an unfamiliar instance and to then use domain_summary_tool for deeper dives. However, it doesn't explicitly state when not to use it or name alternatives beyond domain_summary_tool, though 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?
With no annotations provided, the description carries the full disclosure burden and does so well: it details the return structure (url_path, title, mode), flags the edge case of None for the default 'Overview' dashboard, and documents the storage/yaml mode semantics. It adds genuine behavioral context beyond what a mere schema would reveal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a one-line action statement followed by a compact Returns block. Every sentence earns its place, covering the output schema, the default-dashboard edge case, and the editability constraint in three short lines with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter listing tool with an output schema present, the description is complete. It goes beyond the minimum by explaining the semantic meaning of fields (None url_path, mode values) and the critical implication for editing, which fully equips an agent to use the results in downstream tool calls.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes 0 parameters with 100% schema coverage, so the description needs to add nothing on parameter syntax. The description still adds value by explaining the meaning of the 'mode' values that would come back in results, which is appropriately assigned the baseline of 4 for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Home Assistant dashboards (Lovelace)' uses a specific verb+resource construction and adds the '(Lovelace)' disambiguator, which differentiates it from siblings like get_dashboard_config. The purpose is immediately clear and distinct from the other 30+ sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when this tool matters by noting that only 'storage'-mode dashboards can be edited via these tools, implicitly guiding when an agent would use this vs reading config. It lacks explicit 'use X instead' alternatives, but the mode distinction effectively frames the decision boundary for which dashboards are actionable.
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?
No annotations are provided, so the description carries the full burden. It discloses that search_query does not support wildcards, that default returns lean formatting, and that detailed=True returns all fields. It also notes that to get all entities, leave search_query empty. This is good behavioral context, though it doesn't mention pagination or rate limits, which are not critical for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for Args, Returns, Examples, and Best Practices. It is front-loaded with the core purpose and then provides details. It is slightly verbose with the best practices section, but each sentence adds value. The examples are concise and illustrative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 optional parameters, no required ones) and the presence of an output schema, the description is fairly complete. It covers parameter semantics, return format (lean vs detailed), and usage guidance. It could mention the output schema's structure, but the output schema itself provides that. The description adequately prepares the agent for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains each parameter's purpose: domain, search_query (with wildcard note), limit (default 100), fields, and detailed. It also provides examples showing parameter combinations. This adds significant meaning beyond the schema, though it could be more explicit about the fields parameter's format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get a list of Home Assistant entities with optional filtering.' It specifies the resource (Home Assistant entities) and the action (list), and distinguishes it from siblings like search_entities_tool and domain_summary_tool by mentioning filtering and domain overviews.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it includes best practices such as 'Prefer domain filtering over no filtering' and 'For domain overviews, use domain_summary_tool instead of list_entities.' It also explains when to use detailed=True and how to get all entities, which helps the agent choose between this and alternatives.
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?
With no annotations, the description carries the safety burden. It explicitly warns 'Removes the view and all its cards,' mentions dry_run for previewing, and notes the returned backup_id, giving an agent risk awareness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: a clear headline, a concise warning, then an Args/Returns breakdown. No filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive 3-parameter tool, it covers all arguments, the destructive consequence, and the backup/dry-run result. It could additionally mention restore_dashboard as the undo path, but the provided context is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are 0% covered, so the Args section is the sole semantic source. It explains url_path default behavior, view matching by index/path/title, and dry_run's preview semantics, adding substantial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') and resource ('view from a dashboard'), and the warning 'Removes the view and all its cards' clarifies scope. This distinguishes it from sibling tools like remove_card and update_view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The opening line states the operation clearly and the dry_run parameter gives a preview/safety path, which is an implicit usage recommendation. It does not explicitly name alternative tools for removing only cards or restoring backups.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the return value (a dict with a top-level 'views' list) and the edge case of no stored config (returns an empty scaffold with a note). This is adequate for a read-only getter, though it doesn't discuss error states or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences) and well-structured with 'Args:' and 'Returns:' sections. Every sentence adds value without redundancy. It is front-loaded with the key purpose and then provides necessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single optional parameter) and the presence of an output schema, the description is complete. It describes the return structure, the default behavior, and the fallback for missing config. No critical information is missing for a getter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the url_path parameter with an example ('my-dash') and its purpose (dashboard's URL path). This adds significant meaning beyond the raw schema, which only specifies type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get a dashboard's full configuration'. This is a specific verb + resource that distinguishes it from sibling tools like set_dashboard_config (set vs get) and other dashboard manipulation tools (add_card, update_card).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on the url_path parameter, including the convention for the default dashboard ('Omit or pass None for the default Overview dashboard'). While it doesn't explicitly contrast with alternatives, the purpose is unambiguous given the tool's getter nature.
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?
With no annotations, the description carries the behavioral burden. It discloses the return shape (list of {index, title, heading, card_count}) and a key error condition ('Errors if the view is not a sections view'). It does not explicitly state read-only behavior, but 'List' strongly implies no mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear summary, usage rationale, parameter explanations, and return/error behavior. Every sentence contributes value, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with two optional parameters, the description covers purpose, when to use it, parameter semantics, return format, and error behavior. The presence of an output schema reduces the need to detail return values further, and nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It explains `url_path` as the dashboard URL path or None for the default dashboard, and `view` as the target view by index or matching path/title. This adds meaning that the raw schema does not provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('List the sections of a sections-type dashboard view') and resource. It also distinguishes this tool from siblings by explaining that sections-type views store cards inside sections, not a top-level card list, which is important context for card tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: use it to discover which section to target with the card tools' `section` argument. It implies this is not for non-sections views, but it does not name explicit alternatives or enumerate when not to use it.
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?
No annotations are provided, so the description carries the transparency burden. It discloses a key safety trait: 'The current config is itself backed up first, so a restore can be undone,' and explains dry_run as a preview without saving. It does not cover failure/error cases or permissions, but the main behavioral risks are addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line purpose, a short behavior paragraph, then clearly labeled Args and Returns sections. Every sentence adds information, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter tool with an output schema and no annotations, the description covers the essential context: default behavior, parameter meaning, dry-run capability, reversibility, and return-value shape. It is enough 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining all three parameters: url_path defaults to the default dashboard, backup_id defaults to the newest backup, and dry_run previews without saving. This adds meaning well beyond the raw property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Restore a dashboard from a backup (live).' It clearly distinguishes this tool from siblings like list_dashboard_backups or set_dashboard_config by focusing on restoring a previously saved backup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear behavioral context: restores the most recent backup unless backup_id is supplied, and explicitly references list_dashboard_backups as the source for valid IDs. It does not explicitly enumerate when-not-to-use alternatives, but the restore-vs-edit distinction is strongly 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?
With no annotations provided, the description carries the full burden. It discloses that changes are applied 'live', preserves cards unless changes contains a cards key, returns a backup_id (indicating backups), and supports dry_run. It does not detail permission requirements or error handling, but the key behaviors are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinctly structured with a one-line summary, a critical preservation note, a clear Args list, and a Returns section. Every sentence adds value; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 4 parameters, no annotations, and no schema coverage, the description fully compensates by explaining every parameter, the return format (backup_id or dry-run preview), and a key behavioral nuance (card preservation). The presence of an output schema reduces the need to detail return structure further, and the description is complete for an update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains each parameter in the 'Args' section: url_path (default dashboard), view (index or path/title match), changes (merge dict with example), and dry_run (preview). This adds meaning far beyond the schema, which only provides types and defaults. The example clarifies the changes format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'view's properties' with examples (title, path, icon). It distinguishes from siblings like add_view and remove_view by focusing on modifying an existing view's properties. The parenthetical '(live)' adds immediacy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating existing views and provides a critical nuance about cards preservation unless intentionally overridden. It also mentions dry_run for previewing. However, it does not explicitly state when to use this tool versus alternatives like add_view or set_dashboard_config, though the sibling names make it inferable.
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?
With no annotations, the description carries the burden of explaining behavior. It discloses the return structure, the lack of wildcard support, and the effect of leaving query blank, but does not explicitly state read-only nature, though it is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with sections for args, returns, and examples. It is somewhat detailed but each part adds value, making it appropriately concise without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the lack of annotations, the description is remarkably complete. It covers functionality, parameters, return format, limitations, and alternatives, leaving little ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning to both parameters: query is explained as matching against IDs, names, and attributes, and limit is defined as a maximum result count with a default. It also clarifies edge cases like blank query.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: searching for entities by a query string. It also differentiates from sibling tools like list_entities by explicitly noting the alternative for retrieving all 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool, including a note about wildcard limitations and a clear alternative (list_entities) for fetching all entities. Examples illustrate 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?
Fully discloses the behavioral implications: overwrites entire dashboard, updates every open browser live, backs up first, requires admin token, and only works on storage-mode dashboards. Also explains dry_run behavior. Since no annotations exist, this description carries the full burden and meets 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is somewhat verbose but every sentence adds value—warnings, parameter details, and return value explanation. It's well organized with clear separation for parameters and returns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a full-replacement operation with dry_run and backup behavior, the description covers all necessary context: return values for both save and dry_run modes, prerequisites (admin token, storage-mode), and side effects (live browser updates).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are explained: url_path (default for default dashboard), config (complete new config with views list), dry_run (validate without saving). The description provides clear meaning beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Replace a dashboard's full configuration'. It distinguishes itself from siblings like get_dashboard_config, restore_dashboard, and partial edit tools (add_card, update_card) by emphasizing it's a full, low-level replacement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to use: it's a low-level full replacement, warns about overwriting, mentions restore_dashboard for undo, and notes the storage-mode requirement. It implies partial edits should use other tools, though it doesn't explicitly contrast with all 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?
With no annotations, the description takes full responsibility for behavioral disclosure. It states the operation is 'live' (a mutation), mentions that it returns a backup_id (suggesting reversibility), and describes dry_run behavior. This is rich, useful context beyond mere parameter definitions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-line summary, a clear Args list, and a Returns section. Although it is relatively long, every sentence earns its place given the six-parameter complexity. The format is scannable and informative without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all six parameters, explains return values ('Save result with a backup_id, or a dry-run preview'), and addresses edge cases like sections views and default dashboards. It is complete for a tool of this complexity, especially with an output schema present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description is the sole source of parameter meaning. It explains each parameter in detail, including the card config example, view matching by index/path/title, position semantics, and section requirements. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add a card to a dashboard view (live)' with a specific verb and resource. It distinguishes itself from sibling tools like update_card, remove_card, and move_card by focusing on the creation aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides useful usage context, such as 'section is REQUIRED for sections views' and references list_view_sections for discovering sections. Also mentions dry_run for preview. However, it does not explicitly compare with alternatives like update_card or remove_card, leaving some ambiguity about when to prefer 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?
With NO annotations, the full burden falls on the description — and it delivers. Key subtleties are disclosed: 'All filters are optional and combine (AND semantics)', and stats 'are computed over the filtered output so they match what's returned' (prevents the classic off-by-one confusion of counts vs. full log). Case-insensitivity is noted per filter, the return dict is fully documented including the `error` key for failure, and the Examples clarify default behavior with no args.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Perfectly front-loaded single sentence, then a logical docstring structure: semantics → Args → Returns → Examples → Best Practices. Every section earns its place — the 'AND semantics' and 'computed over the filtered output' notes are exactly the kind of non-obvious detail an agent needs. It's long, but at this density, the length is information-carrying, not waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-optional-param read-only tool, the coverage is exhaustive: parameter semantics, return-value structure, error key, and 5 concrete usage examples. Covers edge considerations like token efficiency when scanning long-running HAs. Given a documented return schema (output_schema exists) the returns section reaffirms rather than compensates. The only marginal gaps (e.g., rate limits, auth scope) are not applicable to a local log reader.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (types only), so the description was required to compensate — and it does so comprehensively. Each of the 4 parameters is documented with its valid values (``ERROR, WARNING, INFO, or DEBUG``), matching patterns (``[name]`` or ``[homeassistant.components.name]``), case-insensitivity, and ordering semantics ('applied after other filters'). The 'Examples' section demonstrates useful combinations and the Examples make the semantics concrete. This is a model of how to document params when the schema is uninformative.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence — 'Get the Home Assistant error log for troubleshooting' — uses a specific verb (Get) + specific resource (Home Assistant error log) + clear purpose (troubleshooting). The description clearly separates this from sibling tools like get_history, get_statistics, and list_entities. No ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The Best Practices section gives actionable runtime guidance: server-side filtering 'to save tokens on noisy logs,' a triage pattern ('Combine integration + level="ERROR"'), and bounding output with `lines`. However, it never explicitly names alternatives or tells the agent when NOT to use this tool versus a sibling like get_history. Strong parameter-usage guidance, but no 'when to use alternative X instead' framing.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds context about the single-timestamp invocation (start_time defaults end to now), UTC-casting of naive timestamps, the return shape, and the performance/token tradeoff of wide windows. It stops short of explicitly declaring read-only semantics, but the behavior is adequately disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses clear Markdown-style section headers (Args, Returns, Examples, Best Practices) that front-load the purpose while keeping details scannable. Two runnable examples demonstrate both single-date and explicit-timestamp forms, and every sentence earns its place — no filler or redundant restatements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no schema documentation, the description covers all necessary operational concerns: parameter formats, output shape, performance implications, and when to prefer an alternative. The return type is acknowledged and tied to the sibling `get_history`, reinforcing consistency. Nothing material is left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description fully documents all three parameters with ISO-8601 format examples (`2026-05-15` vs `2026-05-15T08:00:00Z`), timezone handling ('Treated as UTC if no offset'), and the default for end_time ('Defaults to now (UTC)'). This exactly compensates for the schema's minimal property metadata and even enriches it with semantic details like 'raw' history.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line 'Get raw state-change history for an entity over a date/time range' uses a specific verb plus resource and clearly differentiates from the sibling `get_history` by emphasizing the explicit window parameter. The phrasing 'Like get_history, but takes an explicit window' explicitly distinguishes it from its sibling, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('inspecting what happened on a specific day or correlating with an external event') and names an alternative: 'For aggregated long-term data, prefer get_statistics_range instead.' This gives the agent clear, actionable selection criteria beyond what any structured field could convey.
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?
Since no annotations are provided, the description carries the transparency burden and handles it well: it explains the underlying mechanism (HA recorder statistics over WebSocket), the retention-window behavior, and the prerequisite state_class requirement. It does not explicitly state side-effect or rate-limit behavior, though 'Get' and the described mechanics clearly imply a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but is tightly organized into purpose, usage guidance, args, return shape, and examples. Every section contributes necessary information, and the key purpose and alternative guidance are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter statistics tool with no annotations, the description provides complete context: when to use it, all parameter details, the expected return structure, and two realistic examples. The output shape is described even though an output schema is present, making the tool self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the Args section fully compensates by documenting entity_id's required state_class values, hours' meaning and default, and period's allowed bucket sizes and default. This adds substantial meaning beyond the bare schema and gives the agent actionable constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the tool's action ('Get'), resource type ('long-term aggregated statistics for an entity'), and scope ('over the last N hours'). It also explicitly contrasts with the get_history sibling by naming the alternative, making the purpose distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this instead of get_history when' and lists three concrete conditions: data older than the 10-day window, aggregate values needed, or high-frequency sensors with token-heavy raw history. This gives clear guidance on when this tool is preferred over a key sibling.
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:

[![hass-mcp MCP server](https://glama.ai/mcp/servers/HiTechLabTN/hass-mcp/badges/card.svg)](https://glama.ai/mcp/servers/HiTechLabTN/hass-mcp)

Score Badge

Copy to your README.md:

[![hass-mcp MCP server](https://glama.ai/mcp/servers/HiTechLabTN/hass-mcp/badges/score.svg)](https://glama.ai/mcp/servers/HiTechLabTN/hass-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/HiTechLabTN/hass-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server