Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses key behavioral traits: 'Uses long-term hourly statistics → full date range, no retention limit, ±1h precision.' This is valuable context beyond a simple read operation. It also states what the tool returns (event count, total duration, session list, daily summary). Missing is an explicit statement that the operation is read-only, but the nature of the tool implies it. The precision limitation and data source disclosure earn a strong 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 four sentences, front-loaded with the core purpose, followed by use cases, a critical behavioral note, an alternative tool pointer, and output types. Each sentence adds distinct value without repetition. It is concise and well-structured for quick comprehension.

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 10 parameters and no output schema, the description covers the essential context: what it does, when to use, key limitations (precision), and the four output modes. It does not mention the 'comparison' feature (e.g., 'previous_period'), which is a notable capability, but the schema handles parameter-level details. Overall, it is complete enough for selection and basic invocation guidance.

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 100%, so the baseline is 3. The description adds a small amount of parameter context by mentioning 'group_by="day"' and 'compact session list' and 'daily summary,' but the schema already documents each parameter in detail. The description does not explain parameter interactions beyond what the schema provides, so it adds limited value beyond the baseline.

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 identifies the tool's purpose: 'Detects activity sessions from a numeric sensor using a power/value threshold.' It provides concrete use-case examples ('charging sessions, appliance runs, or heating cycles') and distinguishes from a sibling by stating 'For binary sensors or person/zone state history, use ha_history_get_state_history instead.' This is specific, actionable, and differentiates the tool from alternatives.

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?

Explicit usage guidance is provided: 'Use for threshold-based activity questions' and a clear alternative for binary sensors/person/zone state history. It also implies when not to use (when the sensor is not numeric or threshold-based). The behavioral note about hourly statistics and precision helps set expectations for appropriate queries.

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 a key behavioral trait: 'Always returns consumption (the change over the period), never raw meter readings.' While it does not mention permissions or side effects, the read-only nature is implied and the core behavior is clearly stated.

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 four sentences, each earning its place: purpose, use cases, behavioral guarantee, and exclusion with alternative. It is front-loaded with the main action and stays compact.

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 (8 parameters, no output schema) and rich input schema, the description provides essential high-level context: what the tool computes, when to use it, and when not to. It does not explain return structure, but the schema already details parameter behavior, making this sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by specifying that entity_id should be a 'cumulative meter' and that the tool returns consumption rather than raw readings, which helps interpret parameters like start_time and comparison.

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 begins with a specific verb ('Calculates') and a clear resource ('energy, water, gas, or other resource... consumed or produced in Home over a time period'). It also distinguishes from a sibling by explicitly stating not to use it for instantaneous sensors and pointing to ha_history_get_sensor_stats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use guidance: 'Use for totals, interval breakdowns, and period-over-period comparisons of cumulative meters.' Also clearly states when not to use it and names the alternative tool: 'Do NOT use for instantaneous sensors... → use ha_history_get_sensor_stats.'

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. It adds valuable context by indicating the time is sourced from the Home Assistant server and not from training data. However, it does not specify the output format or timezone details, which would be helpful but not critical for a simple getter.

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 with exactly three sentences. The first sentence states the purpose, the second provides usage guidance, and the third gives an explicit skip condition. Every sentence earns its place, and the purpose is 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?

Given the tool's simplicity (no parameters, no output schema), the description covers the essential context: what it does, when to use, and when to skip. A minor gap is not describing the return format, but for a current-time getter an agent can infer enough to use it 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?

