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

Annotations declare destructive=true/idempotent=false, and the description goes substantially beyond them: fail-closed behavior when every item fails, the group-plus-own-member conflict that silently drops nothing (nothing dispatched), the non-transactional per-leaf failure model, the 100-entity selector cap, and dry_run preview semantics. This is exactly the extra context an agent needs before a destructive bulk 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 purpose and exclusions, then splits modes into labeled paragraphs, which is well structured. However, the trailing Claude Desktop timeout paragraph is long and anecdotal, and mode exclusivity rules are restated in both the description and the schema, so some text does not fully earn its place.

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

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

For an 8-parameter destructive tool, the definition covers both execution modes, failure/abort semantics, exclusion mechanics, batch-size limits, and preview. An output schema exists so return values need no explanation, and annotations carry the safety profile; no gap remains that would cause a misinvocation.

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 schema already documents mode exclusivity (top-level validate_first/timeout_seconds/dry_run rejected in operations mode). The description adds genuine cross-parameter semantics not in the schema: the group/aggregate targeting conflict and its required exclude_entity_ids remedy, plus the >100-entity tightening path — both directly constrain how selector parameters may be combined.

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 ('Manage explicit operations or one deterministic structural bulk action') and immediately disambiguates against named siblings ha_call_service and ha_search. An agent can distinguish this tool from every neighboring tool 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?

Contains an explicit 'When NOT to use' clause naming the two alternatives and the conditions that select them, then explains when to prefer operations mode vs selector mode (exclusions after recursive expansion, group/aggregate conflicts). 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?

Adds behavior the annotations cannot express: the call is fire-and-forget, success only means the bus accepted the event, and no subscriber action is verified. It also documents a concrete failure mode and recovery (Claude Desktop 4-minute timeout, read the target back, delay manual approval) — genuinely operational context beyond readOnly/destructive/idempotent hints.

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

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

Front-loaded with the core action, then cleanly partitioned into when-not, when-to, and caveats. The Claude Desktop workaround paragraph is the longest block and is tangential to tool selection, 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, so return-value explanation is not required, and the description covers purpose, alternatives, and async caveats completely. The one gap is that destructiveHint=true is never reconciled with a tool that merely publishes an event — an agent cannot tell whether the destructiveness comes from the event itself or from downstream automations.

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 (event_type, data) are fully documented in the schema itself, including how data surfaces as trigger.event.data. The description adds no format or syntax detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Execute a custom event on the Home Assistant event bus') and immediately distinguishes itself from the two most confusable siblings by naming them (ha_call_service for entity control, ha_config_set_automation for running automations). An agent can select this tool 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 NOT to use' block names the alternatives and the condition that selects them, and the following paragraph gives the positive use case (event-triggered automations, Node-RED flows, custom integrations). Both when-not and when-to are covered, which is the top of the range.

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 (destructive=true, readOnly=false, idempotent=false), and the description layers on non-obvious behavior: default result compaction and exactly what it strips, the ws_command one-shot restriction with call_service/execute_script rejected, unavailability in Read Only Mode, and the multi-target/wait pitfall. The Claude Desktop timeout-before-retry workaround is unusual but operationally material.

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 when-not/when-to, examples, compaction, the WebSocket escape hatch, and mode gating — every section is headed and information-dense. The single detractor is the trailing Claude Desktop timeout paragraph, which is client-specific and sits far from the call semantics it relates to.

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 10-parameter catch-all with an output schema present, the description covers the routing decision, the two invocation modes, the read-only gate, and the result-shaping behavior that the output schema cannot express. Nothing an agent needs in order to choose and 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 the baseline is 3 and the schema already carries the parameter contract. The description still adds meaning the schema does not: worked examples showing positional domain/service plus data, and the domain.service pattern that governs how these two strings must be supplied. That is a modest but real lift 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+resource ('call any Home Assistant service... the catch-all escape hatch') and immediately frames itself against dedicated siblings, naming them with the exact arguments that select them (ha_config_set_automation, ha_config_set_script, ha_config_set_scene, ha_manage_app, ha_manage_updates, ha_set_integration). An agent can place this tool correctly without opening any schema.

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

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

Explicit when-NOT-to-use (a dedicated tool covers the job) with a concrete routing table of alternatives, followed by an explicit when-to-use (a service no dedicated tool covers), the domain.service naming convention, and a pointer to ha_list_services for discovery. Both the positive and negative conditions are spelled out rather than inferred.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description substantially enriches this: permanent, irreversible, all configuration removed, YAML-mode unsupported, default-dashboard exception, and internal-ID vs url_path resolution semantics. It even flags a known timeout/hang workaround, which is behavior no annotation conveys.

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 destructive WARNING are front-loaded, followed by an example and an edge-case note, which is good ordering. The final Claude Desktop paragraph is verbose and narrow in applicability, costing a point on 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?

For a single-parameter destructive delete with an output schema present, the agent has everything needed: what is destroyed, irreversibility, unsupported targets, ID resolution, and the one undeletable special case. Return values are legitimately omitted since an output schema exists.

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 value beyond the schema by explaining that HA internal IDs may differ from url_path (hyphens become underscores) and that the tool resolves either form before deletion.

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+scope: 'Delete a storage-mode dashboard completely.' This distinguishes it from siblings such as ha_config_delete_dashboard_resource, ha_config_get_dashboard, and ha_config_set_dashboard without needing 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?

Clear when-not conditions are given: it does not work on YAML-mode dashboards and cannot delete the default dashboard. However, it never names the alternative route for those cases (e.g., resource deletion or editing the YAML config), leaving the fallback to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety is covered. The description adds genuine beyond-schema context: the downstream impact (custom cards fail to load) and an operational caveat about Claude Desktop timeouts/hangs. That extra failure-mode detail is valuable, though the timeout workaround is more incidental than core behavior.

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

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

The core purpose, warning, example, and prerequisite note are front-loaded and efficient. The closing Claude Desktop timeout paragraph is three sentences of situational troubleshooting that dilutes focus, costing some 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?

