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

Annotations only declare destructiveHint=true and openWorldHint=false, so the description carries most of the burden and does so richly: parallel-by-default dispatch, partial failures reported without aborting, all-invalid batches fail closed, group+own-member batches fail closed, non-transactional selector dispatch, and a >100-entity fail-closed cap. These are non-obvious behaviors an agent could not infer from annotations or schema.

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

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

The response is long but front-loads purpose and mode selection with bold headers, so it is easy to navigate. A few passages are verbose — notably the trailing Claude Desktop timeout/approval advice, which is operationally useful but reads as troubleshooting rather than tool semantics.

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 8-parameter, two-mode destructive tool with an output schema, the description covers mode selection, failure semantics, and constraints well enough to call correctly. Return values are correctly left to the output schema, though the per-domain parameter allowlist is only partially addressed.

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 real meaning: it explains that selector exclusions apply after recursive membership expansion, that a top-level validate_first/timeout_seconds is rejected in operations mode, and the 'off' vs 'turn_off' action naming convention. It goes beyond restating the schema without fully specifying per-domain parameter allowlists.

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

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

The description names two specific operating modes ('operations mode' and 'selector mode') keyed to explicit parameters, and explicitly distinguishes itself from ha_call_service and ha_search. An agent can tell immediately what the tool does and which sibling to use instead.

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

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

It provides an explicit 'When NOT to use' block naming the two alternatives and the conditions that select them, plus in-mode guidance (use selector mode with exclude_entity_ids when a group action must exclude members). Both the when and the when-not 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 destructiveHint, idempotentHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds real value beyond them: fire-and-forget semantics, that acceptance by the bus does not confirm subscriber action, and client-timeout troubleshooting. It does not reconcile the destructiveHint=true annotation, leaving one small gap.

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

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

Front-loads purpose, then usage, then caveats in a logical order. The final Claude Desktop timeout/manual-approve paragraph is operationally useful but somewhat niche and verbose relative to the core definition.

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 and annotations carry the safety profile, so the description need not explain return values. It covers purpose, alternatives, and fire-and-forget caveats comprehensively, with only the destructiveHint annotation left unexplained.

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 event_type and data are already documented, including the trigger.event.data delivery detail. The description offers no additional syntax, format, or example beyond what the schema provides, making the baseline 3 correct.

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

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

States a specific verb and resource ('Execute a custom event on the Home Assistant event bus') and immediately scopes it against siblings by naming ha_call_service and ha_config_set_automation. An agent can distinguish this from entity control and automation running 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 'When NOT to use' guidance with named alternatives and the exact condition that routes to each (entity control vs. running automations). It also positively describes the intended use case: event types consumed by event-triggered automations, Node-RED, or custom integrations.

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=true and readOnly=false, but the description adds real operational context beyond them: default-on result compaction (what gets dropped), unavailability in Read Only Mode, the multi-target wait/timeout caveat, WS-command restrictions, and the 4-minute timeout guidance. This is behavioral disclosure the schema and annotations do not 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?

Long, but well-structured and front-loaded with the escape-hatch framing and the critical when-not-to-use routing. The timeout troubleshooting paragraph is useful but sits at the end and reads as somewhat incidental; overall it earns its length without much waste.

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

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

An output schema exists so return-value explanation is optional, yet the description still clarifies result compaction, service_response key behavior, and verbose mode. Combined with the routing and mode-restriction notes, an agent has everything needed to call this correctly in context.

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

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

Schema coverage is 100%, so parameters are already documented, but the description still adds value: domain.service format, that ws_command is mutually exclusive with the other service params, the entity_id-wins-over-data precedence note, and result compaction interactions with result_fields. Slightly redundant with the schema in places, hence not a 5.

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

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

States a specific verb (call) plus resource (Home Assistant service / one-shot WebSocket command) and frames itself explicitly as 'the catch-all escape hatch.' It distinguishes itself from siblings by naming which dedicated tools cover which jobs.

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?

Unusually strong routing: a 'When NOT to use' section names concrete alternatives (ha_config_set_automation, ha_config_set_script, ha_config_set_scene, ha_manage_app, ha_manage_updates, ha_set_integration) with the specific parameters that replace this call, followed by a 'When to use' condition and two worked examples.

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?

Goes well beyond the destructiveHint annotation by disclosing irreversibility, scope of deletion (config included), the YAML-mode exclusion, and the default-dashboard restriction. It even adds an operational troubleshooting note about the 4-minute timeout and approval flow that 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-loaded with the core action and the WARNING, which is good, but it then sprawls into an example, a second note, and a long Claude-Desktop-specific timeout paragraph that is only relevant to a narrow client. The timeout paragraph in particular dilutes an otherwise tight definition.

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 destructive contract, the preconditions (storage-mode only, non-default), the ID-resolution behavior, and client-specific failure modes. With an output schema present, no return-format discussion is needed, so the description is complete for a destructive single-param tool.

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

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

Schema coverage is already 100%, so the schema fully documents url_path including the dual-form acceptance. The description's ID-resolution note ('hyphens → underscores') adds a bit of context about how either form is handled, but this is marginal gain over the schema baseline.

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

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

States a specific verb ('Delete') and resource ('storage-mode dashboard') and scopes the operation precisely. It explicitly distinguishes itself from YAML-mode dashboards and adjacent sibling tools like ha_config_delete_dashboard_resource, so the agent can tell them apart.

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 when it does not apply (YAML-mode dashboards, default dashboard) and warns about permanence. However it never names the sibling to use instead (e.g., a setter or resource-deleter) as a positive alternative, so it stops short of a full routing 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 destructiveHint=true, but the description adds real consequence detail beyond them: the resource is no longer loaded on dashboards, and custom cards depending on it will fail to load. It also discloses retry/timeout behavior ('read the target back before repeating it'). The operational note is useful, though partially tool-agnostic noise.

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 core sentences and the example are well front-loaded and earn their place, but the final paragraph about a Claude Desktop 4-minute timeout and manual-approve buttons is verbose, tool-agnostic, and dilutes the definition.

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

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