The tool has zero parameters, so the input schema is empty. According to the rubric, baseline is 4. The description does not need to explain parameters and adds no parameter info, but nothing is 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 description clearly states the tool 'Returns the current date and time from the Home Assistant server (Home).' It uses a specific verb ('Returns') and resource, and distinguishes itself from sibling history tools by being the only one providing current time.

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 tells when to use the tool: 'Call this before time-based queries that use relative or named periods...' and when to skip: 'Skip only if an absolute ISO date range has already been stated in this conversation.' It also warns against relying on training data, providing concrete usage context.

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. It discloses the tool's scope (instantaneous-value sensors), the requirement to pass entity_ids as an array, and the intended usage patterns for aggregations/interval/group_by. It does not mention return value structure or error handling, but the absence of an output schema and the tool's statistical nature make this a minor gap. The description adds useful context about sensor types and unit matching, which goes beyond the schema.

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 six sentences, each earning its place: purpose, array requirement, multi-entity preference, parameter usage, and two explicit exclusions. It is front-loaded with the core function and avoids redundancy. Nothing is wasted, and it remains concise despite covering multiple usage dimensions.

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 (9 params, no annotations, no output schema), the description is very complete. It explains the core behavior, parameter selection strategies, and alternatives. The only missing element is a description of the return format (e.g., a table of aggregates per sensor), but the schema's aggregations enum and the tool name imply this. This is a minor gap in an otherwise comprehensive description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are already well-documented. The description enriches this by explaining when to use which parameter ('Use aggregations for several whole-period stats,' 'Use interval for time series'), and adds guidance on entity_ids ('Always pass entity_ids as an array,' 'Prefer one multi-entity call...'). This adds practical semantics beyond the schema's field-level descriptions.

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 'Computes statistics for one or more instantaneous-value sensors' followed by concrete examples (temperature, humidity, CO₂, pressure, illuminance, power). It explicitly distinguishes from siblings by stating 'Do not use for cumulative consumption in kWh; use ha_history_get_consumption' and 'Do not use for event counting; use ha_history_detect_sessions.' This clearly identifies the tool's scope and differentiates it from probable alternatives.

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 rules: 'Always pass entity_ids as an array,' 'Prefer one multi-entity call over repeated single-entity calls when units match,' and directs parameter selection: 'Use aggregations for several whole-period stats in one call. Use interval for time series and group_by for repeating patterns.' It also gives clear when-not-to-use guidance with named alternatives, covering exclusions and edge cases.

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 appropriately discloses what is returned (state value, unit, timestamps, attributes) and the tool's broad domain support. It could explicitly state it's a read-only operation, but the name and context strongly imply that. The information goes beyond the schema.

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?

Three concise sentences: first states the function, second broadens scope, third gives alternative usage guidance. Every sentence earns its place without redundancy or fluff.

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 simple, but the description covers purpose, scope, return values, and usage alternatives. There is no output schema, so the description's list of returned fields is valuable and sufficient for an agent to understand what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the schema already describes the parameter precisely (exact entity_id, do not guess). The description repeats that it requires the exact entity_id but adds no extra semantics beyond the schema. Baseline of 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 clearly states the tool returns the current state of one entity by exact entity_id, which is specific and distinguishes it from history-related siblings like ha_history_get_state_history. It also notes it works for all domains, including hidden entities, adding scope clarity.

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?

Explicit guidance is provided: prefer GetLiveContext for exposed entities, and use this tool for entities it cannot see, for staleness checks, or when entity_id is already resolved. This clearly tells the agent when to choose this tool over alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the data source (HA recorder), a ~10 day limit, and the shape of returns (timeline or session counts/durations). Missing details include whether read-only is guaranteed, potential errors, or performance characteristics, but the provided context is adequate for a read-like tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences, each earning its place: purpose, usage, mode distinction, and source/return summary. Front-loaded with the primary action and uses bullet-like clarity without redundancy.

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 complex tool with 10 parameters and no output schema, the description explains the two modes, the source, and the default retention limit. It lacks details on error handling or edge cases, but the schema and the mode explanation cover most of the essential context. A bit more detail on when session mode is preferable would push it higher.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the relationship between state_value and the two modes, which is not explicitly stated in the schema. It also orients the reader to session mode vs timeline mode, enhancing parameter understanding beyond individual descriptions.

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 uses a specific verb 'Gets' and clearly identifies the resource: state-change history for discrete-state entities. It distinguishes from siblings by listing concrete use cases (binary sensors, person/device_tracker) and mentions two explicit modes. This makes the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit 'Use for' guidance with example entity types, and explains the two modes (session vs timeline) based on the state_value parameter. However, it does not explicitly exclude other tools or mention alternatives like get_state or get_sensor_stats, so there is room for more differentiation.

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 burden. It discloses that the tool lists areas, supports search narrowing, and returns area names to be reused with area="<name>" in ha_history_list_devices. It stops short of explicitly stating the read-only nature or output format, but 'Lists' implies read-only, and the downstream usage hints at 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?

Three sentences, each essential. The first states the purpose, the second gives usage context, and the third explains filtering and downstream integration. No wasted words; the description is front-loaded and scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with full schema coverage and no output schema, this description is complete. It covers purpose, usage scenarios, parameter semantics, and the relationship to a key sibling tool, giving the agent everything it needs to understand the tool's role and pick it 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?

