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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.