For a single-parameter destructive tool with an output schema present, the description covers action, precondition, consequence, and recovery guidance. 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?

Single parameter with 100% schema coverage, so the schema already documents resource_id fully. The example call shows the expected ID format, which adds marginal value, but the baseline of 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 ('Delete a dashboard resource') and clearly distinguishes itself from the sibling ha_config_list_dashboard_resources and ha_config_set_dashboard_resource. An agent can identify 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?

Explicitly routes the agent: 'Use ha_config_list_dashboard_resources() to find resource IDs before deleting. Ensure no dashboards depend on the resource.' This names the alternative tool and the precondition for safe use.

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 readOnly/idempotent/openWorld, so the bar is lower; the description adds genuinely useful behavior: config_hash stability across unchanged reads and the automation_id resolution/fallback rule. It does not mention permissions or failure modes for a missing automation.

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 followed by return-shape notes and examples; every paragraph carries information. The trailing keyword string ('read inspect fetch view...') is low-value filler, keeping it from a 5.

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

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

With an output schema present, return values need not be documented, yet the description usefully explains the two opaque return fields (config_hash, automation_id) and gives invocation examples. Complete enough for a single-parameter read tool.

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

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

Schema coverage is 100% so the baseline is 3, and the description goes beyond it by clarifying that the identifier may be either an entity_id or a unique_id and explaining that the returned automation_id is the resolved canonical entity_id with a fallback to the input. That adds semantic value the schema does not.

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 ('Get Home Assistant automation configuration') and enumerates the payload (triggers, conditions, actions, mode settings). It is trivially distinguishable from siblings like ha_config_set_automation and ha_config_remove_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?

Two concrete invocation examples cover both identifier forms and it routes the agent to ha_get_skill_guide for documentation, which is clear positive guidance. It stops short of stating when-not-to-use (e.g. vs ha_get_state for live state rather than stored config).

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=true, idempotent=true, openWorld=false, so the safety profile is covered. The description adds meaningful context beyond that: the cross-tool relationship that uid and recurrence_id feed the edit and remove tools, which is not derivable 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-loaded purpose sentence, then output contents, then routing hint, then two compact examples. Each section earns its place 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?

With an output schema present, annotations covering the safety profile, and 100% schema description coverage, the description supplies everything else an agent needs: purpose, entity discovery path, default window behavior, and cross-tool linkage.

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 worked examples add real value: they demonstrate that calling with only entity_id yields the default (next week) window and show the ISO start/end pairing, making the default temporal behavior concrete rather than just implied.

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 (calendar events), and scope (from a calendar entity within a time range). It distinguishes itself from the sibling edit/remove calendar tools by naming them, so an agent can tell which calendar tool to pick 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 routes the agent to ha_search(domain_filter='calendar') for finding entities and notes that the edit/remove tools consume the returned uid/recurrence_id. There is no explicit when-not guidance, but the context for use 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 openWorldHint=false, so the safety profile is covered. The description adds parameter-dependent behavior (list all without category_id, retrieve one with it) and contextualizes categories as domain-scoped organizational groups, which is useful 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 with the core behavior, then uses short paragraphs and examples to clarify edge cases and alternatives. Every sentence contributes useful information without 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?

Given the low complexity, rich annotations, complete schema, and presence of an output schema, the description covers all that an agent needs: scope behavior, conditional semantics, examples, and relevant sibling alternatives. 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 the schema itself documents both parameters. The description adds clarifying semantics by explaining that omitting category_id changes the operation from retrieval to listing, and provides concrete examples for scope values, going beyond the 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?

The description states a specific verb (get) and resource (category), and explicitly distinguishes listing all categories from retrieving one by ID. It also names sibling tools for creation/update and assignment, so an agent can tell it apart without opening other 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?

It gives explicit conditional usage: omit category_id to list, include it to retrieve a specific category. It also names the alternatives ha_config_set_category() for create/update and ha_set_entity(categories=...) for assignment, covering when to use this tool versus others.

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/closed-world, but the description goes well beyond them: cache bypass behavior, config_hash stability per mode, the secret-exposure risk that excludes YAML dashboards from search, the depth bound and `warnings` entry for non-traversed shapes, and the fact that strategy dashboards are unsearchable. This is exactly the additional behavioral 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-loaded with the mode taxonomy and organized into labeled MODE sections plus examples, so it scans well despite its length. A few clauses (the nested python_transform aside, the search-all secret rationale) are verbose, but nearly every sentence carries actionable 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 an 11-parameter, multi-mode read tool with no output schema, the description covers return shape (url_path/title/icon, config_hash, view/view_index, matches with python_path/jq_path, warnings) and mode interactions thoroughly. 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 baseline is 3, but the description adds cross-parameter semantics the schema does not: criteria are AND-ed, python_path must be prefixed with `config`, jq_path is the jq equivalent, and mode overrides the other mode-selecting params. It stops short of 5 only because most per-parameter detail is already in the schema.

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

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

The description states a specific verb+resource ('Get dashboard info') and then decomposes it into four precisely named modes (list, search, get, search-all), each with its own trigger condition. An agent can distinguish this from ha_config_set_dashboard, ha_config_delete_dashboard, and ha_get_dashboard_screenshot 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 when-to-use for every mode, including precedence ('mode="search" takes precedence; list_only/entity_id/card_type/heading are ignored'), an explicit alternative tool for a narrower need (ha_get_dashboard_screenshot), and a worked search→set workflow. 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 readOnlyHint, idempotentHint and openWorldHint, so safety is established. The description adds the dual list/get behavior and concrete invocation examples, but does not mention failure behavior for an unknown label_id, which is a minor remaining gap.

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

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

Front-loaded with the core behavior, then examples, then related-tool routing. The assignment-tool paragraph is somewhat expansive but earns its place by preventing wrong-tool 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?