For a single-parameter destructive mutation with an output schema, the description covers purpose, prerequisite discovery, downstream risk, and an example. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and there is only one required parameter with a clear schema description ('Resource ID to delete.'). The description only restates resource_id in the example, adding no format or lookup semantics beyond the schema, so baseline 3 applies.

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

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

The description opens with a specific verb+resource ('Delete a dashboard resource') and clarifies scope as removing a Home Assistant resource so it is no longer loaded on dashboards. It is clearly distinguishable from the sibling set_dashboard_resource / list_dashboard_resources tools.

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

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

Explicitly instructs the agent to call ha_config_list_dashboard_resources() first to find the resource_id, and warns to ensure no dashboards depend on the resource before deleting. When-to-use and prerequisites are both covered, including a concrete example call.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds genuinely new behavior: config_hash is stable across consecutive reads of an unchanged config (a caching/idempotency signal), and automation_id resolution semantics with a fallback to the input identifier. This is context beyond the structured fields, though no error/not-found behavior is described.

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

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

Front-loaded with the core purpose, then return contents, then two examples – a clean progression. The trailing keyword blob ('read inspect fetch view ... get show detail') is pure stuffing that earns no place and drags an otherwise tight description down slightly.

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 documentation is not owed, and the description still covers the parts an agent needs (config_hash stability, id resolution). For a single-parameter, read-only getter with full annotation and schema coverage, nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by confirming identifier accepts either an entity_id or a unique_id and by explaining how that identifier is resolved into the returned automation_id. That resolution/fallback rule is not derivable from the schema alone.

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

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

States a specific verb+resource ('Get Home Assistant automation configuration') and enumerates what the returned config contains (triggers, conditions, actions, mode). The 'automation' resource cleanly separates it from the many sibling tools like ha_config_get_script, ha_config_get_scene, and ha_config_set_automation without needing 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?

Two worked examples show exactly what to pass (entity_id vs unique_id), giving clear invocation context, and it routes documentation questions to ha_get_skill_guide. It stops short of explicit exclusions, e.g. when to prefer ha_get_entity or ha_get_state over this, so it is clear-but-not-complete.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: which fields are returned, the conditional presence of uid/recurrence_id/rrule, and the default 'next week' window. It does not cover pagination or what happens when max_results is exceeded, 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?

Front-loads the purpose in one sentence, then return shape, then entity-discovery routing, then examples. Every sentence carries information an agent needs, 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?

An output schema documents return values, annotations cover the safety profile, and all four parameters are described. Combined with the return-field list and entity-discovery pointer, 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 description coverage is 100%, so the schema already documents entity_id, start, end, and max_results, including the important 'end defaults to 7 days from now, not from start' caveat. The description restates the default window only loosely ('next week') and adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (get) and resource (calendar events) with an explicit scope (within a time range) and names the entity type it reads from. An agent can distinguish it from the set/remove calendar event siblings without opening a schema.

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

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

Explicitly routes entity discovery to ha_search(domain_filter='calendar') and points out that the edit/remove tools consume the uid and recurrence_id this tool returns, telling the agent when to reach for the sibling tools. Two concrete examples cover the default and date-range invocations.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the meaningful behavioral nuance that omitting category_id changes the operation into a list, plus the domain-scoping concept. It does not mention auth/rate limits, but nothing is contradicted.

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 branches, then context, then examples and alternatives. Every sentence earns its place; no filler.

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

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

An output schema exists, so return values need no prose. For a two-parameter, optionally-branching read tool, the description plus annotations plus examples cover everything an agent needs to select and invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description genuinely adds semantics: it spells out the dual effect of optional category_id, gives concrete scope values, and supplies two worked examples. This goes beyond restating 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 category info') and immediately clarifies the dual mode: list all categories for a scope, or fetch one by ID. The domain-scope sentence ('domain-scoped organizational groups for automations, scripts, scenes, and helpers') further anchors what a category is, distinguishing it from siblings like ha_config_get_label or ha_config_list_groups.

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_set_category() to create/update and ha_set_entity(categories=...) to assign. The without/with category_id branches define exactly when each behavior triggers, leaving no inference required.

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 establish the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: 200-match truncation via `truncated`, cache-invariant config_hash, YAML/strategy/default-dashboard search exclusions, and view_path error behavior. It is rich, though a full accounting of every caveat is impossible to verify, so it stops short of a clean 5.

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

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

The opening line front-loads the three modes and the exclusions before the detailed mode breakdown and caveats, and the examples are cleanly separated. It is long, but for an 11-parameter, multi-mode tool nearly every sentence carries load; density is the only minor cost.

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

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

With no output schema, the description carries the return-value burden and does so: it names matched values, jq_path/python_path, config_hash, view/view_index, and truncated. Combined with the caveats section, an agent has everything needed to call and interpret this tool across all modes.

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 per-parameter descriptions are already complete and the baseline would be 3. The description nevertheless adds cross-parameter semantics the schema does not: that search criteria are AND-ed, that list_only is ignored when a search parameter is given, and how each mode is triggered. That mode-selection logic genuinely exceeds the individual schema descriptions.

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

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

Opens with a specific verb+resource: 'Get Lovelace dashboards' and enumerates its three modes (list, read one config, search cards). It explicitly distinguishes itself from siblings ha_get_dashboard_screenshot and ha_search, so an agent can place 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?

Provides explicit when-not guidance ('Not for a render alone... Not for entity discovery: use ha_search') and explains that the parameters select the mode, with examples covering each mode. The alternatives and selection conditions 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the dual-mode list-vs-get semantics driven by parameter presence, which the annotations do not convey.

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

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

Behavioral core is front-loaded, then examples, then cross-references. Every sentence serves a purpose, though the EXAMPLES block and cross-reference list make it longer than strictly minimal.

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 here. For a single-parameter, fully documented read tool, the description covers mode selection, examples, and related sibling routing, leaving no gap an agent needs to fill.

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 the schema's terse 'ID of the label to retrieve' by explaining the consequence of omitting it (returns all labels with configurations) versus supplying it (returns that label's config). It also supplies concrete example 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 verb and resource ('Get label info') and explicitly distinguishes the two modes: listing all labels vs. retrieving one by ID. An agent can tell it apart from ha_config_set_label and the assignment 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?

