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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, so the safety profile is partially covered. The description adds genuine behavioral context beyond that: the /api path prefix requirement, allowed methods, and that dedicated-tool guards are still enforced. It stops short of noting auth/permission requirements or the oddity that DELETE is permitted under destructiveHint=false.

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?

Front-loads the purpose and examples, then packs method/path/body semantics and the guard caveat into two tight sentences. No filler; every clause carries an invocation-relevant constraint.

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 escape-hatch endpoint with no output schema, the description covers purpose, scope, argument formats, and the preference ordering against dedicated tools. Return shape is omitted, which is defensible for arbitrary REST paths but leaves the agent guessing about response handling.

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 67% and the schema itself documents body and path but leaves method undocumented apart from its enum/default. The description compensates by listing the method values (GET|POST|DELETE), noting path may include a query string, and clarifying body is optional JSON for POST – real additions over the schema text.

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?

States a specific verb ('call any REST endpoint under /api') and scopes it as a fallback for cases without a dedicated tool, with concrete example paths (GET /api/components, POST /api/config/core/check_config). An agent can tell instantly that this is the escape hatch rather than one of the many specific siblings like ha_get_config or ha_list_states.

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?

Explicitly tells the agent when to use it ('cases without a dedicated tool') and when not to ('Prefer the dedicated tools when one exists'), and adds a constraint that it 'cannot bypass their guards'. This is explicit when/when-not/alternative guidance rather than inference.

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?

Annotations already declare readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds value beyond this: it discloses the return semantics ('the states that changed while the service ran'), the POST path, and that extra keys are merged into the data payload. It notably omits any warning that targets like homeassistant.turn_off can affect an entire domain, a real side effect given destructiveHint=false.

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?

Front-loaded with purpose and endpoint, then args and examples; nearly every sentence earns its place. The long enumeration of common services is borderline verbose but serves as a genuinely useful reference for an open-world tool, so it is defensible rather than wasteful.

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 mutation tool with a nested free-form payload, open-world annotations, and no output schema, the description is thorough: it covers inputs, the data-merging rule, and return behavior. Remaining gaps are error/permission behavior and the risk of domain-wide targets, which a complete definition would surface.

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 the baseline is 3. The description goes further by giving concrete example values per parameter (domain 'light', service 'turn_on') and, importantly, explaining the merge semantics of the loosely-typed 'data' object and the optional returnResponse behavior.

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?

States a specific verb+resource ('run a service in a domain') plus the concrete endpoint, and its scope is clearly distinct from siblings like ha_call_api and ha_fire_event. An agent can identify this as the high-level device-control entry point without opening the schema.

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 conveys the intended use via the endpoint and a long list of common domain.service pairs, which implicitly tells the agent this is the tool for controlling devices. However, it never explicitly contrasts with alternatives such as ha_call_api or ha_fire_event, so routing guidance is implied rather than stated.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds concrete consequence detail ('Irreversible: the entity and its attributes are gone') plus a precondition not encoded anywhere in structured fields (integration-backed entities are rejected). It does not address failure/idempotency behavior for repeat deletes.

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 short, front-loaded sentences with no filler; the irreversibility warning comes early where it matters. The 'Args: entityId' fragment is slightly redundant padding against a schema that already names the parameter.

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 single-parameter destructive tool with no output schema and annotations that already flag destructiveness, the description covers origin, irreversibility, and the integration-backed restriction. It omits only error behavior on already-deleted or unknown ids, a minor 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?

Schema description coverage is 100% for the single entityId parameter, so the schema already carries full parameter meaning. 'Args: entityId' restates it without adding format, source, or lookup guidance, which matches the baseline 3.

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?

States a specific verb (Remove) and resource (entity created through ha_set_state), and explicitly names its counterpart tool, letting an agent distinguish it from siblings like ha_set_state and ha_get_state without opening a schema.

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 a clear precondition and implicit exclusion: only works on entities created via ha_set_state and not backed by an integration. It stops short of telling the agent what to do with integration-backed entities (the alternative path), so it is not fully at the 5 level.

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?

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, so the agent knows this is a non-idempotent, side-effecting call. The description adds that the event is observable by automations, but says nothing about persistence, whether the event is transient, or permissions required.

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?