An output schema exists and annotations declare the safety profile, so the description only needs to explain invocation modes and routing – which it does completely. 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 schema documents label_id, so the baseline would be 3. The description goes beyond it by defining the semantic meaning of omitting the parameter (list all) versus providing it (single lookup), which materially helps invocation.

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 label info') and disambiguates its two modes: list all labels or retrieve one by ID. It also names sibling set/assign tools, so an agent can place it immediately in the label toolset.

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 the two calling conditions (without label_id = list, with label_id = specific) with worked examples, and routes adjacent tasks to ha_config_set_label and ha_set_entity/device/area_or_floor. 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 readOnly/idempotent/openWorld=false, yet the description adds real behavioral context: listing returns compact metadata only, integration-managed scenes have no editable storage config or scene_id, and content-search results are explicitly non-exhaustive because unread configs are reported. This exceeds 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?

Front-loaded with the two modes, then routing guidance, then behavioral caveats, then example calls. Every sentence carries a distinct constraint or routing rule 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?

With an output schema present, return values need not be spelled out, and the description still names the returned entities dict and config_hash needed for the edit workflow. Combined with the safety annotations and full schema coverage, an agent has everything required 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%, so the baseline is 3; the description nonetheless adds meaning by clarifying the two accepted forms of scene_id (storage ID vs entity_id resolution), the intended use of search_in_config for attribute values, and the non-exhaustive nature of that search. Examples map parameters to concrete calls.

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 dual-mode purpose (get a scene's full config, or list/search scenes without scene_id) and explicitly differentiates itself from ha_search and from the write path ha_config_set_scene. An agent can tell this apart from siblings like ha_config_remove_scene or ha_search 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 routes: use ha_search for cross-domain/dependency discovery, use this tool for ordinary scene discovery, and pass the returned scene_id back plus the config_hash to ha_config_set_scene for edits. It also qualifies when search_in_config applies and notes that listing metadata is compact.

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 readOnly/idempotent/openWorld, yet the description adds genuinely new behavioral facts: config_hash stability across consecutive reads, the canonical script_id resolution and its rare fallback, and the prefix-stripping mechanism contrasted with automations' state lookup. This is well beyond what the structured fields disclose.

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 core explanation is front-loaded and useful, but the prefix-handling paragraph is somewhat over-elaborate and the trailing keyword string ('read inspect fetch view existing script config sequence actions get show detail') is pure keyword stuffing that adds no meaning.

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

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

An output schema exists, so return-shape documentation is not required, yet the description still clarifies the two salient returned identifiers (config_hash, script_id). For a single-parameter read tool with full schema coverage and annotations, nothing needed for correct invocation 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 adds value by clarifying that a leading 'script.' prefix is stripped before lookup and that the bare key matches what set/remove expect. The examples reinforce both accepted forms, though no additional format or edge-case semantics beyond this.

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 (Home Assistant script configuration) and enumerates the returned content (sequence, mode, fields). It is clearly distinguishable from the sibling write/remove tools ha_config_set_script and ha_config_remove_script, and it explicitly positions itself against ha_config_get_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?

Gives two concrete invocation examples (bare form and entity_id form) and routes users to ha_get_skill_guide for deeper configuration help. It never states an explicit when-not-to-use or a precondition like 'read before calling set_script', so it falls short of the 5 benchmark.

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/openWorld, so the description earns credit for adding behavior: total_count/has_more/inline_count/by_type describe the FULL set rather than just the page, and inline resources return a token-saving preview instead of the full encoded URL. That last detail materially affects what an agent sees and does.

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 pagination semantics, then examples in a clearly labeled block. Slightly longer than strictly necessary, particularly the Home Assistant 2026.6+ UI note, but every section carries 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?

Output schema exists, yet the description still clarifies the tricky parts an agent would misread: summary counts span all resources, and content is previewed or truncated under budget. Combined with the read-only annotations, nothing needed 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?

Schema coverage is 100%, so the baseline is 3, but the description goes beyond by supplying worked examples with actual values (offset=100, include_content=True) and by framing include_content as a token tradeoff rather than just a 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 and resource ('List Lovelace dashboard resources') and immediately scopes it to custom cards, themes, CSS/JS. Sibling tools like ha_config_set_dashboard_resource and ha_config_delete_dashboard_resource make this the read-side counterpart, and the description confirms that role by noting each resource carries an ID for update/delete.

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 concrete invocation examples for the two non-default behaviors (offset=100 to page, include_content=True for full content) and explains when to care about inline previews. It stops short of explicitly naming when to prefer a sibling tool, but the read-only listing scope 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 readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: results are paginated, total_count/has_more describe the full unpaginated set, and the scope is limited to legacy group types. It stops short of describing error behavior or ordering.

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 scope, pagination semantics, and an example call. No redundant sentences; every clause adds information an agent needs.

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

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

For a two-parameter paginated read with an output schema present, the description covers purpose, scope, pagination behavior and even the returned field set. 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%, so limit and offset are already documented; the baseline is 3. The example call with offset=100 illustrates pagination in practice but adds no meaning beyond the schema's own parameter descriptions.

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

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

States a specific verb and resource ('List Home Assistant entity groups with their member entities') and immediately scopes the domain: old-style groups from group.set/YAML, explicitly excluding platform-specific groups such as light or cover groups. An agent can tell this apart from set/remove group siblings and from helper/area listings 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?

Usage is implied by the tool's nature (read-only listing) and the note that total_count/has_more cover the full set, which hints at pagination strategy. However, no explicit when-to-use, when-not-to-use, or alternative (e.g., ha_config_get_group, ha_config_list_helpers) is named, so the agent must infer 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 establish read-only/idempotent safety, so the description's job is to add context — and it delivers: pagination semantics (total_count/has_more), the degraded-registry warning case, the COMPONENT_NOT_INSTALLED error paths, and the person YAML exception. This is exactly the kind of behavior an agent needs before calling.

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 and record shape, then layered detail in digestible paragraphs. Slightly long, and the trailing keyword string ('list all helpers input_boolean ...') is search-stuffing that doesn't earn its place, holding it back 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?

Given an output schema exists, return-value explanation isn't required, yet the description still covers the fields an agent will act on (identity resolution, degraded case) plus all error conditions. For a paginated list tool with two type families, this is 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 coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema: it explains the id vs entity_id vs original_name semantics under renaming, and clarifies that 'all' is component-only rather than a partial fallback. That goes beyond what the enum list 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?

States a specific verb and resource ('List Home Assistant helpers of a specific type with their configurations') and immediately scopes it against siblings by noting what it is not (YAML-defined helpers, non-storage types). An agent can separate this from ha_config_set_helper and ha_config_list_groups without reading 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?

Provides concrete usage examples (single type, 'all', pagination) and routes the agent to ha_get_skill_guide for deeper docs. It also states conditions that change behavior (flow types need the custom component). It stops short of an explicit when-not-to-use statement versus sibling list tools, so not 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 destructiveHint=true and idempotentHint=true, so safety framing is covered; the description adds genuine value by stating the deletion is permanent and by documenting the return-value fallback (resolved entity_id vs input identifier) plus a concrete timeout-recovery procedure. The main gap is that it never says the operation is idempotent or what happens on a second call.

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 examples, then troubleshooting. The Claude Desktop timeout paragraph is verbose and tool-support specific, but it is last and practically actionable, so it earns most of its space.

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 return-value discussion is partly redundant, yet the resolved-vs-fallback behavior is useful. Annotations cover the destructive/idempotent profile. The description is nearly complete for a 2-parameter destructive tool; only repeated-invocation behavior is unaddressed.

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

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

Schema coverage is 100% and both parameters are already described (identifier accepts entity_id or unique_id; wait controls synchronous removal), so the description's examples largely restate the schema. Baseline 3 is appropriate — no additional syntax or format detail beyond what the schema carries.

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 ('Delete a Home Assistant automation') and adds 'permanently', which cleanly distinguishes it from the sibling mutators like ha_config_set_automation and ha_config_get_automation. An agent can identify the operation 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?

Usage is implied by the destructive verb, and the examples show acceptable identifier forms, but there is no explicit when-to-use/when-not-to-use guidance or pointer to an alternative (e.g. disable vs delete). Nothing tells the agent when deletion is the wrong call versus ha_config_set_automation.

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, idempotentHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new context: deletion runs over the WebSocket API, the exact command path, and a concrete timeout/retry troubleshooting note for Claude Desktop. The repetitive 'read the target back before repeating' advice is a bit soft but does not mislead.

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 and the command, then examples. The trailing timeout paragraph is longer than the core spec and slightly dilutes focus, but each part still carries operational 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?

With a rich schema, destructive/idempotent annotations and an output schema, the description supplies everything else an agent needs: UID sourcing, recurring-event semantics, the transport quirk, and a failure-mode hint. 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 examples and text go beyond the schema by showing how uid, recurrence_id and recurrence_range combine and by stressing the verbatim 'THISANDFUTURE' spelling. That is added semantic value over the property 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?

Specific verb+resource (delete a calendar event) with the exact WebSocket command named, and it explicitly distinguishes itself from the sibling set/get calendar event tools by noting delete lives only on the WebSocket API. An agent can identify the tool's role without ambiguity.

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

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

Explicitly routes the agent to ha_config_get_calendar_events() for the UID, and the two worked examples show single-event vs recurring-range invocation. It stops short of stating when not to use it (e.g., use the set tool to modify instead), so it is clear context rather than full when/when-not coverage.

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 important context beyond annotations: deletion removes the category from the registry and from all assigned entities, and the action cannot be undone. It also includes an operational timeout note for Claude Desktop users.

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 definition is front-loaded with the core action, scope, and warning, and the example is useful. The Claude Desktop timeout paragraph is lengthy and somewhat tangential to tool semantics, slightly reducing conciseness.

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 explained. The description covers prerequisites, side effects, irreversibility, and an invocation example, making it complete enough for an agent to call the 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?

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds an example showing argument order and sample values, but does not add much parameter meaning beyond the schema baseline.

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

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

The description states a specific verb (Delete/Removes) and resource (Home Assistant category), and clarifies the registry scope. It is clearly distinguishable from sibling get/set category tools by naming the delete action and its consequence.

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 tells the agent to use ha_config_get_category() to find category IDs, which is a clear prerequisite. It also provides an example call and a strong warning that deletion cannot be undone, though it does not explicitly state when not to use this versus set/get alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial context beyond them: automations referencing the group may fail, YAML-defined groups reappear after restart, and only old-style groups are affected. It also discloses operational behavior (4-minute timeout handling) that no structured field carries.

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 and the when-not/when-to structure is easy to scan, but the closing Claude Desktop timeout paragraph is lengthy and only tangentially about invoking the tool correctly. It earns partial credit as actionable guidance but dilutes an otherwise tight definition.

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 removal tool with a full output schema, the description covers routing, prerequisites, side effects, and persistence caveats thoroughly. Nothing an agent needs to call it safely is missing, and return values are correctly left to 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?

Schema description coverage is 100%, so both object_id (with prefix-exclusion and format) and the wait flag are already documented in the schema. The description only restates the identifier format via an example and never mentions the wait parameter, adding no meaning beyond the schema. 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 ('Remove a service-based Home Assistant entity group via the group.remove service') and immediately distinguishes it from the config-entry-backed path handled by ha_remove_helpers_integrations. An agent can tell this apart from ha_config_set_group and ha_config_list_groups 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?

Explicit when-NOT-to-use (config-entry groups created via ha_config_set_helper → use ha_remove_helpers_integrations) and when-to-use (groups from ha_config_set_group or YAML `group:` config), plus a discovery pointer to ha_config_list_groups() and a concrete example. Both branches of the alternative-selection decision are covered.

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 and idempotentHint, and the description goes well beyond them: it discloses cascade effects (removal propagates to all entities, devices, and areas), irreversibility, and operational timeout guidance. That is substantial behavioral context not available from 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 and the warning is well placed, but the final paragraph about a 4-minute Claude Desktop timeout and the manual-approve button is tangential troubleshooting chatter that does not help an agent select or invoke the tool.

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, annotations cover the safety profile, and the description adds the cascade-destruction warning plus the ID-retrieval prerequisite. Everything an agent needs to call this correctly 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?

Only one parameter with 100% schema coverage, so the schema already carries the semantics and baseline is 3. The worked example ha_config_remove_label("my_label_id") adds the concrete string-ID usage form, giving a modest bump above baseline.

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

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

States a specific verb (delete/remove) and resource (Home Assistant label) and clarifies it operates on the label registry, which cleanly separates it from siblings like ha_config_remove_category, ha_config_remove_scene, or ha_config_set_label.

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 clear context: use ha_config_get_label() to find label IDs before calling. It does not name a when-not condition or an alternative deletion path, but the retrieval prerequisite is explicit, which is most of what an agent needs.

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 and idempotentHint, but the description adds genuinely new behavioral detail: the 405 failure mode for file-defined scenes, the risk of breaking automations/scripts that call scene.turn_on, and the 4-minute-timeout/approval quirk. That is far beyond what the structured fields 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 and example are front-loaded, then caveats, then the timeout note — a sensible order. The Claude Desktop timeout/approval paragraph is operationally useful but slightly tangential to the tool's semantics, keeping it 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, so return values need no explanation, and the description still covers the mutation's failure modes and blast radius. Nothing an agent needs to invoke this destructive tool 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 both parameters (scene_id, wait) are already documented in the schema. The description's example only echoes the scene_id format the schema already states, adding no syntax or default behavior beyond it, 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 scene') and immediately separates itself from ha_config_set_scene / ha_config_get_scene by its destructive action. The inline example pins down the calling form unambiguously.

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-not condition (YAML-defined scenes cannot be deleted and return 405) plus a concrete alternative path (edit scenes.yaml/configuration.yaml directly), and warns about the consequence of deleting scenes referenced by automations. This is exactly the when/when-not/alternatives guidance the rubric reserves a 5 for.

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 goes further: it discloses the UI-vs-YAML restriction, the specific 405 error, the downstream automation-failure risk, and a timeout/re-approval workaround. That is substantial behavioral context 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?