The input schema already covers 100% of parameters, so baseline is 3. The description adds value by explaining the search parameter's purpose ('Narrow by name with search') and clarifying how the returned names will be used with the area='<name>' field in ha_history_list_devices, which gives semantic context beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Lists the areas (rooms and locations) defined in Home', a specific verb and resource. It clearly distinguishes itself from sibling ha_history_list_devices by mentioning areas vs devices, making the tool's scope unambiguous.

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?

Explicit usage guidance is provided: 'Use when the user wants to explore areas or when you need the exact area name for ha_history_list_devices.' This not only states when to use but also references the alternative tool, giving the agent clear decision criteria.

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 format ('Returns entity_ids with their metric kind and analytics capability') which is useful. However, it does not explicitly state that this is a read-only operation or mention any other behavioral aspects like permissions or side effects, though listing strongly implies non-destructive behavior.

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?

Three sentences, each serving a distinct purpose: state purpose, give usage conditions, and provide follow-up tool guidance. No filler or redundant content. The description is front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters and no output schema, the description adequately covers when to use, what it returns, and how to proceed. The schema handles parameter details. It doesn't explicitly mention default behavior (e.g., max_results default) but that's in the schema. This is a solid, complete description for a list operation.

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 100%, so the schema already documents all parameters (device, max_results, device_class, include_diagnostics) with types and descriptions. The description adds no additional parameter semantics beyond referencing the device name from a prior tool, which is already hinted in the schema's device parameter description.

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 specific verb and resource: 'Lists entities (sensors and controls) on a specific device in Home.' It clearly distinguishes from sibling tools like ha_history_list_devices (which lists devices) and ha_history_list_entities (which lists all entities) by scoping to a single device.

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?

Explicit when-to-use guidance: 'Use when ha_history_list_devices did not already surface the needed entity_ids or when you need a deeper per-device inspection.' It also names follow-up tools for appropriate entity types ('Use measurement sensors with ha_history_get_sensor_stats and cumulative counters with ha_history_get_consumption'), which helps the agent choose the right path.

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 full burden. It clearly indicates a read-only listing operation and describes output as analytics-ready entity_ids. It could be more explicit about side-effect-free nature, but the behavior is transparent enough 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 three sentences, front-loaded with purpose, and every sentence adds value: what it does, how to use it, and what to do with results. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description appropriately explains return values (devices with entity_ids) and provides cross-tool context. It covers the main use cases and directs to related tools, making it complete for a list/filter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds marginal semantic context for area and search (room-based vs device lookup), but does not significantly elaborate beyond the schema's parameter descriptions.

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 lists devices in Home, with filtering by area or search. It also distinguishes itself from related tools by explicitly directing use of the returned entity_ids with analytics tools and telling when to call ha_history_list_device_entities instead.

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: use area for room-based discovery and search for device/appliance lookup. It also gives clear direction on when to use this tool versus ha_history_list_device_entities, and advises using returned entity_ids with analytics tools.

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 full burden. It discloses grouping behavior ('grouped by area and device'), the nature of search (AND semantics in schema, but implied), and the output shape. It does not explicitly state read-only safety or cost implications, but 'discovery tool' strongly implies no mutation and the schema covers include_state performance. It adds meaningful behavioral context beyond the schema.

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?

Four sentences, front-loaded with the tool's core purpose, followed by usage context and exclusions. Every sentence adds distinct value with no redundancy or filler. The structure efficiently guides the reader from purpose to alternatives.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description provides essential context for a discovery tool: what it returns, how it groups results, and how it fits into the broader analytics workflow. It lacks details on pagination or max_results behavior, but those are in the schema. It adequately covers the tool's role and relationship to siblings.

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 100%, so baseline 3 applies. The description summarizes the main filters ('Filter by area, device, device_class, and search') but does not add new parameter details beyond the schema's own descriptions. It does not clarify relationships between filters or the meaning of domains, but schema handles that.

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: it is the 'Primary discovery tool for the exact entity_ids that the ha_history_* analytics tools require.' This clearly differentiates it from sibling tools by framing it as the precursor to analytics, and it lists concrete filter dimensions (area, device, device_class, search) and output contents (entity_id, name, unit, type).

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 ('before ha_history_* analytics') and when not to: 'Not needed before device-control (Hass*) tools — those take plain names and areas, never entity_ids.' It also directs users to ha_history_get_state for live single-entity state, providing an alternative for a distinct use case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.