Short, but it repeats the 'Args:' prefix in two consecutive sentences, which is wasted space in an otherwise tiny description and creates mild 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 simple two-parameter fire-and-forget tool with no output schema and annotations covering the safety profile, the description is nearly sufficient. Only a note on event persistence/delivery behavior is missing.

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 both parameters are already documented. The description adds only an example value ('my_custom_event') and restates that eventData is an optional JSON object — marginal value 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?

States a specific verb+resource ('Fire a custom event on the event bus') with the key consequence that automations can listen for it, which separates it from ha_call_service and ha_set_state. It does not explicitly name a sibling, so it stops short of 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 parenthetical 'automations can listen for it' implies the scenario where this tool is appropriate, but there is no explicit when-to-use, no exclusion, and no pointer to alternatives such as ha_call_service for triggering actions.

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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint) and there is no contradiction. However, the description adds almost no behavioral context beyond the time range – no timezone handling, result limits, or ordering semantics – leaving it thin for a list-style 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?

Two short sentences, front-loaded with the core scope, with no filler. The 'Args: ...' clause is largely redundant with the schema's required list, keeping it from a 5.

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 read-only tool whose annotations carry the safety profile, the description is adequate but minimal: there is no output schema, and it says nothing about the return shape or how timestamps are interpreted. It is sufficient to invoke but not rich.

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 documents each parameter (ISO 8601 formats, calendar entity id example). The description only restates which args are required, adding no meaning beyond the schema, so the baseline 3 applies.

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 names the resource (events of one calendar) and the precise scope (between two timestamps), so an agent knows exactly what it returns. It is a fragment rather than a verb-led sentence and does not explicitly contrast with siblings, so it stops short of 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives (e.g., ha_list_calendars to discover entityIds first). The agent must infer the usage context entirely.

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?

Annotations already establish the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description isn't obligated to restate them. It adds the useful framing that this doubles as a connectivity probe, but says nothing about response format, latency, or failure modes. With annotations carrying the behavioral load, a 3 is appropriate.

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?

Two tight sentences with zero filler. The returned-fields summary is front-loaded and the usage hint follows efficiently. Every clause earns its place.

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 zero-arg, read-only tool with annotations covering its safety profile and no output schema to explain, the description provides everything an agent needs: what it returns and why you'd call it first. Nothing material is missing.

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 takes no parameters, so there is nothing for the description to disambiguate beyond what the empty schema already conveys. This is the baseline-4 case: no parameter documentation 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?

Names a specific resource (instance configuration) and enumerates the exact fields returned (location, time zone, unit system, version, loaded components), so the agent knows precisely what this tool produces. The verb is only implied ('Get' via the title), and it does not explicitly contrast itself with siblings, but the resource is distinct enough to stand apart from the state/history/logbook tools.

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?

States a clear use context: 'Best first call to confirm the connection works.' This tells the agent when to reach for it. It stops short of naming alternatives or giving explicit when-not conditions, but for a trivial zero-arg config read that is adequate.

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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description usefully adds the scope ('current session') and the plain-text return shape, but says nothing about log size, truncation, or filtering 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?

Two short sentences with the resource and scope front-loaded and the use case trailing. No filler or 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?

With no parameters, no output schema and full annotation coverage, the description carries the remaining burden well by stating scope and return format. Minor gap: no guidance on volume or how to interpret the text.

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 takes zero parameters, so the schema baseline is 4; there is nothing parameter-related the description could add or omit.

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?

States a specific resource (errors logged during the current Home Assistant session) and the return format (plain text). It distinguishes itself reasonably from siblings like ha_get_logbook or ha_get_history by scoping to errors only, though it never explicitly contrasts with them.

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?

'Useful when something misbehaves' gestures at when to reach for it but is vague and offers no alternatives or exclusions — e.g. nothing tells the agent whether to prefer this over ha_get_logbook when diagnosing an issue.

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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real value: it states the recorder-integration prerequisite and describes the return shape ('one array per entity') with no output schema present. It also explains the minimalResponse trade-off (only state + last_changed, much smaller).

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?

Front-loads the purpose in the first sentence, then a compact Args/Returns block. Dense and terse rather than wasteful, though the inline Args list reads as schema duplication rather than prose.

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 read-only history query with annotations covering the safety profile and no output schema, the description covers purpose, prerequisites, return structure and key parameter defaults. Only the noAttributes flag and pagination/limits go unmentioned.

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 60%, and the description reinforces the important parameters with defaults (entityIds required, start default 1 day ago, minimalResponse default true) while adding meaning the schema lacks — what minimalResponse actually omits. It leaves noAttributes unexplained, a minor gap.

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?