Purpose and the key restriction are front-loaded in the first two paragraphs, and the warning is clearly flagged. The final Claude Desktop timeout paragraph is somewhat long and environment-specific, but it is operationally useful rather than 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 and annotations carry the safety profile, so the description does not need to explain return values. For a destructive delete tool it covers everything an agent needs: what is deleted, what cannot be deleted, the error to expect, and the side-effect risk.

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 script_id (including the 'script.' prefix-stripping behavior) and wait are already fully documented in the schema. The description only demonstrates script_id via an example and adds no new format or syntax detail, 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 script') and immediately scopes it with an example call. An agent can distinguish it from ha_config_set_script and ha_config_remove_automation 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 states the when-not condition: only UI-created scripts can be deleted, while YAML-defined scripts return 405 and must be edited in the config file. It also warns that deletions may break dependent automations, giving the agent enough to advise a user before acting.

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, but the description adds substantial non-structured context: take-control is one-way and does not free the blueprint (HA keeps counting the automation as a user), a changed alias without config_hash is rejected before writing, and the Claude Desktop 4-minute timeout recovery procedure. This is the behavioral depth 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?

Long, but sectioned (MUST, MODES, IDENTITY, EXAMPLES, TAKE CONTROL) with the hard requirements front-loaded before the detail. Each block earns its place as critical routing or safety information, though the six examples partially restate the schema-documented parameters.

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 11-parameter mutation tool with an output schema and annotations present, the description covers creation, update, rename, disable, run-now, take-control, blueprint conversion, and the BestPracticeKey protocol. Nothing an agent needs to call this correctly appears to be 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 already high (91%), so much parameter meaning is in the schema. The description still adds value beyond it: the identity/rename rejection rule, the relationship between identifier and config['id'], and the per-mode usage of config vs python_transform vs take_control_of_blueprint via concrete examples. A few semantics (e.g. category, wait) are left to 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 pair (create or update) on a specific resource (Home Assistant automation), and immediately differentiates from siblings by routing non-automation logic to ha_config_set_scene and ha_config_set_helper with explicit conditions. An agent can tell this apart from the other config_set_* tools 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?

