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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false), and the description goes well beyond them: it explains that the action is a validated enum (turn_on/turn_off/toggle), that an unchecked value could reach an arbitrary service, that ValueError is raised on bad action, and that an invalid domain surfaces the underlying HA HTTP error. Error modes and validation behavior are exactly the kind of context structured fields cannot carry.

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 action is front-loaded in sentence one and the labeled Use when / Not for / Errors / Limits blocks are easy to scan. Slightly verbose: the ADR-0006 parenthetical and the 'Returns' line restate what the output schema already provides, so a little text does not earn 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 three-parameter mutation tool this covers everything an agent needs: selection criteria, the alternative tool, the service-dispatch mechanism, validation failures, and upstream HTTP failure behavior. Return values are already covered by the output schema, so the extra 'Returns' line is a harmless redundancy rather than a 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 coverage is 100%, so the baseline is 3, but the description adds compositional meaning the schema does not: `domain` and `action` are combined into the `<domain>.<action>` service name and `area_id` is passed as the target payload, so the agent understands the parameters jointly rather than as three independent fields. It does not explain the `light` default beyond 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?

The first sentence states a specific verb (turn on/off/toggle) and a precise resource scope (every entity of one domain within an area). It also discloses the underlying mechanism — dispatching `<domain>.<action>` with an area target — which distinguishes it unambiguously from entity-level and list-level siblings.

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 contains an explicit 'Use when' clause ('controlling a whole area by domain, e.g. all lights in a room') and an explicit 'Not for' clause naming the alternative (`entities_bulk_control`) for explicit entity_id lists across areas. Nothing about tool selection is left 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 idempotentHint=false and destructiveHint=false, but the description adds the concrete consequence: Home Assistant assigns the area_id, you cannot request one, and calling twice with the same name yields two distinct areas. It also discloses the return payload shape, which is genuine context beyond the hints.

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 the action, then compact labeled sections (Use when / Not for / Returns) on separate lines. Every sentence carries information; there is no filler or repetition of the title.

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 create tool with annotations and an output schema, the description covers the operation, the non-idempotent pitfall, usage boundaries, and the return contents. An agent has everything needed to call 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?

Schema coverage is 100% and the single 'name' parameter is fully described in the schema, so the baseline is 3. The description adds a little beyond the schema by clarifying that name is the only input and that area_id cannot be specified, which is meaningful for a create operation.

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 ('Create a new Home Assistant area (room)') and names the underlying WS command. It also distinguishes itself from the sibling update concept by noting no update tool exists in this namespace, so the agent can place it precisely among the areas_* 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?