States a specific verb+resource: retrieving state changes over a period for one or more entities. This is clearly distinct from ha_get_state (current state) and ha_list_states, though the description doesn't explicitly name those alternatives. The scope ('one or more entities') is concrete.

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?

Usage is implied by 'state changes' plus the recorder prerequisite, which tells the agent when the tool is even viable. However, there is no explicit when-to-use/when-not guidance or direction to a sibling over this tool. Minimum viable.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds real value by naming the return fields (when, name, message, entity_id) and the default start window, which no structured field supplies. It omits any note on result limits or ordering, so not 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?

Compact and front-loaded: purpose first, then args, then return shape. The parenthetical example earns its place, though the 'Args:'/'Returns:' telegraphic style is slightly clipped.

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?

With no output schema, the description usefully supplies the return fields and the default time window. An agent can call this correctly; only limits/pagination and sibling disambiguation are missing, which are minor for a read-only query 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 the schema already documents the ISO 8601 format, the 1-day default, and the entity filter. The description merely restates 'start (default: 1 day ago), entity (optional), end' without adding format or behavioral nuance 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?

States a specific verb and resource ('Human-readable history entries') and grounds it with a concrete example ('Light turned on by automation'). It does not differentiate itself from the sibling ha_get_history, which is the main ambiguity an agent would face.

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 lists accepted arguments but never says when to choose this tool over ha_get_history, ha_get_error_log, or ha_get_calendar_events. Nothing here routes the agent between the closely related history siblings.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety and idempotency profile is fully covered. The description adds only that the response contains state plus attributes; it says nothing about behavior for an unknown/removed entity, availability, or value formatting, so it is adequate but not rich.

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?

Two tight sentences with no filler, and the definition of what is returned is front-loaded. The inline 'Args:' stub is slightly mechanical but costs almost nothing in length.

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 one-parameter, fully-annotated read tool with no output schema, the description usefully declares what comes back (state and attributes), which is the main missing structured information. Only edge-case behavior (unknown entity, unavailable state) is absent, which is a minor gap at this complexity.

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% and the single parameter carries its own description with an example. The description merely repeats an example ('sensor.kitchen_temperature') without adding domain/format rules (e.g. that the domain prefix determines behavior), so the baseline 3 is correct.

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 names the resource (one entity) and the data returned (current state and attributes), which is specific enough to distinguish it from ha_list_states at a glance. It lacks an explicit verb ('Get' appears only in the tool name) and never names the sibling it contrasts with, so it stops short of 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?

There is no when-to-use guidance, no prerequisites, and no reference to alternatives such as ha_list_states for bulk reads or ha_get_history for past values. The phrase 'a single entity' weakly implies the alternative, but the agent must infer it entirely on its own.

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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds 'Args: none' and the return fields, which is useful but minimal; with no output schema this return-shape note carries some weight, though it stops at two field names.

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 terse fragments, no waste, and the resource scope is front-loaded. 'Args: none' is mildly redundant against the empty schema but harmless.

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 zero-parameter read tool with full annotation coverage and no output schema, the description supplies the essentials: what it returns and that it needs no input. Only the relationship to ha_get_calendar_events is left unstated.

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 takes zero parameters, so the baseline is 4. 'Args: none' explicitly confirms the schema's empty properties, leaving no ambiguity for the caller.

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 names the resource ('Calendar entities available in this instance') and implies enumeration, but there is no verb and no explicit differentiation from siblings such as ha_get_calendar_events. An agent can infer it lists calendars, but the definition relies on the tool name to supply the action.

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?

It never states when to use this tool versus alternatives, nor any prerequisite (e.g. call this to discover entity_ids before ha_get_calendar_events). Usage is only implied by the return fields.

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?

Annotations already declare this is a read-only, idempotent, non-destructive operation, so safety is covered. The description adds genuinely new behavioral context by disclosing that the response payload changes shape depending on whether `domain` is supplied, and that the unfiltered variant is small. Minor gap: it does not say what happens for an unrecognized domain or whether results are cached.

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 short sentences with the core purpose front-loaded, followed by output-shape detail, then the routing rule. The telegraphic 'Without domain / With domain' construction is dense but every clause carries information an agent needs.

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?