Gives explicit preconditions (MUST call ha_get_skill_guide first), a prefer-native-over-templates rule, a routing table for the dedicated scene/helper alternatives, three mutually exclusive modes with per-mode requirements, and six worked examples. When-to-use and when-to-avoid are both covered.

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 only flag destructiveHint and openWorldHint; the description adds substantial context beyond them: update replaces the whole event and clears un-supplied description/location, rrule survives an update (no way to express 'no recurrence'), date-only vs datetime forms cannot be mixed, and a Claude Desktop timeout/approval workaround. Nothing here contradicts 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?

Front-loads the core create/update/mode-switch behavior, then uses a bolded exclusions block and concrete examples. It is long for a tool description and the trailing Claude Desktop timeout/approval paragraph is somewhat digressive, but the structure keeps it navigable.

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, return values need no explanation. Given 10 parameters, three modes, and integration-dependent limitations, the description covers the decision-relevant behavior (mode selection, field replacement, recurrence edge cases) without gaps.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: uid is the mode switch into WebSocket update, rrule requires the WebSocket path because the REST service schema rejects recurrence, and recurrence_id/recurrence_range only make sense with uid. Some overlap with schema text (e.g., the end-date exclusivity) keeps it just below the top.

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 precise verb+resource and immediately disambiguates the dual mode: create a one-off event, create a recurrence via WebSocket, or switch to update mode by passing uid. An agent can distinguish this from the get/remove calendar 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?