Explicit 'Use when' (need a new area to assign devices, entities or labels to) and 'Not for' (renaming or moving an existing area, with the note that no update tool exists). Both the trigger and the exclusion are stated, 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 destructiveHint=true and idempotentHint=true, but the description adds genuinely new context: the effect is immediate ('area disappears from the registry immediately') and irreversible ('there is no restore tool'). It stops short of noting permission/auth requirements or downstream effects on entities assigned to the area.

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 the action, then cleanly labeled Use when / Returns / Limits sections. Minor redundancy: the raw WS result is stated twice ('returns Home Assistant's result unchanged' and 'Returns: the raw WS deletion result').

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?

An output schema exists, so return-value explanation is optional, yet the description still covers the return, the mutation's immediacy, and the irreversibility — everything an agent needs before invoking a destructive one-parameter delete.

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 already documents itself, including the pointer to areas_list_areas. The description adds no format or syntax detail beyond what the schema provides, 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?

States a specific verb and resource ('Delete a Home Assistant area by its area_id') and names the underlying WS command, making it trivially distinguishable from areas_create_area, areas_list_areas, and the other area siblings.

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?

Includes an explicit 'Use when: removing an area that is no longer used' line, giving clear positive context. It does not name an alternative or a when-not condition (e.g., what to do if the area still has devices), so it falls short of a 5.

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 and closed-world, so safety is covered. The description adds real value beyond them: it discloses the underlying read path (entity and device registries over WebSocket), the matching rule (own area_id OR device_id of a device assigned to the area), and the limit that an unknown area_id yields an empty list rather than an error. Missing only return-format/pagination detail, which the output schema likely covers.

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 core action, then uses compact labeled sections (Use when / Not for / Returns / Limits). Every sentence carries unique information; nothing restates the name or title.

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 read tool with full schema coverage, annotations, and an output schema, the description covers purpose, routing, semantics, and edge-case behavior. Nothing needed to invoke it correctly 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% and the single area_id parameter is fully documented in the schema, including where to obtain it (areas_list_areas). The description adds no syntax or format beyond 'given area', so the baseline 3 applies when the schema does the heavy lifting.

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 (get entity registry rows for an area) and immediately clarifies the scope: direct area members plus entities reached via their device. It explicitly separates itself from areas_get_area_states and snapshot_get_area_snapshot, so the agent can disambiguate without reading 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?

Contains an explicit 'Use when' clause (need entity registry rows for one area, e.g. before bulk-editing labels/categories) and a 'Not for' clause naming the two siblings to use instead for state values or combined views. When-to-use, when-not, and alternatives are all present.

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 adds genuine behavioral context beyond that: it discloses the internal two-step mechanism (calls areas_get_area_entities, then filters ha.get_states()) and the exact return shape. It does not mention pagination or performance cost of pulling the full state list, which keeps it from 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?

Front-loaded with the purpose, then mechanics, then when/when-not, then returns. Every line is useful, though the internal implementation detail is slightly more than strictly needed for selection.

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 annotations carrying the safety profile, a 100%-covered single-param schema, and an output schema, the description only needs to route the agent and it does so fully. No gaps remain 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 coverage is 100% and the single parameter already documents that area_id comes from areas_list_areas, so the description adds no meaning beyond the schema. Baseline 3 applies when the schema does all the work.

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 ('Get') and resource ('current states of every entity in a given area'), and explicitly distinguishes itself from areas_get_area_entities (registry rows) and snapshot_get_area_snapshot (combined view). An agent can route correctly 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?

Explicit 'Use when' (live state values scoped to one area, e.g. before deciding what to control) and 'Not for' clauses that name the two alternatives with the condition that selects each. Nothing is left 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 readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds real value beyond that: it discloses the underlying WebSocket call (config/area_registry/list) and that results are returned 'exactly as Home Assistant reports it, unfiltered', clarifying there is no server-side filtering or pagination.

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 the action, then the data source, then the usage trigger and return shape. Every sentence adds information an agent can act on; nothing is 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 zero-parameter read tool with an output schema, the description covers purpose, source, filtering behavior, and when to reach for it. Nothing needed to invoke it correctly 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 zero parameters, so per the rubric the baseline is 4; there is no parameter semantics to document 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 verb+resource ('List all Home Assistant areas (rooms)') and scopes it precisely as the full, unfiltered registry, which distinguishes it from siblings like search_search_areas, areas_list_floors, and areas_list_devices. An agent can pick it 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?

'Use when: you need area IDs and names before assigning entities, devices or labels to an area' gives a concrete precondition and motivation. It stops short of naming alternatives or when-not-to-use conditions, so it is clear context without exclusions.

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 safety profile is covered. The description still adds real value by naming the underlying WS command (`config/device_registry/list`), stating that entries are returned verbatim with every field rather than the slimmed projection used elsewhere, and describing the return shape.

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 the core purpose, then cleanly sectioned into Use when / Not for / Returns. The 'Returns' line largely restates what the output schema already provides, which is the only redundancy; otherwise every sentence 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-parameter read-only list tool with full annotation coverage and an output schema, nothing an agent needs to call it correctly is missing — scope, alternatives, and data shape are all covered.

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. There is nothing for the description to disambiguate, and it correctly avoids inventing filter parameters.

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 ('List all devices in Home Assistant's device registry, unfiltered') and explicitly positions itself against three sibling list/search tools. An agent can identify exactly what this returns 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?

Provides explicit 'Use when' and 'Not for' sections, naming the alternatives (`devices_list_devices`, `devices_list_devices_in_area`, `search_search_devices`) and the condition that selects each. Routing is fully determined by the text.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral context beyond that by naming the WebSocket endpoint and stating that results are returned exactly as Home Assistant reports them and unfiltered.

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, structured with purpose, usage, and return sections, and contains no obvious filler. It is slightly more verbose than strictly necessary because the output schema already covers the return shape, but the extra framing remains useful.

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 zero-parameter list tool with annotations and an output schema, the description is complete. It states the purpose, data source, filtering behavior, and a relevant usage scenario, so an agent has enough context to invoke 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 takes zero parameters, so there is no parameter semantics burden. The baseline score for a no-parameter tool is 4.

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 and resource: 'List all floors defined in Home Assistant.' It also names the exact backing registry endpoint, so an agent can distinguish this from sibling area, device, or entity listing 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?

It provides a clear use case: 'Use when: grouping areas by floor, e.g. before building a floor-scoped dashboard.' It gives positive guidance but does not explicitly state when not to use it or name alternative sibling 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?

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds the exact backend service invoked (scene.turn_on) and the return shape, which goes beyond the annotations.

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

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

Three short, front-loaded lines: action, mechanism, return. No filler, and the most important information (what it does) leads.

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 action tool with annotations covering the safety profile and an output schema present, this is largely complete. The return-value line is somewhat redundant given the output schema, and it omits error/failure behavior, keeping it just under a 5.

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 entity_id parameter is fully documented in the schema, including an example format. The description merely restates that entity_id is passed to scene.turn_on, adding no new syntax or constraint detail, 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?

The description gives a specific verb+resource ('Activate a scene') and clarifies the effect ('applying its stored entity states'), which distinguishes it from siblings like automations_get_scene_config or automations_list_scenes. It does not explicitly name a sibling it should be preferred over, 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?

It notes the underlying mechanism (calls scene.turn_on) but offers no when-to-use guidance, no prerequisites, and no comparison to alternatives such as services_call_service or entities_turn_on. An agent gets no routing help.

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 idempotentHint=true, but the description adds material context beyond them: the two-step confirm safety gate, the side effect of calling automation.reload, the concrete endpoint, exact error shapes for confirmation_required and not found, and the irreversibility warning ('deletion is immediate and permanent').

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 action and the confirm gate, then uses labeled Returns/Errors/Limits blocks. Slight redundancy with the output schema, but every line carries actionable content 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 destructive 2-param tool with full schema coverage, annotations, and an output schema, this covers the remaining gaps (confirmation workflow, error responses, permanence) thoroughly. Nothing an agent needs to call it correctly 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 in the schema (confirm's safety behavior and automation_id's config-id/prefix rules). The description largely restates those semantics rather than adding new ones, 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?

States a specific verb+resource+scope: 'Delete an automation by config id, then reload automations.' An agent can distinguish this from automations_delete_script, automations_delete_scene, and the get/set config siblings 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?

Clearly describes the confirm-gated workflow (without confirm=True you get a safety prompt; with it the deletion runs), which is the key usage condition. It stops short of naming alternatives (e.g. disable_automation vs delete) or when deletion is inappropriate, so it is clear context without explicit routing.

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 substantial behavioral detail: the safety prompt when confirm is false, the exact endpoint touched, the scene.reload service call, possible not_found result, confirmation_required error, and that deletion is immediate and permanent. This is rich context beyond the structured annotations.

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 the core action and then organized into safety, returns, errors, and limits sections. It is longer than strictly necessary given the output schema exists, but each section is relevant and the structure aids quick scanning.

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 a destructive mutation tool with annotations, a fully covered input schema, and an output schema, the description still supplies the critical safety context an agent needs: confirm gating, immediate permanence, endpoint behavior, and error outcomes. Nothing essential for correct invocation appears 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 the schema already documents both scene_id and confirm. The description reinforces the confirm requirement, but it does not add syntax or semantic detail beyond what the schema provides, making the baseline 3 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 states a specific verb and resource: delete a scene config, then reload scenes. It distinguishes itself from siblings such as automations_delete_automation and automations_delete_script by naming the scene config resource, and the confirm requirement further differentiates the operation.

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 clearly explains the two invocation modes: without confirm=True it returns a safety prompt and touches nothing; with confirm=True it deletes and reloads. It does not name alternative tools or explicitly say when not to use this tool beyond the confirmation guard, so it falls short of full when/when-not/alternatives 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?

Despite annotations already flagging destructiveHint=true and idempotentHint=true, the description adds substantial context: deletion is immediate and permanent, the confirm gate semantics, the underlying endpoint and script.reload call, and the concrete error shapes for confirmation_required and not found.

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 the core action, then cleanly sectioned into Returns/Errors/Limits. Slightly verbose in restating the confirm behavior and the return dict, but every section carries usable information and nothing is 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 two-parameter destructive tool with an output schema, the description covers the confirmation flow, side effects, permanence, and error cases — nothing an agent needs to invoke it safely 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 the schema already documents both confirm (including its default and safety-prompt behavior) and script_id formats. The description restates the confirm requirement rather than adding syntax 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 ('Delete a script by id') plus the side effect ('then reload scripts'), which cleanly separates it from siblings like automations_set_script_config, automations_run_script, and automations_delete_scene/automation.

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 confirm=True gate is explained thoroughly (safety prompt without it, real deletion with it), giving clear operational context. It stops short of naming sibling alternatives (e.g. delete_scene/delete_automation) or stating when a script should be deleted versus edited, so it's clear but not fully routing.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is partly covered. The description adds important non-obvious behavior: it calls the automation.turn_off service, changes only runtime state, and leaves stored config untouched, which reconciles the non-read-only but non-destructive annotation pair. It stops short of mentioning permissions or rate limits.

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 the core action and consequence, then adds only the two details an agent needs: that it wraps automation.turn_off and that stored config is untouched. The return-value line is short and earned, with 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?

For a single-parameter automation toggle, the description covers what the tool does, how it does it (turn_off service), what changes (runtime state), what does not change (stored config), and what it returns. An output schema already exists, so return details are not required, but the extra note is harmless and 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 100%: the entity_id parameter is fully documented with its expected format and example. The description only restates that entity_id is passed to the service call, adding no syntax or format detail beyond the schema, so the 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 states a specific verb and resource ('Disable an automation') and adds the effect ('stops reacting to its triggers'), making the purpose unmistakable. It does not explicitly contrast itself with the sibling automations_enable_automation, but the action is self-evidently distinct from trigger/list/enable 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?

Usage is implied by the verb 'disable' and the consequence of stopping trigger reactions, but the description never explicitly states when to choose this over automations_enable_automation, automations_trigger_automation, or automations_set_automation_config. It gives useful context (runtime state only, config untouched) that indirectly guides selection but falls short of explicit when/when-not 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?

Annotations already declare non-read-only, non-destructive, and idempotent behavior. The description adds the underlying `automation.turn_on` service call and the raw response shape, which clarifies the mutation mechanics. It does not cover auth needs or further side effects, so it stops 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?

Four short, front-loaded lines cover purpose, mechanism, exclusion, and return. The return line is slightly redundant because an output schema exists, but the overall structure remains efficient and 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 single-parameter enable tool with rich annotations and an output schema, the description supplies purpose, alternative routing, and mechanism. An agent has everything needed to invoke 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?

Schema coverage is 100% and the single `entity_id` parameter is already documented with an example. The description only restates 'with entity_id' and adds no new parameter meaning, so the baseline of 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 ('Enable') and resource ('disabled automation'), and explicitly names the sibling automations_trigger_automation as the not-for case. An agent can distinguish it from related tools without opening schemas.

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 ('running the automation's actions immediately') and names the alternative (automations_trigger_automation). The intended enable use case is clear from the first line.

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), yet the description adds genuine behavior: it hits a specific HTTP route and returns None on 404, including for package/YAML automations that lack a config-id route. That edge-case disclosure is high-value context an agent could not infer from annotations.

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

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

Front-loads the purpose, then the mechanism, then the exclusion, then the return shape. Every sentence carries signal, though the HTTP endpoint path detail is slightly more than needed for selection.

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?

Despite an output schema existing, the description supplies the critical None/404 behavior and the packages-without-id caveat that the output schema would not convey. Combined with named alternatives, nothing needed to call it correctly 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 the schema already fully documents automation_id (config id vs entity_id, leading prefix stripping). The description adds no syntax 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?

States a specific verb and resource ('get the stored config of one automation') and even names the backing file (automations.yaml), distinguishing it from the many sibling automations_* 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?

Explicitly declares what it is NOT for ('the automation's current runtime state') and routes the agent to two named alternatives, automations_list_automations and entities_get_entity. The condition selecting this tool is unambiguous.

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, closed-world, so the safety profile is covered. The description adds real value beyond them by disclosing the underlying trace/get WebSocket command and the blocking round-trip behavior. It stops short of rich context (no error modes when the run_id is stale or missing).

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 core purpose, then uses tight labeled clauses (Not for / Returns / Limits) that each carry distinct information. No filler sentences and no repetition of 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?

For a read-only trace fetch with full schema coverage, annotations, and an output schema, this is complete: purpose, prerequisite routing, return shape, and blocking caveat are all present. An agent has everything needed to invoke 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?

Schema description coverage is 100% and both required params are documented in-schema, including the prefixed 'automation.<id>' form. The description adds no syntax or format detail beyond what the schema already 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 (Get), resource (full automation trace), and scope (for a specific run), with the content of the trace enumerated (steps, timing, condition results). An agent can distinguish it from list/get_last siblings 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 names the exclusion ('Not for: finding which run_id to use') and routes the agent to two specific alternatives (automations_list_automation_traces, automations_get_last_automation_trace) with the condition that selects them. Nothing is left 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 cover the safety profile (readOnly/idempotent/non-destructive), yet the description adds substantive behavior: the internal trace/list → trace/get sequence, exact error payloads ({"error": "no_traces"|"no_failed_traces"}), and the latency cost (two sequential WebSocket round trips). That is well beyond what annotations provide.

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

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

Labeled sections (Use when / Returns / Errors / Limits) keep it front-loaded and scannable, and every line carries information. It is slightly verbose in restating the internal call flow, but nothing is wasted padding.

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 an output schema present the description needn't explain the trace payload, and it uses that space for errors, latency, and run-selection logic instead. An agent has everything needed to call it correctly and interpret failures.

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, but the description goes further by explaining the selection semantics of failed_only ('most recent whose script_execution isn't finished'), which sharpens an otherwise terse boolean flag.

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 ('fetch the most recent trace for an automation in one call') and immediately distinguishes itself from the sibling pair list_automation_traces/get_automation_trace by describing the two-step composition it collapses into one call.

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 explicit when-to-use ('debugging "why didn't this fire?" without first listing traces and picking a run_id by hand'), which implicitly routes the agent away from the two-step workflow. It stops short of naming the sibling tools as alternatives, but the trigger condition is clear and specific.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: the exact error payload shape for the no-traces cases, and that the call blocks for two sequential WebSocket round trips. That is non-obvious cost/behavior info an agent needs.

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 the core action, then organized into Use when / Returns / Errors / Limits blocks. Every line carries actionable information and nothing is 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 read-only two-parameter tool with an output schema, the description covers usage context, return shape, failure modes, and latency characteristics. An agent has everything it needs to call this correctly without further exploration.

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 already 100%, so both parameters are documented structurally. The description still adds meaning, notably clarifying that failed_only selects the most recent run whose script_execution isn't 'finished', which is slightly richer than the schema's 'did not finish cleanly' phrasing.

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 action (fetch the most recent, or most recent failed, trace) for a specific resource (a script identified by script_id). It also spells out the internal trace/list + trace/get composition, so it is clearly distinguishable from siblings like automations_list_script_traces and automations_get_script_trace.

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 'Use when' line gives an explicit scenario (debugging a script's behavior) and implicitly frames the alternative it replaces (listing traces and hand-picking a run_id). It doesn't name a sibling tool directly, so routing relies on the agent inferring it, but the context is clear.

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

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 adds genuinely useful behavior beyond that: the underlying HTTP route and that a 404 yields None rather than an error. It stops short of describing caching, permissions, or failure modes other than 404, so it is not a full 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?

Front-loaded with purpose, then usage boundary, then return shape; each block is short and earns its place. The 'Returns:' block overlaps with the existing output schema, which is mild redundancy but not bloat.

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 read tool with full annotations and an output schema, the description covers purpose, the exclusion case, the transport, and the empty-result behavior. Nothing an agent needs to invoke it correctly 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% and the single scene_id parameter is already well documented in the schema, including the bare-vs-prefixed form and prefix stripping. The description adds no parameter 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?

Specific verb+resource ('Get a scene's stored config') with a parenthetical that names the contents (member entities and their target states), which separates it from runtime-state tools. The 'Not for' clause explicitly disambiguates it from automations_list_scenes and entities_get_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?

Explicitly states what this tool is NOT for (current runtime state) and names two concrete alternatives for that use case. The when-to-use condition is unambiguous, and the 404 behavior is stated so the caller knows how absence is signalled.

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 adds substantive context beyond annotations: the underlying HTTP endpoint, the 404-to-None behavior, and the exact return shape. It stops short of mentioning permission requirements or caching, but adds real behavioral value.

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 tight sentences, front-loaded with the core action, then the exclusion, then the return contract. Every sentence adds information with no 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?

Covers the action, the sibling it is not, the transport endpoint, the 404 fallback, and the return shape. With an output schema present the description need not detail return values, yet it still names the top-level keys, making this more than sufficient 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 coverage is 100% and the schema already explains the bare/prefixed script_id handling thoroughly. The description adds no new parameter syntax but correctly identifies the return dict keys (alias, sequence, fields, mode), which indirectly signals what the id refers to. Baseline 3 applies when schema carries the load, but the explicit key mention is a small extra.

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 ('Get a script's stored YAML config as a dict') and names the exact sibling to avoid ('automations_list_scripts', 'entities_get_entity') for a different concern. An agent can distinguish this from automations_list_scripts without opening either 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 defines the boundary: 'Not for: the script's current runtime state — use automations_list_scripts or entities_get_entity for that.' This tells the agent when not to use this tool and which alternatives to pick.

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/openWorld=false, so the safety profile is covered. The description adds real behavioral context beyond that: it names the underlying `trace/get` WebSocket command and warns that the call 'blocks for the WebSocket round trip', which is latency information the annotations do not convey.

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 the primary action and purpose, then a compact returns/limits block. Every sentence earns its place; the WebSocket command name is borderline implementation detail but useful for diagnostics, keeping it just short of 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?

An output schema exists, yet the description still gives a one-line sense of the return shape ('dict with the full step-by-step trace'). With annotations covering safety and the schema covering params, nothing an agent needs to invoke this correctly 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 in the schema (run_id provenance, script_id prefix format). The description restates that the call takes script_id and run_id but adds no format or edge-case detail beyond the schema, matching the baseline of 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 and resource ('Get a full script trace') and immediately enumerates what the trace contains (steps, timing, action results). It is clearly distinguishable from siblings like list_script_traces and get_last_script_trace, which it explicitly names.

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?

Contains an explicit 'Not for:' clause routing the agent to `automations_list_script_traces` or `automations_get_last_script_trace` when it does not yet have a run_id. The condition that selects the alternative is stated directly.

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, closed-world), so the bar is lower. The description adds real behavioral detail by revealing it reads ha.get_states() and filters on the 'automation.' prefix — implementation semantics that tell the agent what will and won't appear.

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 the purpose, then implementation detail, then return shape. The second sentence about ha.get_states() is slightly implementation-leaning but earns its place by explaining the filter. No 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?

An output schema exists, yet the description still names the returned fields (entity_id, state, friendly_name, last_triggered), which is helpful redundancy rather than a requirement. Everything an agent needs to call and interpret the result 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?

The tool has 0 parameters, so the baseline is 4. The description doesn't invent parameters and correctly presents this as an unfiltered list, which is appropriate for a zero-arg 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?

Starts with a specific verb + resource ("List all automations") and states scope ("with their current state"). It also discloses the underlying data source and filter ('automation.' entity_id prefix), which distinguishes it from the many sibling list 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?

The description makes clear this is a read-only enumeration of automations, which is enough context to prefer it over automations_list_scripts / automations_list_scenes / automations_list_groups. It does not explicitly contrast with those siblings or state when not to use it, so it falls short of a 5.

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 safety is covered, and the description adds genuinely new context: the WebSocket round trip blocks, and only summary data is returned. It says nothing about default limits or pagination of the trace list, which would complete the picture.

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 the core purpose, then return shape, alternative, and limits in a tight structured block. The 'trace/list WebSocket command' detail is slightly implementation-heavy but small and useful for transparency.

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 an output schema present, the description needn't re-document return values, yet it briefly characterizes the summary fields and disclaims step-by-step detail, plus notes the blocking behavior. Combined with the sibling routing, an agent has everything needed to call 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?

Schema description coverage is 100% and the schema already documents the bare-or-prefixed 'automation.<id>' format, so the baseline is 3. The description only names the parameter in the context of the underlying WebSocket command and adds no syntax or format meaning 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 ('List trace summaries (recent runs) for an automation') and explicitly distinguishes itself from the sibling automations_get_automation_trace, which returns one run's full detail. An agent can tell it apart from both the get and the get_last variants 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?

Explicitly routes the agent to automations_get_automation_trace when step-by-step detail for a single run is needed, which is exactly the sibling-selection decision this tool faces. It conveys the summary-vs-detail context clearly, though it doesn't state any prerequisite or when-not condition for listing traces.

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 and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: the underlying data source (ha.get_states()), the filtering rule, and the exact per-group fields returned, which tells the agent the data is a point-in-time state snapshot rather than a registry lookup.

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 the purpose, followed by implementation and return shape in a compact three-part structure. The 'Returns:' field list is slightly redundant against the existing output schema, which keeps 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 parameterless read-only listing tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what is listed, where the data comes from, how it is filtered, and the shape of each item.

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?

Zero parameters, and the input schema is a closed empty object, so there is nothing to disambiguate. Baseline for a parameterless tool is 4; the description correctly implies no arguments are accepted.

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 ('List all Home Assistant entity groups') and narrows scope precisely with '(group.* entities)', which separates it from the broad entities_list_entities sibling. It does not explicitly name a sibling to route away from, so it falls just 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?

Usage is implied rather than stated: by explaining that it reads ha.get_states() and keeps group.* entries, it signals 'use this instead of scanning all states yourself.' There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. entities_list_entities).

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, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the implementation (reads ha.get_states() and filters by the 'scene.' entity_id prefix), telling the agent where the data comes from and why the result set is what it is.

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, front-loaded with the purpose, then the data source, then the return shape. 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?

An output schema exists, so return values did not need spelling out, yet the description still names the fields. With annotations covering safety and a zero-parameter schema, nothing an agent needs in order to call this correctly 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 zero parameters, so the schema carries nothing to explain; the baseline for a no-param tool is 4. The description adds nothing about parameters because there is nothing to add.

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 ('List all scenes') and even names the underlying data source and filter ('ha.get_states()' entries whose entity_id starts with 'scene.'), which unambiguously separates it from siblings like automations_list_scripts or automations_list_automations.

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 the name and the description — an agent can infer this is the read tool for the scenes collection — but there is no explicit statement of when to use it versus alternatives such as automations_get_scene_config or ws_get_states, and no prerequisites or exclusions.

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 and closed-world, so safety is covered. The description adds genuinely new behavioral context beyond them: it discloses the data source (ha.get_states()) and the exact filtering rule (entity_id prefix 'script.'), which tells the agent what will and will not appear in the results.

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 sections: purpose, mechanism, return shape. No filler sentences and the essential information leads.

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-only listing tool with an output schema and full annotation coverage, the description is essentially complete. The only missing piece is routing guidance versus sibling list tools, which is a minor gap given the tool's simplicity.

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. The description correctly introduces no parameter discussion and instead explains the implicit scoping of results, which is the only 'parameter-like' semantics available here.

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 ('List all scripts') plus the data they expose ('current state'). It is distinguishable from automations_list_automations and automations_list_scenes by resource name, though it never explicitly contrasts itself with those siblings.

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 statement of when another tool (e.g. automations_list_automations, automations_get_script_config) is the better choice, and no preconditions. The implementation note about filtering script. entities implies usage but does not guide selection.

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=false, so the safety profile is covered. The description adds non-obvious context the annotations do not: the tool blocks on a WebSocket round trip, and the return contains no step-by-step detail. Useful disclosure beyond the structured fields.

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 the core purpose, then structured Returns/Limits sections. The content is efficient, though the return description is somewhat redundant given an output schema exists. No wasted sentences overall.

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?

An output schema exists so return values needn't be described, yet the description still summarizes them (run_id, timestamps, script_execution) plus the blocking limit and the sibling alternative. Complete for a single-param read tool; only minor redundancy keeps it from a 5.

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?

Only one parameter (script_id) with 100% schema description coverage, including the bare-or-prefixed format. The description adds no syntax or format meaning beyond the schema, so the baseline 3 applies – the schema does the heavy lifting.

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 (trace summaries / recent runs for a script), and explicitly distinguishes itself from the sibling automations_get_script_trace. An agent can tell what it does and how it differs from the full-detail tool without opening either 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?

Names the alternative explicitly ('use automations_get_script_trace for one run's full detail'), giving a clear condition that selects between summary listing and single-run detail. This mirrors the strongest calibration example's routing pattern.

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 annotations already covering idempotentHint, destructiveHint, and readOnlyHint, the description still adds real value: it discloses that it calls the automation.reload service, that it re-reads automations.yaml/packages, re-applies enabled/disabled state, and pulls in config-store automations. It stops short of noting what in-memory state might be discarded, so it is strong but not exhaustive.

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 the core action in the first sentence, followed by useful elaboration. The 'Returns:' sentence is somewhat redundant given a dedicated output schema exists, but otherwise the text is tight and well-ordered.

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 tool with full annotation coverage and an output schema, the description supplies everything an agent needs: the mechanism (automation.reload), the data sources re-read, and the interaction with automations_set_automation_config. Return values are already covered by the output schema.

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 of 4 applies. There is no parameter surface for the description to clarify or obscure.

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+scope ('Reload all automations from YAML') and proceeds to name the underlying service. It is cleanly distinguishable from sibling reload tools such as automations_reload_scripts and automations_reload_scenes, which target different resources.

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 context is implied (use after automations are created/edited in YAML or via automations_set_automation_config) but never stated as an explicit when-to-use rule. It doesn't contrast this tool with alternatives such as automations_set_automation_config, services_reload_config, or system_reload_all, so the agent must infer the choice.

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 safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower; the description still adds real context by explaining that the config file is re-read from disk, scene entities are re-registered, and scenes written by `automations_set_scene_config` survive the reload. It does not mention failure behavior when the YAML is invalid, so it stops 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?

Front-loaded with the action, then supporting detail, then a one-line return note. The final 'Returns: list[dict]' line duplicates what the output schema already covers, which is the only wasted sentence.

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, an output schema present, and annotations covering safety, the description supplies the missing behavioral layer well. The only unaddressed element is what happens on reload failure (invalid scenes.yaml), which an agent calling a config-reload tool would benefit from knowing.

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; there is nothing for the description to clarify. It correctly avoids inventing parameter 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 ('Reload scenes from YAML') and names the underlying mechanism (the `scene.reload` service), so it is clearly distinguishable from automations_reload_automations, automations_reload_scripts, and automations_set_scene_config. An agent knows exactly what this tool does 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?

It explains the effect of the reload and clarifies that scenes saved via `automations_set_scene_config` are included, which is decision-relevant. However, it never states when an agent should choose this over `automations_set_scene_config` or `automations_reload_all`/`system_reload_all`, nor any prerequisite (e.g., valid scenes.yaml). Usage is implied rather than directed.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description goes beyond that by naming the underlying service (script.reload) and disclosing the effect (re-reads scripts.yaml/packages, re-registers script entities), which tells the agent this is a safe state-refresh rather than a data mutation. It does not discuss any error or failure behavior, so it stops 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?

Front-loaded with the action, followed by the mechanism and the return type in three tight sentences with no filler. Every sentence carries distinct information.

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 parameterless reload tool with an output schema already present, the definition covers purpose, mechanism, side effects, and return shape. Nothing an agent needs to invoke it correctly 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 zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify here, and it correctly adds no redundant parameter prose.

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 (reload) and resource (all scripts from YAML), and the mention of scripts.yaml/packages makes it clearly distinct from siblings like automations_reload_automations and automations_reload_scenes. An agent can pick this apart from the other reload tools 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?

Explaining that it re-reads scripts.yaml/packages implies the use case (pick up file edits without restarting), but there is no explicit when-to-use, no statement of when to prefer it over automations_reload_automations or system_reload_all, and no prerequisites. Usage is only implied.

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 flag destructiveHint=true and idempotentHint=true, and the description adds genuinely new behavioral detail: the confirmation gate, the exact return payload, the error shape for confirmation_required, and the reload/restart caveat for groups.yaml groups. This is exactly the extra context annotations cannot carry.

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 action and its create-sibling, then separates Returns/Errors/Limits into scannable blocks. No filler sentences; every line conveys operative behavior.

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 destructive mutation tool with an output schema, the description supplies the confirmation workflow, error contract, and persistence caveat that an agent needs to invoke it safely. 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?

Schema coverage is 100%, so both confirm and group_id are already documented, establishing the baseline of 3. The description's mention of calling the group.remove service with object_id does not match the schema's group_id name, adding mild confusion rather than meaning.

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 (runtime entity group), and anchors it to the sibling that created it (automations_set_group), letting an agent place it precisely among automations_list_groups/set_group.

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?

Clearly explains the two-mode usage (without confirm=True it returns a safety prompt; with confirm=True it actually removes) and the important caveat that YAML-defined groups reappear on reload. It does not explicitly say when to prefer this over a YAML edit, but the context is unambiguous.

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 safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, yet the description adds real context beyond them: fire-and-forget semantics, the underlying `script.turn_on` service call, and the crucial caveat that the script's `response_variable` is never surfaced. It stops short of covering failure modes or permission requirements.

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 key behavioral fact in the first sentence and is generally efficient. There is mild redundancy across the three sentences ('return immediately', 'does not return the script's response variables', and the Returns line all circle the same non-blocking/non-returning idea).

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 two-parameter tool with a full output schema and annotations, the description covers what an agent needs: what it does, the async contract, and the missing-response caveat. Explaining the return value is slightly redundant given the output schema exists, but nothing essential 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 coverage is 100%, so both `entity_id` and `variables` are already documented in the schema; the description's statement that variables are passed as the script's fields largely restates the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Start a script') and immediately qualifies the execution model ('return immediately without waiting for it to finish'), which is exactly what separates it from trigger/get-config siblings. An agent can distinguish it from automations_trigger_automation and automations_get_script_trace 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?

Gives an explicit negative case ('Not for: getting the script's result — this tool never returns it'), which is strong guidance. It does not, however, name the alternative tool the agent should use instead (e.g. a trace-listing tool), so the routing is implied rather than 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 destructive and idempotent behavior, but the description adds concrete operational detail: it posts to a specific endpoint, calls automation.reload, returns a status dict, describes error conditions, and critically states there is no confirmation prompt when replacing an existing automation. This goes well beyond the annotations.

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

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

The description is front-loaded and structured with clear labels (Not for, Returns, Errors, Limits). It is somewhat long, and the Returns dict is partially redundant given an output schema exists, but most sentences add valuable behavioral or usage context.

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 destructive mutation, complete parameter schema, annotations, and output schema, the description supplies everything an agent needs: full-replacement semantics, reload side effect, no confirmation behavior, and error contracts. No critical information 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 coverage is 100%, so both parameters are already well described in the schema. The description mainly reinforces the full-replacement meaning of config and adds error wording, but it does not materially extend parameter semantics beyond what the schema provides.

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 states a precise verb (Create or replace) and resource (the automation whose config id is automation_id), and clarifies that it replaces the whole stored config. It is clearly distinguishable from siblings like automations_get_automation_config, automations_delete_automation, and automations_set_scene_config/script_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?

It explicitly tells the agent when not to use the tool (editing a single field without resending the rest) and implies when to use it (full create or replace). However, it does not name a specific alternative tool or describe prerequisites beyond the config id.

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=false, destructiveHint=false, idempotentHint=false), but the description adds real context beyond them: the group is not written to groups.yaml, it disappears on restart or YAML reload, it forwards to group.set, and it returns a specific error payload without calling the service when entities is combined with add/remove. The one gap is that replacing the entire member list via `entities` sits awkwardly beside destructiveHint=false, though the replacement semantics are at least 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?

Front-loaded and sectioned, but repetitive: the persistence caveat and the files_write_config_file alternative appear twice, and the entities/add_entities/remove_entities exclusion is stated three times (service-call paragraph, Errors, Limits). Trimming the duplication would lose no information.

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 7-parameter mutation tool with an output schema already present, the description covers the essentials an agent needs: mutation semantics, persistence lifecycle, valid parameter combinations, error behavior, and the correct alternative for persistent groups. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds value by enumerating exactly which fields are forwarded to group.set and by spelling out the failure contract for the entities vs add_entities/remove_entities conflict. Minor wrinkle: it refers to the `all` parameter while the schema names it `all_entities`, which could momentarily confuse mapping.

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 ('Create or update an old-style group.* entity at runtime') and immediately draws the boundary against adjacent capabilities, explicitly noting it does not create light/switch/cover group helpers. Combined with the sibling set (automations_list_groups, automations_remove_group, helpers_*), an agent can place this tool precisely 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?

Gives an explicit when-to-use (runtime group that need not survive restart) and when-not ('Not for: a group that survives a restart'), naming the concrete alternatives — groups.yaml via files_write_config_file or a Group helper. It also states the mutually exclusive parameter combinations, so the agent knows how to shape a valid call.

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/idempotentHint/readOnlyHint=false, but the description adds genuinely new behavior: the side-effecting call to `scene.reload`, the silent overwrite with no `confirm` prompt, the exact error shape on invalid `entities`, and the merged return payload. This is well beyond what the structured fields convey and is consistent with them.

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 the core action, then organized into labeled Not for/Returns/Errors/Limits sections that are easy to scan. It is longer than minimal and the second sentence restates the first at a lower level, but no section is 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 destructive, idempotent write tool with nested-object parameters, the description covers the side effect, the no-confirmation risk, the error contract, and the response shape. An output schema exists, so the Returns section is a bonus rather than a necessity, and nothing an agent needs 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 baseline is 3. The description nonetheless adds the validation contract for `entities` ('non-empty dict of {entity_id: state_dict}') and the overwrite behavior tied to `scene_id`, giving meaning slightly beyond 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+resource+scope ('Create or overwrite a scene's stored config') and immediately distinguishes itself from the sibling that applies scenes. An agent can separate this from automations_activate_scene, automations_get_scene_config, and automations_delete_scene 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?

Explicit 'Not for: applying the scene's states right now — use automations_activate_scene' gives a named alternative and the condition that selects it. The overwrite semantics (existing config at id replaced without prompt) further define when this tool is the right call.

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 idempotentHint=true, but the description adds concrete consequences: the whole stored config at that id is replaced (not merged), script.reload is invoked as a side effect, and there is no confirm step so an existing script is overwritten silently. It also documents two specific error payloads, which is exactly the kind of behavior an agent cannot infer from annotations.

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

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

The first sentence front-loads the whole operation (write config, then reload) and every subsequent line is a labeled block (Not for / Returns / Errors / Limits). No filler, no repetition of the title, and the destructive-overwrite caveat is given its own line rather than buried.

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 an idempotent-but-destructive config writer, it covers the alternative tool, the return shape, the failure modes, and the absence of a confirmation guard. With an output schema present it did not need to explain return values in detail, yet the one-line 'Returns' is a harmless reinforcement rather than padding.

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 earns one more by spelling out replacement semantics and surfacing runtime validation failures tied to `config` ('config must be a dict', must contain 'alias' or 'sequence'). This tells the caller what a well-formed `config` actually needs before the call, which the schema alone only partially conveys.

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 states a specific verb pair and resource (create or overwrite a script's stored YAML config) plus the follow-on effect (reload scripts). It also states the exact endpoint, which makes it trivially distinguishable from siblings like automations_get_script_config, automations_delete_script and automations_set_scene_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?

Explicitly names a near-miss sibling and when to prefer it: 'Not for: running the script — use automations_run_script.' The create-vs-overwrite condition is also covered by the schema/description ('an id that does not exist yet creates a new script'). It stops short of 5 because it doesn't compare against automations_get_script_config or the delete/reload siblings in the same family.

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 declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), and the description adds a genuinely non-obvious trait: it calls automation.trigger with skip_condition=true, so conditions that normally block the automation are bypassed. That warning is valuable beyond annotations; the only gap is not saying whether this can be reverted or what side effects are possible.

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 the core behavior, then a short 'Use when' and 'Returns' block — efficient and scannable. The Returns line is slightly redundant given an output schema exists, but it is brief.

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 action with annotations and an output schema, the description covers purpose, trigger semantics, and usage context well. It omits only minor details such as whether conditions can be honored and what side effects the fired actions may cause.

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 there is a single required entity_id, so the schema already documents the parameter fully. The description restates that entity_id is the target but adds no format or selection guidance beyond the schema's example.

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 ('Run an automation's actions now, skipping its normal trigger') and contrasts with the normal trigger path, which cleanly separates it from siblings like automations_run_script or automations_activate_scene.

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 an explicit 'Use when: testing or forcing an automation's actions on demand,' which gives clear invocation context. It does not name a specific alternative tool or state when NOT to use it (e.g., vs. running a script), so it stops short of a 5.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it names the exact upstream calls made (`ha.get_states()`, `ha.list_services()`), enumerates what is deliberately not resolved (device_id, area_id, label_id, templates), and specifies failure semantics — 'unavailable' checks with errors naming the failed fetch, and empty rather than misleadingly-empty missing_* lists. The per-call full-state/full-service fetch cost is also 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?

Front-loaded with the core purpose, then cleanly blocked into Use when / Not for / Returns / Errors / Limits. Nearly every sentence carries information, though the parenthetical about templates ('not just the ones containing '{{ ... }}'') is awkwardly nested mid-sentence and could be tightened.

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?

Despite an output schema existing, the description still enumerates the return keys and explains the 'ok'/'unavailable' check semantics and error shape, which the schema alone would not convey. Combined with limits and non-resolution rules, an agent has everything needed to call and interpret this tool 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?

Only one parameter and schema description coverage is 100%, so the schema already documents `yaml_content` fully (including the plain `yaml.safe_load` parsing and unresolved HA-only tags). The description reinforces the literal-only inspection semantics, which is useful framing, but adds no new parameter-level syntax or format detail. 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 ('cross-check entity IDs and services used in automation YAML against the live registry') and immediately distinguishes itself from the similarly-named sibling `automations_validate_best_practices` by labeling that one static. An agent can select this tool without opening either 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?

Explicit 'Use when' clause ties it to a concrete workflow ('before saving it with automations_set_automation_config') and an explicit 'Not for' clause routes YAML syntax/authoring checks to the named alternative. Both the positive and negative conditions are stated rather than inferred.

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, but the description adds substantial context: parsing uses plain `yaml.safe_load` so HA-only tags fail, the exact fixed rule set run, the return dict shape, and the specific error payload for invalid YAML. This is well beyond what the annotations convey.

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 purpose sentence followed by clearly labeled Use when / Not for / Returns / Errors blocks. It is longer than typical, but each section carries distinct, non-redundant information (checks list, return shape, error contract) and 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 one-param static linter with an output schema, the description covers the parse model, the rule set, the routing to alternatives, and the error contract. Nothing an agent needs to select or invoke it correctly 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?

Single parameter with 100% schema coverage, so the schema already documents `yaml_content` including the safe_load/!input caveat. The description largely restates that parsing behavior rather than adding new parameter-level semantics, so the baseline of 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?

Opens with a specific verb+resource: 'Validate automation YAML against static Home Assistant authoring rules.' It immediately distinguishes itself from the sibling `automations_validate_automation_references` and enumerates the concrete static checks performed, so an agent knows exactly what class of validation this is.

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 'Use when' (linting before saving with `automations_set_automation_config`) and 'Not for' clauses that name the alternative tool for reference checking and call out the blueprint/!input case with a prescribed workaround. Both when-to-use and when-not-to-use are stated with named 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 flag destructiveHint=true and idempotentHint=true, but the description adds substantial context beyond them: the underlying `blueprint/delete` WebSocket command, that the file under /config/blueprints/<domain>/ is removed with content lost and no backup, that there is no confirm guard, and that it blocks on a ~10s round trip. These are exactly the behavioral traits an agent needs before invoking an irreversible delete.

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 the core action, then clearly partitioned into Not-for / Returns / Limits blocks, so no sentence is wasted. It is on the verbose side for a two-parameter delete, but the structure makes the length scannable rather than 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?

Even though an output schema exists, the description notes the return is typically an empty success payload, and it covers destructive semantics, timing limits, and the absence of a confirm parameter. For a destructive two-param tool, nothing an agent needs to call it correctly 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 coverage is 100%, so the baseline is 3. The description still adds value by framing `path` as relative to /config/blueprints/<domain>/ and tying `domain` to the file location, reinforcing the relationship between the two parameters beyond their individual schema 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?

States a specific verb ('Delete') and resource ('an installed blueprint') plus the locating key ('by its relative path'). It is immediately distinguishable from sibling blueprints tools (import/save/substitute) and from the automations_delete_* tools it explicitly routes to.

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 names the negative case ('Not for: automations or scripts generated from this blueprint') and the exact alternatives to use instead (`automations_delete_automation`, `automations_delete_script`), including the reason (they keep running with substituted config). This is textbook when/when-not/alternative 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), yet the description adds non-obvious behavior: it downloads and validates but never persists, the round trip includes a remote download, and the default 10-second ha._ws_call wait applies. That timing/bounding context is genuinely value-add beyond structured fields.

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 the core action, then cleanly sectioned into Use/Not for/Returns/Limits. Slightly repetitive in stating non-persistence twice ('does NOT save anything to disk' and 'Not for: persisting'), but every block still carries useful information.

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 two-param, output-schema-bearing tool, the description covers purpose, routing to the alternative, return shape summary, and blocking/timeout limits. Nothing an agent needs in order to call and interpret it correctly 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 url and domain are already fully documented with examples and defaults in the schema. The description adds no syntax or format detail beyond that, so the baseline 3 applies; the return-value fields it mentions are outputs, not parameters.

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+scope: 'Fetch a blueprint from a URL and validate it without saving it.' It also names the WebSocket command invoked and contrasts with blueprints_save_blueprint, so an agent can distinguish it from siblings without opening schemas.

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?

Includes explicit 'Use when:' (previewing metadata and validation errors before persisting) and 'Not for:' clauses that route the agent to blueprints_save_blueprint with the exact fields (raw_data, suggested_filename) to pass along. Both the when and the alternative are stated, not inferred.

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, and the description adds real operational context on top: it discloses the underlying `blueprint/list` WebSocket command via `ha._ws_call`, that nothing is read from disk, and that the call blocks for the round trip with a default 10 second wait. That timeout/blocking behavior is exactly the kind of trait annotations cannot convey.

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?

Purpose is front-loaded in the first sentence, followed by compact labeled sections (Use when / Returns / Limits). Every sentence carries information; nothing is redundant padding despite the multi-line 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?

Even though an output schema exists (so Returns needn't be spelled out), the description proactively summarizes the return shape, and adds mechanism, usage trigger, and a blocking/timeout caveat. For a low-complexity single-parameter list tool this is more than 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 description coverage is 100%, so the single 'domain' parameter is fully documented in the schema itself (type, default, folder semantics). The description restates the domain scoping ('for the given domain') but adds no syntax or format detail beyond the schema. Baseline 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?

States a specific verb (List), resource (installed blueprints), scope (for a domain), and mechanism (over the WebSocket API). An agent can distinguish it from blueprints_import_blueprint, blueprints_save_blueprint, blueprints_delete_blueprint, and blueprints_substitute_blueprint purely from the description.

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 names the trigger condition ('Use when: enumerating what blueprints exist under /config/blueprints/<domain>') and ties it to the sibling actions that follow (importing, substituting, deleting). It leaves nothing to inference about when this tool is the right one.

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 idempotentHint=true, but the description adds substantial context beyond them: overwrite=False (default) refuses to replace an existing file while overwrite=True loses the previous content, the RuntimeError surfaced by ha._ws_call on conflict, the blocking WebSocket round trip with a 10s default wait, and the explicit absence of a confirm parameter. This is rich behavioral disclosure.

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 the purpose and destination, then cleanly partitioned into Not for / Returns / Errors / Limits sections. Every sentence carries operational value, and length is justified by a mutation tool with several edge conditions.

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?

An output schema exists, so return values need not be re-explained, and the description still notes the typical empty success payload. Combined with the error and timeout coverage, an agent has everything required to invoke the tool correctly, including the path convention tied to blueprints_import_blueprint.

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 still adds cross-system meaning beyond the schema by explaining that overwrite maps to Home Assistant's allow_override flag, which an agent invoking the underlying WebSocket command would not learn from the schema alone.

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