With no output schema, the description does the work of describing the two return shapes, which is the right call, and the single optional parameter is fully covered. It stops short of describing error behavior for an invalid domain, which is the only real gap for a one-parameter lookup 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 coverage is 100% and the domain parameter's example values are already documented in the schema. The description goes beyond that by explaining the semantic effect of the parameter on the result: omitting it yields a compact domain-to-service-names map, supplying it yields full definitions with accepted fields. That meaning is not derivable from the schema alone.

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?

Opens with a specific resource ('Services that can be called') and immediately specifies the two output shapes, so the agent knows this enumerates service definitions rather than states or config. The verb is implied by the name/title rather than stated outright, but the resource and scope are unambiguous. It is clearly distinguishable from siblings like ha_call_service, ha_list_states, and ha_get_config.

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 final sentence names the sibling tool (ha_call_service) and the exact triggering condition: confusion about a service name or its data fields. That is an explicit when-to-use rule with an alternative identified, leaving nothing to inference.

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?

Annotations already declare the safe read-only/idempotent profile. The description adds a genuinely useful warning that an unfiltered call returns a huge payload, which is not derivable from annotations, but it says nothing about pagination behavior or result limits beyond that.

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?

Front-loads what is returned, then the args, then the practical caveat. Compact and no filler, though the arg list duplicates the schema.

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?

With no output schema, the description compensates by naming the returned fields, and the annotations cover the safety profile. An agent has enough to call it correctly; only return-size/pagination limits are left unspecified.

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 all three parameters are already documented, including defaults and bounds. The description adds only a domain example ("light"), which the schema also provides, so baseline 3 applies.

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?

States a specific verb (list) and resource (entity states), and enumerates the returned fields (entity_id, state, attributes). The word "All" implicitly contrasts with the singular ha_get_state sibling, but no sibling is named explicitly.

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?

"Always pass a domain on a real install — the full list is huge" gives concrete operational guidance on how to call it, and the offset param hints at paging. It stops short of naming alternatives (e.g. ha_get_state for a single entity).

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered structurally. The description adds 'server-side' execution and the return shape ('the rendered string'), but says nothing about template evaluation cost limits, error behavior on invalid templates, or which HA objects are reachable. Useful additions, but modest against an already-complete annotation set.

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?

Front-loads the purpose, then args, then the comparative usage advantage, then examples, then the return. Every line carries information and there is no filler or repetition.

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?

With no output schema, the description correctly compensates by stating 'Returns: the rendered string' and demonstrating template syntax. What is missing is failure behavior (invalid template, unknown entity) and any note on template scope, but the core call information is present.

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% ('Jinja2 template', 'Variables available to the template'), so the schema already documents both parameters. The description's 'Args: template, variables (optional)' restates that, including the optionality of variables. It adds no syntax or scoping detail beyond the schema, so baseline 3 applies.

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?

States a specific verb and resource ('Render a Home Assistant Jinja2 template server-side') and immediately shows what that means with two concrete template examples. The 'cheapest way to read or compute many values at once' framing sets it apart from the state-reading siblings like ha_get_state and ha_list_states.

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?

Gives a clear when-to-use rule ('cheapest way to read or compute many values at once'), which is the main selection driver versus ha_get_state or ha_list_states. It stops short of an explicit when-not or naming the alternative tools, so it is strong but not complete.

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?

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false), but the description adds substantial non-obvious context: the change is internal-only, not a device command, and the entity is created if absent. It omits the non-idempotent behavior flagged by idempotentHint=false, which would have been worth calling out.

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 critical warning and the alternative routing are front-loaded in the first two sentences, which is exactly right. The trailing args list is partly redundant with the schema, costing a bit of density but not clarity.

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 mutation tool with no output schema, the description covers everything material: what is overwritten, that the effect is representational rather than physical, the sibling to use for real control, and the create-on-missing edge case.

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 entityId, state, and attributes. The description's args list (required/optional markers) largely restates the schema's required array rather than adding format, naming conventions, or attribute 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?

States a specific verb and resource ('Overwrite an entity's state and attributes') and immediately draws the boundary against the sibling tool that actually controls devices. An agent can distinguish this from ha_call_service and ha_delete_state without opening any schema.

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?

Explicitly says when NOT to use it ('it does NOT talk to the physical device') and names the correct alternative ('use ha_call_service instead'). This is the routing information an agent needs before acting.

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