Names the exact condition selecting each mode ('Without a label_id' vs 'With a label_id') and routes the agent to the correct alternatives: ha_config_set_label for create/update, and ha_set_entity/ha_set_device/ha_set_area_or_floor for assignment. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavior beyond them: listing returns only compact metadata, integration-managed scenes have no editable storage config or scene_id, and config-search results are bounded and explicitly not exhaustive. These are exactly the failure modes an agent would otherwise stumble into.

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 mode split is front-loaded and the guidance, caveats, and examples are cleanly separated into paragraphs. It is denser than strictly necessary — the parenthetical about python_transform updates could be tighter — but every sentence carries routing or behavioral information rather than padding.

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

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

An output schema exists, so return-shape exposition is not required, and the description instead spends its budget on the things structure cannot express: the dual get/list mode, the integration-managed edge case, and the non-exhaustive search caveat. Nothing an agent needs to call this correctly or interpret its results 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, and the description beats it by explaining the purpose of scene_id (retrieving the entities dict and config_hash for editing) and demonstrating search_in_config and query through concrete examples. It stops short of documenting limit/offset semantics, which stay with 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 opening sentence names the exact verb+resource pair and captures both modes ('Get a scene's complete configuration, or list and search scenes without scene_id'), which is a real distinction agents must make. It also explicitly separates itself from ha_search for cross-domain discovery, so the boundary with the most tempting sibling is drawn.

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 states when to use this tool ('For ordinary scene discovery, use this tool'), when to use the alternative ('Use ha_search for cross-domain discovery and dependency searches'), and the downstream workflow (pass the returned scene_id and config_hash to ha_config_set_scene for python_transform updates). The closing pointer to ha_get_skill_guide covers the remaining escalation path.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new behavioral context beyond that — config_hash stability across consecutive reads and the canonical script_id resolution with its fallback path. No auth or rate-limit detail, so not a 5.

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

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

Purpose and return contents are correctly front-loaded, but the REST-envelope fallback paragraph is deep internal detail and the trailing keyword dump ('read inspect fetch view existing script config sequence actions get show detail') is pure filler that 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?

With an output schema present, return-value documentation is not required, yet the description still explains the two notable return fields (config_hash, script_id) and their interpretation. For a read-only single-parameter tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% (baseline 3), and the description goes further by documenting the remote-resolution semantics of script_id: it is the canonical bare storage key that set/remove expect, matching get_automation's prefix handling, with two worked examples of valid input forms.

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 Home Assistant script configuration') and immediately enumerates what the config contains (sequence, mode, fields). It is clearly separable from siblings ha_config_set_script / ha_config_remove_script, which it names and ties back to via the returned script_id.

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 clear context for when this is the right call (reading an existing script's full config) and routes the agent to an alternative for a related need ('For detailed script configuration help, use ha_get_skill_guide'). It does not state explicit when-not conditions or contrast against ha_config_get_automation beyond a parity note, so it stops short of a 5.

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

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

Annotations already establish the safe read profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description usefully adds pagination semantics (total_count/has_more vs per-page), the token-saving inline preview behavior, and the downstream ID contract for update/delete. Some of the return-field explanation overlaps the existing output schema, so it is strong but not maximally additive.

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

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

Purpose is front-loaded in the first sentence, followed by return-shape and pagination detail, then compact examples. The closing note about Home Assistant 2026.6+ UI availability is somewhat tangential, keeping it just short of 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 carrying return values and annotations covering the safety profile, the description only needed to fill pagination, preview/truncation, and ID-usage gaps — all of which it does. Nothing an agent needs 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 description coverage is 100%, so all three parameters are already documented in the schema, including defaults, bounds, and the truncation caveat. The description's examples reinforce offset/include_content usage but add little semantic detail beyond what the schema already supplies, 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 ('List Lovelace dashboard resources') and immediately scopes what a resource is (custom cards, themes, CSS/JS), which distinguishes it cleanly from the sibling set/delete dashboard resource tools. An agent can identify the tool's role 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?

Provides concrete usage examples (offset=100 for the next page, include_content=True for full content) and explains the pagination workflow, plus the pointer that each resource has an ID used for update/delete. It stops short of explicitly naming when NOT to use it or routing to a specific sibling, so it is clear context but not full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: pagination semantics (one page returned, total_count and has_more report the full set) and the exact scope of what is returned versus platform-specific groups.

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

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

Front-loaded with the purpose, then scope, field contents, and a concrete example in roughly four compact sentences. The field enumeration (entity_id, name, state, members, icon, all mode) is slightly list-heavy but still earns its place by telling the agent what a group record looks like.

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 the return-value detail is somewhat redundant, but the pagination framing (total_count/has_more) and the old-style-group scope are the key things an agent needs to call and interpret this correctly. Nothing essential is missing for a read-only paginated list tool.

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

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

Schema description coverage is 100%, so limit and offset are already documented in the schema and the baseline is 3. The trailing EXAMPLE demonstrates offset in use, which is mildly reinforcing, but adds no format or constraint detail the schema does not already carry.

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 clear verb+resource (list Home Assistant entity groups with member entities) and sharpens the scope by excluding platform-specific groups like light or cover groups, which are separate entities. It does not name a specific sibling tool (e.g. ha_config_list_helpers or ha_get_entity) as an alternative, so it falls just short of full sibling differentiation.

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

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

Usage is implied rather than stated: the note that only old-style groups from group.set/YAML are returned tells the agent the result set is narrower than all group-like entities, and the example hints at pagination. There is no explicit when-to-use, when-not, or named alternative tool, leaving the agent to 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavioral context: pagination via total_count/has_more, the COMPONENT_NOT_INSTALLED error conditions, degraded-registry warnings, withheld options, and the person YAML exception.

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 and the examples section is useful, but the description is over-long with redundancy (COMPONENT_NOT_INSTALLED stated twice) and ends with an awkward keyword-stuffed tail ('list all helpers input_boolean input_number ...') that does not earn its place.

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

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

Given six parameters, an output schema, and the type/degradation edge cases, the description covers what an agent needs: record fields, pagination, error modes, and the describe workflow. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: helper_type='all' is component-only and errors rather than returning partial results, and describe/helper_id/menu_choice are tied to the set_helper workflow.

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

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

The opening sentence states a specific verb+resource with scope: 'List Home Assistant helpers of a specific type with their configurations.' It is unambiguous versus write siblings like ha_config_set_helper and is clearly a list/read tool.

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

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

It gives explicit context ('Call it before ha_config_set_helper to learn the config keys for a type') and routes to ha_get_skill_guide for deeper docs. It does not, however, state when NOT to use it or contrast it against near-neighbors like ha_config_list_groups.

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 the safety profile is covered. The description adds real value beyond them: it emphasizes deletion is permanent, explains the returned automation_id resolution/fallback behavior, and documents a known Claude Desktop timeout hang. It stops short of stating required permissions or auth needs.

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

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

The purpose leads, followed by return semantics and compact examples, so it is well front-loaded. The trailing Claude Desktop timeout workaround is a fairly dense tangent that lengthens the definition, though it is framed as actionable and call-specific.

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

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

With an output schema present the description needn't explain return values, yet it usefully clarifies the automation_id resolution anyway. Between annotations covering destructiveness/idempotency and examples covering argument forms, an agent has what it needs to call this 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 both parameters are already documented in the schema. The description reinforces the dual identifier semantics (entity_id or unique_id) and its fallback return behavior but adds little syntax or format detail beyond the schema, matching the baseline for fully-covered schemas.

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 (Home Assistant automation) plus the permanence qualifier, making it easy to distinguish from siblings like ha_config_get_automation and ha_config_set_automation without opening the schema.

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

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

The EXAMPLES block gives concrete invocation patterns (by entity_id and by unique_id) that clarify when to reach for it, and 'permanently' implies this is not the tool for reversible toggling. However, it never explicitly names an alternative (e.g. disable vs delete) or states when not to use it.

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/idempotent/readOnly=false, but the description adds real operational context beyond them: the fact that delete lives only on the WebSocket API (no REST fallback), that recurrence_range is matched verbatim, and a known Claude Desktop timeout/hang workaround. These are exactly the traits annotations cannot express.

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 implementation rationale, examples, and the desktop workaround in a logical order. The implementation explanation is slightly long, but each section earns its place by preventing misuse.

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 API path, prerequisite for obtaining the uid, examples per use case, recurring-event semantics, and a known failure mode. With an output schema present, return-value explanation is unnecessary, leaving nothing material missing for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning by showing how uid pairs with recurrence_id and recurrence_range in real calls and where the uid comes from. It does not add much beyond the schema for recurrence_range, which the schema already documents as verbatim.

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 ('Delete an event from a calendar') and clarifies the exact command path (WebSocket calendar/event/delete). It also distinguishes itself from siblings by pointing at ha_config_get_calendar_events() as the source of the UID, so an agent can tell it apart from the get/set calendar tools.

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

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

Gives a clear prerequisite (obtain the uid from ha_config_get_calendar_events) and concrete examples for both single-event and recurring-range deletion. It does not explicitly state when NOT to use it, but the usage path 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?

Goes well beyond the annotations by disclosing the cascading effect (removes the category assignment from all entities in that scope) and irreversibility, which the destructiveHint flag alone does not convey. It also flags a Claude Desktop hang workaround, adding operational context the structured fields cannot express.

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 purpose and warning are front-loaded and efficient, but the closing Claude Desktop timeout paragraph is disproportionate and reads like internal debugging notes rather than tool-selection guidance, diluting the core message.

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 covering return values and annotations covering the destructive/idempotent profile, the description fills the remaining gaps: cascade behavior, irreversibility, ID discovery, and a worked example. An agent has everything needed to call it safely.

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 documented in-schema, so the baseline is 3. The example clarifies the positional form and typical scope value ('automation'), but adds no constraints or edge cases beyond the schema.

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

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

States a specific verb and resource ('Delete a Home Assistant category') and narrows the scope to the category registry, which cleanly separates it from siblings like ha_config_remove_label, ha_config_remove_scene, and ha_config_set_category.

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

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

Gives a concrete invocation example and explicitly directs the agent to ha_config_get_category() to discover the required category_id. It lacks explicit 'do not use when...' or alternative-routing guidance, but the usage context is clear.

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

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

Annotations only declare destructive/idempotent/readOnly state; the description adds consequences the agent could not infer: automations referencing the group may break, YAML-defined groups reappear after restart, and platform-specific groups are out of scope. It also documents an operational failure mode (Claude Desktop 4-minute hang and the read-back-before-repeat mitigation), which is meaningful behavioral context beyond the structured fields.

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

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

Bold headers and front-loaded purpose make it scannable, and the routing guidance is prioritized correctly. The Claude Desktop workaround paragraph is three sentences of client-specific advice that dilutes an otherwise tight definition, which keeps it out of 5 territory.

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 explained, and the description covers scope limits, persistence behavior, side effects, discovery tooling, and environment-specific failure handling. Nothing needed to invoke this correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents both object_id (with the 'group.' prefix caveat) and the wait flag, so the baseline is 3. The description only reinforces object_id via an example call and adds nothing about the wait parameter or removal timing semantics.

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

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

States a specific verb and resource ('Remove a service-based Home Assistant entity group via the group.remove service') and immediately separates itself from the config-entry-backed siblings it must not be confused with. An agent can distinguish it from ha_remove_helpers_integrations, ha_config_set_group, and ha_remove_entity 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 explicit 'When to use' and 'When NOT to use' sections naming the alternative tool (ha_remove_helpers_integrations) and the exact condition that selects it (helper_type="group" groups). It also points to ha_config_list_groups() for discovery, so both the routing decision and the prerequisite lookup are 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?

Beyond the annotations (destructive=true, readOnly=false, idempotent=true), the description discloses the cascading effect ('removes the label from all entities, devices, and areas') and irreversibility, which the annotations alone do not convey. The Claude Desktop timeout note adds operational context, though it is client-specific rather than tool-semantic.

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 purpose and warning are front-loaded effectively, but the long Claude Desktop workaround paragraph is verbose and tangential to the tool's own semantics, diluting the otherwise tight structure.

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 and annotations covering the safety profile, the description only needs to add cascade behavior and irreversibility, which it does. Nothing essential for a correct call 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 already documents label_id, giving a baseline of 3. The example call showing the ID argument in use adds a small amount of value beyond the schema, warranting a slight bump.

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 label') and reinforces it with 'Removes the label from the label registry'. This cleanly separates it from siblings like ha_config_set_label and ha_config_get_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?

Points the agent to the right companion tool ('Use ha_config_get_label() to find label IDs') and provides a concrete invocation example. It gives clear context but does not state explicit when-not-to-use conditions or compare against other removal tools.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the mutation profile is covered. The description does add real value beyond that: the 405 failure mode for YAML scenes and the automation-breakage warning. However, the annotation set already carries the core safety signal, so the incremental disclosure is moderate rather than decisive.

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, example, error case and warning are front-loaded and tight. The closing Claude Desktop timeout/hang paragraph is client-specific and noticeably longer than the rest, but it does carry actionable operational content, so it isn't padding.

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

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

For a destructive config mutation with an output schema present, this covers the failure mode (405 on YAML scenes), preconditions (UI-created only), the side-effect risk, and a recovery path on timeout. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so scene_id and the wait flag are already documented in the schema itself. The description only echoes scene_id in the example and says nothing about wait, which is the baseline-3 case where 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?

Opens with a precise verb+resource ("Delete a Home Assistant scene") and immediately bounds the scope: only UI-created scenes are deletable. That scope statement cleanly separates it from the get/set scene siblings and from remove_automation/remove_script.

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-not to use it (YAML-defined scenes in scenes.yaml or configuration.yaml return 405) and names the alternative action (edit the configuration file directly). It also flags the downstream consequence of deleting a scene referenced via scene.turn_on.

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, readOnlyHint=false and idempotentHint=true, but the description adds failure modes the annotations cannot convey: the 405 for YAML scripts, the risk that dependent automations break, and a client-specific timeout/hang workaround. This is well beyond the annotation baseline.

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 headline, example, constraint paragraph and warning are front-loaded and each earns its place. The closing Claude Desktop workaround paragraph is long and reads as client-specific troubleshooting rather than tool-selection guidance, slightly diluting an otherwise tight entry.

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

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

With annotations covering the safety profile and an output schema present, the description need not explain return values. It covers restrictions, risk and example usage, leaving only minor gaps around the wait parameter's practical effect.

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 (bare key vs entity_id, prefix stripping) and wait are already documented in the schema. The description's example reinforces the id form but adds no syntax or semantics beyond what the schema states; 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 supplies a concrete example call. An agent can distinguish this from the sibling ha_config_set_script / ha_config_get_script 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 defines the negative condition: only UI-created scripts can be deleted, while YAML-defined scripts return 405 and must be edited in the config file instead. That is a real usability boundary with an alternative path, not just implied context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds far more: take-control is one-way, the blueprint stays locked as a user until the automation is removed, alias changes require config_hash, and there is a documented Claude Desktop timeout workaround. That is substantial context 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?

Front-loaded purpose, clear section headers (MODES, IDENTITY, EXAMPLES, TAKE CONTROL), and every paragraph carries decision-relevant content. It is long for a description, and the trailing keyword list ("create update modify edit...") is search padding that does not earn its place, but the structure prevents it from being unusable.

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, no-required-field tool with an output schema present, the description covers every path an agent needs: creation, update, rename/locking, mode selection, enable/disable, run-now, and blueprint conversion. Nothing material is left implicit.

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 the baseline is 3, but the description meaningfully adds identity resolution semantics (omit identifier/config['id'] to generate an ID; unused raw IDs are literal) and the mode-to-parameter requirements, which the schema only partially conveys. It stops short of 5 because the deep per-parameter detail (e.g. python_transform security rules) lives in the schema, not the description.

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

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

Opens with a precise verb+resource ("Create or update a Home Assistant automation") and immediately differentiates itself from siblings by routing to ha_config_set_scene, ha_config_set_helper, and ha_eval_template for adjacent cases. An agent can tell exactly what this tool is for 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 enumerates the three modes (python_transform/config/take_control_of_blueprint) with the conditions that select each, states when a dedicated sibling is preferable, and calls out mutual exclusivity. When-to-use and when-to-use-something-else 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 declare destructive=true and idempotent=false, but the description adds substantial non-obvious behavior: updates replace the whole event (non-patch), un-supplied description/location are cleared, rrule survives an omitted update (HA cannot express 'no recurrence'), and integration support varies for create/recurrence/update. This is exactly the kind of consequence-level detail 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?

Despite its length it is well front-loaded and organized with headers and examples, and each section carries decision-relevant content. The trailing Claude Desktop timeout paragraph is loosely scoped operational advice that sits outside the tool's core contract, costing it a point.

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

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

Given 10 params, an output schema, and full annotation coverage, the description supplies everything else an agent needs: mode selection, mixing rules, replacement semantics, recurrence quirks, and integration support limitations. 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 baseline is 3, and the description exceeds it by explaining the all-day vs timed distinction, the date/datetime mixing rejection, and the interplay of uid/recurrence_id/recurrence_range for partial-series updates. It stops short of fully restating every parameter, hence 4 rather than 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+resource (create/update calendar event) and then splits the behavior precisely: create via REST service, recurring series via WebSocket when rrule is present, update mode when uid is passed. It also explicitly names sibling tools it is not, so an agent can route correctly without opening schemas.

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

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

Includes an explicit 'When NOT to use' block routing retrievals to ha_config_get_calendar_events and deletions to ha_config_remove_calendar_event, plus a note that finding a uid requires the get tool. It also specifies when create vs update fires (uid presence, rrule presence), covering both alternatives and triggers.

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=false, so the safety profile is covered. The description adds genuinely non-schema context: the create-vs-update branch, and an unusually specific Claude Desktop approval-timeout workaround with recovery guidance. It stops short of stating what an update overwrites (e.g., replacing name/icon on an existing category), which would matter given destructiveHint=true.

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, and the worked examples are compact and directly useful. The closing Claude Desktop timeout paragraph is long relative to its narrow applicability, but it is clearly set apart and does not bury the primary instruction.

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 mode selection, scope semantics, and the assignment follow-up. Minor gaps remain around valid scope values beyond the examples and what an update replaces, neither of which is fatal 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 description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the operational semantics of category_id — omitting it creates, supplying it updates — where the schema only says 'Category ID for updates.' Examples also demonstrate scope and icon usage in context.

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 (create or update) and resource (Home Assistant category), and explicitly names the conditional that selects the mode: omitted category_id means create, present means update. It further distinguishes categories from the sibling concept labels ('unlike labels, categories are domain-scoped'), so an agent can route correctly 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?

Gives clear context for both modes and a concrete follow-up path ('use ha_set_entity(categories=...) to assign it'), which resolves the common 'what next' question. It contrasts categories with labels, an implicit when-to-use guide. It does not name ha_config_get_category or ha_config_remove_category as the read/delete alternatives, so routing for those operations 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 destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description adds substantial context beyond them: config 'Replaces everything', strategy dashboards cannot be converted here, config_hash provides optimistic locking, metadata updates are rejected when combined with patch, and the Claude Desktop timeout behavior. This is far richer than the annotation baseline.

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 front-loaded (purpose, prerequisite, then modes) and nearly every sentence carries operational weight, including the worked EXAMPLE and the mode decision list. Some content, such as the python_transform security pointer and mutual-exclusion notes, overlaps the schema, keeping it from a 5.

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

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

For a 13-parameter, multi-mode, destructive write tool with no output schema, the description covers prerequisites, mode selection, hash/locking requirements, metadata-update constraints, scope limits (storage vs YAML mode), post-write verification, and even a known client hang. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 92%, so the schema already carries most per-parameter meaning (baseline 3). The description adds a layer the schema does not: the mutual-exclusion relationships framed as a mode-selection decision, when config_hash is required vs optional, and that patch values are literal. It stops short of adding new syntax detail beyond the schema.

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

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

Opens with a specific verb+resource ('Create or update a Home Assistant dashboard') and immediately distinguishes the three operating modes (patch, python_transform, config) and the storage-mode-only scope. It also names the sibling tools it is not (ha_config_get_dashboard, ha_config_delete_dashboard, ha_config_set_yaml), so an agent can route correctly 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?

Explicit decision framework: 'MODES (pick one)' with the condition selecting each, a mandatory prerequisite (call ha_get_skill_guide first), guidance to fetch entity IDs via ha_search/ha_get_overview rather than guessing, and named alternatives for follow-up (ha_get_dashboard_screenshot) and for YAML-mode dashboards (ha_config_set_yaml / UI 'Take Control'). When-not-to-use is covered too.

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 destructive=true/idempotent=false; the description adds substantial context beyond them: data: URI embedding with no file storage, deterministic URLs, ~128KB cap, self-containment requirements, the silent-failure mode under a CSP proxy ('this call still succeeds and the card simply never renders'), the required browser cache clear, and the Claude Desktop timeout workaround.

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 the content/url branches, examples, and caveats. Most sentences carry real constraint information, but the trailing Claude Desktop timeout workaround and the long CSP digression make it heavier than it needs to be for 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?

For a mutation tool with subtle semantics, the description covers the create-vs-update path, both input modes, type restrictions, failure modes, and post-call refresh needs; an output schema exists so return values need no explanation. 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 coverage is 100%, but the description adds constraints the schema cannot express: the exactly-one-of relationship between content and url (the schema permits all-null), the fact that content supports only 'module' and 'css' and not 'js', and the size limit on inline content.

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

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

States a specific verb and resource: 'Create or update a dashboard resource (inline code or external URL)', immediately scoping it to dashboard resources rather than the dashboard itself (ha_config_set_dashboard) or the resource list/delete siblings. The inline-vs-URL distinction further pins down what the tool operates on.

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

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

Gives a strong when-to-use rule ('Provide exactly one of: content or url'), explains the choice between them, and gives a when-not with a concrete alternative (on CSP-injecting reverse proxies, register the code as a file and use url='/local/...'). It does not route to sibling tools (e.g., listing resources for IDs or deleting), which keeps it short of a 5.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=false. The description adds lifecycle facts not in annotations: groups created here are only removable via ha_config_remove_group and invisible to ha_remove_helpers_integrations, and config-entry-backed alternatives behave differently. It also warns about a Claude Desktop timeout/hang workaround, which is valuable operational context 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?

Front-loaded purpose followed by bolded when-not/when-to-use sections, parameter rules, and examples. The Claude Desktop timeout paragraph is longer than typical but is targeted operational guidance; overall there is little filler, though the description is more verbose than strictly needed.

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 creation and update modes, alternatives, lifecycle/removal path, mutual exclusivity, and examples. An output schema exists, so return values need not be explained. Complete for a destructive 8-parameter config tool with complex sibling alternatives.

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 adds conditional semantics—object_id plus entities required for new groups, any fields for updates, and mutual exclusivity among entities/add_entities/remove_entities—which goes beyond the schema's per-field descriptions. It does not clarify the roles of wait, all_on, or icon beyond what the schema already says.

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 ('create or update') and resource ('service-based Home Assistant entity group via the group.set service'). It distinguishes the tool from the sibling ha_config_set_helper and explains the alternative. An agent can identify scope 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 names when NOT to use (prefer ha_config_set_helper) and when to use (compatibility with existing group.set/YAML groups, rare case where entity-registry membership is unwanted). It also states mutual exclusivity of entities/add_entities/remove_entities and the different required fields for new versus existing groups. Examples reinforce correct invocation.

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?

Far exceeds the annotations (which only say non-read-only, destructive, non-idempotent). It discloses patch semantics on update (omitted fields are preserved), the action-fallback discriminator, silent ignoring of undeclared flow keys, that validation errors echo data_schema/menu_options for self-correction, and the Claude Desktop timeout workaround. This is unusually rich operational context.

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

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

Front-loaded with the core purpose then logically sectioned by helper category, EXAMPLES, and behavior. Prose is dense but mostly earns its place for a 16-param polymorphic tool. The trailing keyword-stuffing line is pure noise and the Claude Desktop workaround paragraph is tangential, costing it a point.

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

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

For a highly complex, multi-mode mutation tool, the description covers the create/update/reconfigure branches, per-type field requirements, and self-correction via returned data_schema. An output schema exists, so return-value explanation is correctly omitted, and 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 already 94%, so the baseline is 3, but the description adds real meaning beyond it: the per-type config key inventory (input_number min/max/step, zone lat/long/radius, etc.), the step_values escaping mechanism for multi-step flows, and the null-clears-a-field rule. It stops short of clarifying a few of the 16 params (labels/area_id/category are only defined in the schema), so 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+resource ('Create or update Home Assistant helpers') and immediately partitions the space into SIMPLE types, FLOW types, and CONFIG_SUBENTRY, each with its own mechanics. An agent can distinguish this from siblings like ha_config_set_script or ha_config_list_helpers 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 prerequisites ('MUST call ha_get_skill_guide OR refer to locally installed skills first'), a when-not rule (do not create `otp` here because the user enrolls it in an authenticator app), and routes to alternatives for follow-up (ha_config_list_helpers(describe=True), ha_set_entity for renaming). Nothing about tool selection is left to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=false, so the safety profile is carried. The description still adds real behavioral context beyond that: the Claude Desktop timeout/hang workaround, and the subtlety that area assignment is additive rather than replacing. It does not, however, spell out what an update does to fields not supplied.

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 rule is front-loaded in the first sentence and examples are compact and scannable. The closing Claude Desktop paragraph is long and interrupts flow, but it carries non-obvious operational information 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?

With an output schema present and annotations covering safety, the description supplies what is left: create/update semantics, field examples, assignment follow-ups, and a deployment-specific failure mode. 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 100%, so the baseline is 3, but the description adds genuine meaning: label_id's presence is the create-vs-update switch, plus three worked examples showing name/color/icon/description/areas combinations. That is more than the schema's terse per-field strings 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?

States a specific verb (create/update) and resource (Home Assistant label), and the branching rule is explicit: creates when label_id is absent, updates when it is present. It also characterizes labels as a cross-domain tagging system for entities, devices, and areas, distinguishing it from siblings like ha_config_set_category or ha_config_set_group.

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

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

Gives explicit when-to-use guidance (create vs update driven by label_id) and names the follow-up tools for applying the label to entities, devices, and areas. It also routes the agent elsewhere for clearing an area's labels (ha_set_area_or_floor with labels=[]), so the exclusion path is covered too.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, and the description reinforces this by stating 'full config replacement' and 'wholesale replacement'. Beyond that it discloses a hard prerequisite (MUST call ha_get_skill_guide first), optimistic-locking semantics (config_hash REQUIRED for python_transform), mutual exclusivity of modes, activation after reload, and a known Claude Desktop timeout/hang workaround — none of which is in 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-loaded purpose followed by clearly labeled WHEN TO USE / WHEN NOT TO USE / SHAPE / EXAMPLE blocks makes it scannable despite its length. It is somewhat verbose — the Claude Desktop timeout workaround is a multi-sentence tangent and it ends with a keyword-tail ('create update modify edit scene ...') that adds bulk without semantic clarity.

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

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

An output schema exists, so return values need not be explained. For a 9-parameter, dual-mode mutation tool the description covers prerequisites, mode selection, locking, examples, and security constraints for the executable field — everything an agent needs to invoke it correctly.

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

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

Schema description coverage is already 89%, so the schema carries most parameter meaning (including a detailed python_transform security allow/forbid list and config_hash purpose). The description still adds value the schema lacks: a concrete shape contract pointer and a worked example showing the 'entities' dict keyed by entity_id, plus the clarification that 'activate' can be passed alone with scene_id.

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 scene') and immediately decomposes it into three distinct modes (full config replacement, python_transform, activate-only). It explicitly names the sibling it is not for ('To list or look up existing scenes, use ha_config_get_scene'), so an agent can differentiate it 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 explicit WHEN TO USE and WHEN NOT TO USE sections that map each mode to a scenario ('python_transform' for surgical single-entity edits, 'config' for creation/wholesale replacement, 'activate' alone with scene_id). The exclusion routes to the correct alternative tool (ha_config_get_scene). 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?

Beyond the annotations (destructiveHint=true, idempotentHint=false), the description discloses real behavioral traits: take-control is one-way, it does NOT free the blueprint and HA keeps counting the converted script as a user so blueprint deletion stays refused, config writes trigger a reload with no completion signal, and the Claude Desktop timeout workaround. This is exactly the kind of context annotations cannot convey.

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

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

Purpose and prerequisite are front-loaded, then modes, examples, and edge cases follow in a logical order. It is long, and the best-practice/template guidance paragraph partly duplicates content that ha_get_skill_guide serves, but for an 11-parameter, 4-mode tool the length is largely earned.

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 four operating modes, an output schema (so return values need not be described), and rich annotations, the description covers modes, prerequisites, side effects, examples, and even a known client failure mode. An agent has everything needed to select and 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 91%, so the schema carries most parameter meaning; the description adds mode-level semantics that the schema does not (python_transform requires config_hash, run must be used alone with script_id, mutual exclusivity between modes). It stops short of documenting every parameter (e.g. wait, MandatoryBPS, category), which the schema handles.

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 script'), and the description explicitly distinguishes itself from the sibling ha_config_set_automation ('for trigger-based execution use ha_config_set_automation') and clarifies that scripts use 'sequence', not 'trigger'/'action'. An agent can differentiate it from adjacent config 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?

It gives explicit when-to-use routing via a MODES block (python_transform vs config vs take_control_of_blueprint vs run), states the required prerequisite ('MUST call ha_get_skill_guide OR refer to your locally installed skills first'), and names the alternative tool for previewing blueprint rendering (ha_manage_blueprints). 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/non-destructive, so the safety burden is covered. The description still adds real behavioral context: warnings on suspect renders, strict turning them into hard errors, failed renders returning HA error text plus line/source_line, and the condition-testing mode. Some of this (warnings, strict) overlaps the schema, but the return-on-partial-failure behavior is genuine added value.

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

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

Front-loaded with the core action, then labeled sections (When to use / When NOT to use / Results / EXAMPLES) make it scannable. Every sentence carries information; nothing is padding.

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

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

An output schema exists, so return format need not be explained, and the description covers the remaining gaps: two operating modes, error/warning behavior, timeout/strict semantics via schema, and cross-references to sibling tools. 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 100%, so the baseline is 3. The examples go beyond the schema by showing concrete usage of template, variables (with sample trigger data) and condition (including the 'and' combinator), which clarifies how the parameters interrelate and that template/condition are mutually exclusive.

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 (execute/render) and two concrete resources (Jinja2 template, automation condition) in Home Assistant, and explicitly contrasts with the plain-value siblings ha_get_state / ha_search. An agent can distinguish this from every sibling 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?

Contains explicit 'When to use' and 'When NOT to use' sections, names the alternatives (ha_get_state, ha_search, native constructs, ha_get_skill_guide for anti-patterns) and gives the heuristic 'one render beats fetching N states'. This is the full when/when-not/alternatives pattern.

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

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

Annotations already declare readOnly, non-destructive, idempotent, and open-world. The description adds the meaningful prerequisite that this requires Home Assistant OS or Supervised, which is not in the annotations. Output schema covers return values, so no further disclosure is required.

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

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

Three short sentences, front-loaded with the core purpose, then the exclusion, then mode selection and the environment prerequisite. 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?

For a read-only, multi-mode list/detail tool with full schema description coverage and an output schema, the description covers purpose, exclusions, mode selection, and the OS/Supervised requirement. Nothing an agent needs is missing.

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

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

Schema coverage is 100%, so the schema already documents parameter meaning richly (including slug prefix variability and the version vs version_installed nuance). The description restates the slug/source usage but adds no semantics beyond the schema, so baseline 3 is correct.

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

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

States a specific verb (get) and resource (Home Assistant apps/add-ons) with clear scope: installed/available inventory or single-app details. Explicitly distinguishes from the mutating sibling ha_manage_app.

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 for each mode (slug for details, source='installed' for inventory, source='available' for store discovery) and a when-not-to-use clause routing state/config changes to ha_manage_app.

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 read-only/idempotent safety profile, and the description adds real behavioral context on top: traces are retained only for the most recent runs per the stored_traces setting, older runs are unavailable, list mode is paginated via offset/has_more, and 'state' values are defined ('stopped', 'running', or error). It also discloses that trigger-set variables and null entries are omitted regardless of deduplicate.

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

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

Front-loaded with the purpose and the payload contents, then a scannable numbered mode list; length is justified by 8 parameters and three distinct call shapes. Minor redundancy: the deduplicate behavior is explained in both the description and the schema, and the retention note could sit closer to the list mode it constrains.

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, read-only diagnostic tool with an output schema present, the description covers the remaining agent-facing unknowns: what is returned in each mode, retention limits, pagination, and section/flag semantics. An agent can choose the right mode and interpret results without further guessing.

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 a 3 is the baseline, but the description adds operational meaning the schema lacks: worked examples of the automation_id and run_id formats, the offset-when-has_more paging rule, and the caveat that script-style action paths (sequence/, numeric) are always matched regardless of the detailed 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 ('Get execution traces for automations and scripts') plus the goal ('to debug issues'), and enumerates exactly what a trace contains (trigger, condition results, action/branch, errors, variables). This is enough to separate it from config-oriented siblings like ha_config_get_automation and from log/history 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?

The numbered USAGE MODES give explicit conditional guidance: omit run_id to list vs. supply run_id for detail, use offset when has_more is true, detailed=True for logbook/context, deduplicate=False for per-step variables, with literal call examples. It never names an alternative tool (e.g., ha_get_logs or ha_get_history) for when traces are the wrong instrument, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world), yet the description adds genuinely new behavioral detail: the return format (JPEG/PNG/GIF), that the image is returned directly, and that a short text block accompanies it with size and retrieval time in HA local time. It stops short of describing failure modes (e.g., camera offline) but adds real value 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?

Purpose is front-loaded in the first sentence, followed by return detail, exclusions, a parameter tip, and an example. Slightly long and a touch of framing prose ('for visual analysis'), but nearly every sentence 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?

With no output schema, the description correctly explains what comes back (the image plus a size/timestamp text block) and the supported formats. For a single-required-param read tool, nothing an agent needs to invoke and interpret it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the intent behind width/height (reduce token usage on high-resolution cameras) and provides a concrete call example. This complements rather than repeats the schema's own 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 (Get) plus resource (a camera entity's snapshot image) with the exact return described. It explicitly differentiates itself from siblings: 'use ha_search or ha_get_state for those; it returns an image, not state.' An agent can tell it apart from every other ha_ tool 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 concrete when-to-use scenarios (security checks, delivery verification, confirming a garage door closed) and an explicit when-not-to-use rule routing state inspection to ha_search/ha_get_state. It even includes a conditional usage tip for high-resolution cameras (pass width/height to reduce token usage).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: detail_level interaction with list mode, the fact that single-device lookups always return full detail, and which protocol-specific fields (ieee_address, node_id/node_status, node_diagnostics) come back. It does not discuss pagination limits or ordering, but the remaining gap is minor.

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 mode distinction before the example block, and the bolded headers make scanning easy. It is on the long side, but each example line illustrates a distinct parameter combination, so few lines are wasted.

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-value documentation is not required, yet the description still notes protocol-specific return fields, and it covers both call modes, filtering, pagination, and the handoff to ha_manage_radio. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so a baseline 3 applies, but the description goes further by showing how parameters combine (offset=50 for next page, limit=10 with detail_level='full', integration values mapped to protocols) and by clarifying that detail_level is effectively ignored in single-device mode — semantics the schema does not state.

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 device information') and immediately scopes the two operating modes (list with filters vs. single-device lookup). It also enumerates the protocol coverage (Zigbee/ZHA/Z2M, Z-Wave, Matter), which lets an agent distinguish it from generic entity-oriented siblings like ha_get_entity.

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

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

Explicit when-to-use guidance for both modes with concrete invocation examples (offset pagination, area/integration filtering, device_id vs entity_id), plus a routing hint to ha_manage_radio for Matter management. The alternatives and conditions are spelled out rather than inferred.

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