Contains an explicit 'When NOT to use' block routing to ha_config_get_calendar_events and ha_config_remove_calendar_event, plus the condition for finding a uid. It further narrows applicability with an integration-support matrix (Local Calendar supports create/update; Google Calendar and CalDAV do not).

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 supply openWorldHint=false and destructiveHint=true, so the description doesn't need to restate scope/safety. The description adds genuine behavioral context: the create-vs-update branching driven by category_id, the domain-scoping model, follow-up assignment flow, and a Claude Desktop timeout/approval caveat. It does not cover the destructiveHint implication (what an update overwrites) or permission needs, keeping it 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?

Content is front-loaded with the core create/update rule, followed by a concise conceptual note, examples, and follow-up guidance. The final timeout paragraph is verbose relative to the rest but is genuinely actionable, so it earns most of 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?

With an output schema present, return values need not be described. The description covers creation semantics, scoping, follow-up assignment, and an operational caveat, leaving only the destructive-update semantics unaddressed. Nearly complete for a 4-parameter config tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that category_id's presence toggles create vs update behavior and by demonstrating icon and scope syntax in examples. This is more than the schema fields alone convey.

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+resource ('create or update a Home Assistant category') and explicitly distinguishes categories from labels ('cross-domain') and clarifies categories are domain-scoped. An agent can tell this apart from ha_config_set_label or ha_config_set_automation 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?

It clearly explains the conditional branch: create when category_id is absent, update when present, and gives concrete examples for both. It also tells the agent to follow up with ha_set_entity to assign the category. It stops short of naming explicit alternatives (e.g., ha_config_get_category / ha_config_remove_category) or when-not-to-use conditions, so it is clear but not exhaustive.

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 give destructiveHint=true, and the description goes well beyond that: it warns config 'replaces everything', that combining metadata edits with patch is rejected, that config_hash is required for patch/python_transform, that YAML-mode and strategy dashboards can't be handled here, and documents a real timeout/retry failure mode. This is exactly the behavioral context annotations can't 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-loaded with purpose, then structured MODES, a worked example, and caveats. Almost every section earns its place given 13 parameters and three mutually exclusive paths, though the Claude Desktop timeout paragraph and some repeated mutual-exclusivity notes push it toward the verbose side.

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, multi-mode, 13-parameter tool with no output schema, the description is complete: it covers mode selection, locking via config_hash, storage-vs-YAML boundaries, metadata-update rules, entity-lookup guidance, and failure recovery. 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 already 92%, so the baseline is 3. The description adds genuine mode semantics for the three mutually exclusive write parameters (patch ops, python_transform chaining, config replacement) and explains why config_hash must be refreshed between calls, which the schema does not spell out.

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 precise verb+resource ('Create or update a Home Assistant dashboard') and immediately scopes it further (storage-mode dashboards only). It also names the sibling tools it coordinates with (ha_config_get_dashboard, ha_config_delete_dashboard, ha_get_dashboard_screenshot), so an agent can place it in the CRUD set without guessing.

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 enumerates three mutually exclusive modes with the condition that selects each (patch for known paths, python_transform for loops/pattern changes, config for new/full restructure). It states when-not (YAML-mode dashboards are edited elsewhere), prerequisites (MUST call ha_get_skill_guide first), and routes visual re-checks to a different tool.

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 only supply destructiveHint=true and openWorldHint=false; the description adds far more: deterministic data: URI generation, the ~128KB cap, self-containment requirements, the silent-failure mode where the resource is saved but never renders under CSP, the required hard refresh, and timeout/approval guidance. This is unusually rich disclosure for a mutation tool.

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

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

Front-loads the action and the mutually exclusive parameter rule, then uses bullets for detail. It runs long and the three examples plus the Claude Desktop timeout note are verbose, but nearly every sentence carries actionable 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 4-parameter mutation tool with an output schema (so return values need not be described), the description covers the failure modes, caching requirement, reverse-proxy caveat, and update-vs-create path (resource_id omitted = create), leaving no meaningful 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 would be 3, but the description adds constraints absent from the schema, notably that content supports only 'module' and 'css' (not 'js'), the ~128KB limit, and that relative imports/url() cannot resolve inside a data: URI. These materially change how an agent parameterizes the call.

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 pair ('Create or update a dashboard resource') and immediately scopes the two mutually exclusive modes (inline content vs external URL). It is clearly distinguishable from siblings like ha_config_list_dashboard_resources and ha_config_delete_dashboard_resource.

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 'Provide exactly one of' for content vs url, describes which resource types each mode supports, names the alternative approach when a reverse proxy injects CSP ('Register the code as a file and use url=/local/...'), and gives concrete example flows including the HACS prerequisite order.

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 declaring destructiveHint=true and openWorldHint=false, the description adds substantial behavioral context: groups created here are only removable via ha_config_remove_group, ha_remove_helpers_integrations will not find them, and it notes a Claude Desktop timeout/approval workaround. These details go well beyond the annotations and help the agent avoid misleading cleanup paths.

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 structured with clear sections for exclusions, usage, new/existing behavior, mutual exclusivity, and examples. It is front-loaded and mostly earns its space, though the Claude Desktop timeout paragraph is somewhat long and operationally tangential.

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 an 8-parameter tool with a rich schema, an output schema, and sibling alternatives, the description covers the critical gaps: when to use it versus ha_config_set_helper, how new and existing groups differ, mutual exclusivity, removal behavior, and timeout handling. Nothing essential for correct invocation 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 baseline is 3, but the description adds important semantic constraints not present in the schema: entities, add_entities, and remove_entities are mutually exclusive, new groups require object_id and entities, and existing groups should provide only fields to update. It still does not explain every parameter such as wait, icon, or all_on, so it earns a strong 4 rather than a 5.

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: create or update a service-based Home Assistant entity group via group.set. It immediately differentiates itself from the preferred sibling path, ha_config_set_helper(helper_type="group"), so an agent can distinguish the two 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?

It gives explicit When NOT to use guidance naming ha_config_set_helper as the preferred alternative, and explicit When to use guidance for compatibility with existing group.set/YAML groups or when entity-registry membership is unwanted. This is exactly the routing information an agent needs.

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?

Goes well beyond the destructiveHint/openWorldHint annotations: update is a patch (omitted fields preserved, null clears where allowed), action falls back to a helper_id/subentry_id presence discriminator, flow config keys outside the step data_schema are silently ignored, validation errors return data_schema/menu_options for self-correction, next_step_id is consumed as a list for multi-menu flows, and it even documents a client-side timeout/misapproval recovery. This is unusually rich behavioral disclosure for a mutation tool.

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

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

Front-loaded and logically ordered (purpose → prerequisite → type families → behavior → examples), but it is very long and ends with a bare keyword dump of all 29 helper type names that simply restates the helper_type enum and adds no information. The Claude Desktop timeout paragraph, while practically useful, is operational trivia that dilutes the core contract.

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 description is correctly omitted. Given 43 parameters, three distinct API families, and destructive update semantics, the description supplies the create/update contract, discriminator rules, patch semantics, and worked examples for the non-obvious menu-based types. 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 98%, so the schema already carries the field-level burden and baseline is 3. The description still adds genuine semantics the schema cannot: why to pass action ('a helper_id typo fails as helper not found instead of creating a helper'), the helper_id-presence discriminator for create vs update, step_values for fields two steps declare, and concrete config payloads for menu-rooted types. It stops short of full coverage only because it defers most per-field detail to the schema.

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

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

States a specific verb+resource ('Create or update Home Assistant helper entities and config subentries') with scope (30 types, unified interface). It explicitly partitions the domain into SIMPLE / FLOW / CONFIG_SUBENTRY families and routes out-of-scope work to siblings (otp via ha_set_integration, rename via ha_set_entity), so an agent can distinguish it from ha_config_remove_helpers_integrations and ha_set_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?

Gives explicit prerequisites (MUST call ha_get_skill_guide or consult local skills, helper-selection.md under skill_content), selects the correct parameter family per helper type, and names alternatives and their trigger conditions for otp and renaming. When-to-use and when-to-go-elsewhere are both spelled out.

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 openWorldHint=false, so the mutation risk is known. The description adds real value beyond that: the areas parameter's additive-but-replacing semantics, the 4-minute Claude Desktop timeout with explicit remediation (read back before retrying, wait before approving), and sibling calls needed to complete labeling. It stops short of saying whether omitted fields on an update are preserved or cleared, which matters for a destructive-hint tool.

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

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

Purpose and the create/update rule are front-loaded in the first three lines, and the EXAMPLES section is scannable and earns its space. The final paragraph on Claude Desktop timeouts is long and operationally wordy relative to the rest, slightly diluting focus for a tool that is otherwise tight.

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, return values need no explanation, and the description covers both modes, cross-tool follow-up, and a real failure mode. The remaining gap is update semantics for non-area fields (whether omitting color/icon/description clears them), which an agent needs before performing a destructiveHint update.

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 every parameter including the tricky areas merge/no-op semantics is already documented in the schema, making 3 the baseline. The EXAMPLES block shows realistic parameter combinations and functionally reinforces the schema's create-vs-update contract, but adds no format or constraint detail the schema lacks.

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 pair (create/update) plus the resource (Home Assistant label) and immediately disambiguates the two modes by the presence of label_id. It also explains the concept domain ('cross-domain tagging system for entities, devices, and areas'), which distinguishes it from the sibling config_set_* tools that target single resource types.

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

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

Gives explicit when-to-use conditions (no label_id = create, label_id = update) backed by three concrete examples, and routes to the correct siblings for follow-up work: ha_set_entity, ha_set_device, ha_set_area_or_floor. It also notes the alternative for clearing area labels and warns that the area path replaces rather than merges, so an agent has both the positive and negative paths.

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 only declare destructiveHint=true and openWorldHint=false, but the description adds substantial context: mutual exclusivity of config/python_transform, config_hash optimistic locking, the read-back-after-timeout guidance, the best-practices read-receipt protocol, and the python_transform security allow/deny list with an infinite-loop hang warning.

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 WHEN TO USE / WHEN NOT TO USE structure is front-loaded and useful, but the piece is bloated: the timeout troubleshooting paragraph and the long skill_content explanation dilute focus, and the trailing keyword string ('create update modify edit scene ...') is pure filler that earns no 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 9-parameter destructive tool with an output schema, the description covers modes, activation behavior, locking, and skill prerequisites well. It is close to complete, with only minor residual gaps (e.g., interaction of wait/category with each mode) that the schema largely backstops.

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 89%, so the baseline is 3, but the description earns extra by explaining cross-parameter mode interactions, the config shape contract ('entities' is a dict, not a list), and worked python_transform examples that the schema only gestures at.

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+resource ('Create or update a Home Assistant scene'), and the description further distinguishes the tool from its sibling by naming ha_config_get_scene as the lookup alternative. It also cleanly separates the two operating modes (config replacement vs. python_transform) plus the activate-only path.

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

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

Explicit WHEN TO USE and WHEN NOT TO USE sections map each mode to a concrete scenario (surgical edits -> python_transform, new/wholesale replacement -> config, activation-only -> activate with scene_id). The exclusion clause routes listing/lookup to ha_config_get_scene, naming the alternative 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 flag destructiveHint=true, but the description adds material context annotations cannot carry: take-control is one-way, editing a blueprint's input afterward, the fact Home Assistant still counts the converted script as a blueprint user so deletion stays refused, no completion signal on the reload a write triggers, and the 4-minute timeout workaround. This is genuine 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?

Well front-loaded with the core action, then modes, examples, and caveats in priority order. It is long, and the trailing Claude Desktop timeout paragraph is operational trivia, but nearly every sentence earns its place and the formatting scannable.

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

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

An output schema exists so return values need no explanation, and the description covers mode selection, prerequisites, mutual exclusivity, and destructive side effects for an 11-parameter tool. 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 coverage is 91%, so individual parameter meanings are largely documented already, but the description adds cross-parameter rules beyond the schema: which mode needs which parameter, mutual exclusivity between config/python_transform/take_control, and the run-alone-with-script_id constraint. Slightly redundant with schema descriptions for config_hash and python_transform.

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 a Home Assistant script') and explicitly differentiates from the nearest sibling: scripts use 'sequence', not 'trigger'/'action', and trigger-driven cases should go to ha_config_set_automation. An agent can route correctly 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?

Enumerates four explicit modes with selection criteria (python_transform for surgical edits requires config_hash, config for new/full restructures, take_control_of_blueprint for conversions, run alone with script_id). It also names prerequisites (call ha_get_skill_guide first) and points to alternatives (ha_manage_blueprints substitute for previewing).

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?

Even though annotations cover read-only/idempotent safety, the description adds real behavioral context: partial failures return results with `warnings`, `strict=true` escalates warnings to errors, failed renders return HA's error text plus `line`/`source_line` when the MCP component is installed, and non-truthy condition renders are silently false. Minor gap: no explicit statement that `timeout` produces a distinct failure mode beyond the schema's max.

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 when/when-not/results/examples. Some sentences (the condition-position rationale, the ha_mcp_tools aside) are dense, but each carries actionable content rather than 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 6-param, no-required-arg tool with an output schema, the description covers selection, mutual exclusion of `template`/`condition`, warning/error semantics, and worked examples. Nothing an agent needs to invoke it correctly is missing, and return-shape detail is appropriately left to 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?

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter meaning the schema does not: the interaction between `strict` and `report_errors`, that `strict` applies to templates only, and template-vs-condition exclusivity. It stops short of documenting the default `timeout` behavior or condition-mode timeouts.

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 and dual resource (Jinja2 template render or automation condition check) in Home Assistant. It explicitly contrasts itself with the plain-value siblings ha_get_state and ha_search, so an agent can distinguish it 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?

Dedicated 'When to use' and 'When NOT to use' sections give conditions and name alternatives (ha_get_state/ha_search for single values, native condition/trigger constructs, ha_get_skill_guide for the anti-pattern list). This is explicit routing, not 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 openWorldHint, so the safety profile is covered. The description adds a real environmental constraint not in annotations: 'Requires Home Assistant OS or Supervised.' It does not discuss pagination or call cost, but the output schema covers return values.

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

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

Three short, front-loaded sentences: capability first, then the alternative and mode mapping, then the prerequisite. No filler and nothing repeated from 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?

With an output schema explaining return values, full parameter docs, and annotations covering safety, the only remaining gap an agent faces is environment support — which the description supplies. Nothing needed to invoke the tool 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 goes slightly beyond field-level docs by mapping parameters to intents (slug/details, source/installed for inventory, source/available for discovery). It adds mode-selection meaning, though the format/precedence details remain in the schema.

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

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

States a specific verb and resource ('Get installed or available Home Assistant apps (add-ons), or details for one') and immediately distinguishes itself from the sibling ha_manage_app, which handles changes. An agent can tell the read path from the write path 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 routing: do not use for state/configuration changes, use ha_manage_app instead. It also names the exact parameter combinations for each mode ('slug' for details, source="installed" for inventory, source="available" for discovery), so the agent knows not just when but how.

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 openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: retention is bounded by the stored_traces setting so older runs are unavailable, and the 'state' field's 'stopped'/'running'/error values are decoded. Return-shape gaps are excused by the output schema.

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

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

Front-loaded with what traces are, then organized into numbered modes with inline examples. It repeats some schema param text (detailed, deduplicate) and runs long, but every block earns its place for an 8-parameter tool with two distinct output shapes.

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 8-param, dual-mode read tool with an output schema and full annotation coverage, the description covers purpose, mode selection, retention limits, and status field semantics. 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 coverage is already 100%, so baseline is 3, but the description adds cross-parameter semantics the schema lacks: the run_id-present/absent dichotomy defines two different result shapes, and the note that script-style action paths are always matched regardless of detailed. Slightly above baseline.

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

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

States a specific verb and resource ('Get execution traces for automations and scripts') and immediately scopes it to debugging. The following sentence enumerates exactly what a trace contains, so an agent can distinguish it from sibling config/state tools like ha_config_get_automation or ha_get_logs.

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?

Four numbered usage modes with concrete call examples give explicit when-to-use routing: omit run_id to list, provide run_id for detail, detailed=True for logbook/context, deduplicate=False for per-step variables. Paging guidance (use offset when has_more is true) is also stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, not open-world), and the description adds real value: images return in native format (JPEG/PNG/GIF) and width/height reduce token cost. It does not mention failure modes (offline/unavailable camera) or latency, 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 core action, then constraints, then a usage tip, then an example. Well organized, though the parenthetical example list is slightly verbose and could be trimmed.

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?

No output schema, but the description compensates by stating the return type and formats, and the side-effect profile is carried by annotations. Only error/edge-case behavior (camera offline, invalid entity) is unaddressed, which is a minor gap for a read-only fetch tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds behavior the schema lacks: width/height are for high-resolution cameras and exist to reduce token usage, plus a concrete call example with both params. That is meaningfully beyond the terse 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+resource ('Get a snapshot image from a Home Assistant camera entity') and no sibling in the list provides camera imagery, so it is trivially distinguishable. The follow-on sentence clarifies what the returned image is for.

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 concrete use contexts (security checks, delivery verification, confirming a garage door closed) and a restriction ('Only cameras exposed to Home Assistant are accessible'), which tells the agent when this works. It does not name an alternative tool or state when not to use it, but no sibling overlaps functionally.

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 openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context: pagination semantics, that single-device lookups always return full detail, and protocol-specific return fields (ieee_address, node_id, node_diagnostics). It does not state default page size or error behavior, so not a 5.

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