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?

Beyond the annotations (destructiveHint=true, non-idempotent) it discloses genuinely useful behavior: fire-and-forget semantics, what listener_count vs wildcard_listener_count mean, that a timeout means unconfirmed dispatch, and that context_id/parent_id is the only proof a listener acted. However, it spends most of its length on internal dispatch routing (in-process component vs WebSocket fire_event, REST exception for state_changed) and a Claude Desktop timeout workaround, which is operational trivia rather than behavior an agent needs to select or invoke the tool. The safety-relevant disclosure is diluted by this padding.

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 exclusions are correctly front-loaded, but the body sprawls across five dense paragraphs, most of it covering dispatch internals, error-text provenance, and a client-specific timeout workaround. Several sentences (the recorder being a wildcard listener, the fallback GET /api/events lookup) do not earn their place in a tool description an agent must parse at selection time.

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

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

For a two-parameter fire-and-forget tool with an output schema and full param documentation, this covers more than enough: exclusions, error surfacing, count semantics, and trace-based verification. It loses a point because the volume of low-value routing detail and the confusing 'read the target back before repeating it' instruction make it harder to extract the operative guidance, and the client-specific paragraph reads as extraneous.

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

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

Schema description coverage is 100% for both parameters, so event_type and data are already fully documented, establishing a baseline of 3. The description adds a real constraint beyond the schema (for state_changed the type must be a plain name without / \ ? # or %, and Core enforces a 64-character event-type limit), but only for one narrow route; it offers nothing extra about the data payload.

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 and resource: 'Execute a custom event on the Home Assistant event bus.' It then names what the event is for (event-triggered automations, Node-RED flows, custom integrations), which lets an agent distinguish it from service calls and automation runs without opening the schema.

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

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

Gives an explicit 'When NOT to use' block with two named alternatives and their exact invocation (ha_call_service for entities, ha_config_set_automation(entity_id=..., run_actions=True) to run an automation), plus a positive use case. Both the exclusion and the routing condition are stated.

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

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

Annotations already cover the safety profile (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 declare destructiveHint=true and idempotentHint=true, and the description goes well beyond them: it states that all configuration is destroyed, that an auto-backup can re-create it, that YAML-mode dashboards are immune, and that IDs are resolved to a registry ID before deletion. This is exactly the context a caller needs before firing a destructive, irreversible-looking operation.

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

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

The warning is correctly front-loaded ahead of examples, and the examples block is tight. The closing Claude Desktop timeout paragraph is long and harness-specific rather than tool semantics, which dilutes an otherwise efficient description.

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

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

For a single-parameter destructive tool with an output schema, the description covers the destructive blast radius, the backup recovery route, the YAML-mode limitation, ID/alias resolution, and a concrete example. Nothing an agent needs in order to call it safely 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 100% and already notes that both ID and url_path forms are accepted, so the description's added value is the nuance: hyphens may map to underscores internally, either form is resolved to the real registry ID, and 'default' is an alias for 'lovelace'. That meaning is genuinely absent from the schema, though the failure mode when neither form resolves is unstated.

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 storage-mode dashboard completely') and immediately narrows the scope to storage-mode, which distinguishes it from the sibling read/set dashboard tools and from the YAML-mode case. An agent can identify exactly what this operates on without opening the schema.

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

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

Gives clear conditions: storage-mode only, YAML-mode dashboards cannot be deleted via the API, and 'default' aliases 'lovelace'. It also points to a recovery path via ha_manage_backup(scope='edits', action='restore') and tells the agent to read the target back after a timeout. It stops short of naming the direct alternative for editing (ha_config_set_dashboard) or stating an explicit 'do not use this to update' exclusion, so not a full 5.

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

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

Annotations already declare destructiveHint=true, 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, so the description correctly spends its space on non-obvious traits: config_hash stability across reads of an unchanged automation, and the specific conditions (missing bridge, unloaded/disabled automation) under which references is None and related is substituted. Some of this repeats field semantics that an output schema would carry, which keeps it below 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?

The purpose sentence is front-loaded and the examples are compact, but the middle paragraph is a dense run-on enumerating every return field, and the trailing keyword string ('read inspect fetch view existing automation config triggers conditions actions get show detail') is search-noise that adds nothing for an agent.

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

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

For a one-parameter read tool with an output schema, the definition covers input forms, failure modes, bridge-dependent field fallbacks, and a pointer to the documentation skill — an agent has enough to call it and interpret degraded results. It is somewhat over-complete on return-field detail while under-specifying how this differs from related read tools.

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

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

Schema coverage is 100% and the schema already documents the single parameter, so the baseline is 3. The description earns the extra point by explaining resolution behavior — automation_id is the resolved entity_id, falling back to the raw input — which the schema does not convey.

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

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

The opening sentence gives a specific verb and resource ('Get a Home Assistant automation's stored configuration') and scopes it to the stored body rather than a live state, which separates it from ha_config_get_script, ha_config_get_scene and ha_get_state in the sibling list.

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 the input forms accepted (entity_id like 'automation.morning_routine' or a config id) through two concrete examples, and routes documentation requests to ha_get_skill_guide. It does not say when to prefer ha_get_entity or ha_get_automation_traces instead, so the exclusion guidance is incomplete.

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 carry the read-only/idempotent safety profile, and the description adds real context on top: which fields come back, that uid and recurrence_id are only present when the calendar supplies them, and that those two fields are what the edit/remove tools consume. It does not discuss pagination or truncation behavior when max_results is hit.

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

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

Front-loaded with the core action and scope, followed by return fields, sibling linkage, and two compact examples. Every sentence and example carries information an agent would otherwise have to infer.

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 four-parameter read tool with annotations and an output schema, nothing needed to invoke it correctly is missing: defaults, date-range convention, entity discovery path, and downstream use of uid are all covered.

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

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

Schema coverage is 100%, so the baseline is 3, but the worked examples demonstrate the start/end pairing convention and the entity-only default call, which adds practical meaning beyond the field docs. max_results is left entirely to the schema.

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

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

States a specific verb (get) and resource (calendar events) plus the scoping dimension (within a time range). It is clearly separable from the sibling tools ha_config_set_calendar_event and ha_config_remove_calendar_event, which it even references by their use of uid/recurrence_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?

Explains the default window (next week) and explicitly routes entity discovery to ha_search(domain_filter='calendar'), plus points at the edit/remove siblings. It does not state any explicit exclusion (e.g., when to prefer ha_get_history or a service call over this), so it falls short of a full 5.

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

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

Annotations already declare 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?

Although annotations already mark this as a safe read operation, the description adds substantial behavior beyond them: config_hash stability, the 200-match truncation limit, YAML dashboard skipping for cross-dashboard searches, default-dashboard warnings, strategy dashboards lacking stored cards, and unknown view_path errors listing available views.

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

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

The description is front-loaded with purpose and exclusions, then organized by mode and caveats, with examples at the end. It is dense and long, but most sentences carry necessary operational detail for an 11-parameter tool; a slightly tighter structure would improve scanability.

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

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

Given the 11 parameters, absence of an output schema, and rich read-only annotations, the description covers modes, caveats, error behavior, return-shape hints (config, view, view_index, config_hash, truncated), and examples. An agent has everything needed to invoke it correctly.

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

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

With 100% schema coverage the baseline would be 3, but the description adds mode-selection semantics and cross-parameter interactions the schema does not: search parameters are AND-ed, entity_id supports wildcards, heading excludes badges, card_type='badge' lists view badges, describe=True uses card_type as a type to describe, and include_config has a storage-mode safety caveat.

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 the specific resource (Lovelace dashboards) and the three modes: list, read one config, or search cards. It explicitly distinguishes itself from sibling tools (ha_get_dashboard_screenshot for renders, ha_search for entity discovery), so an agent can select 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?

The description gives explicit when-not-to-use rules ('Not for a render alone', 'Not for entity discovery') and names the alternatives. It then explains exactly how parameters select each mode, including list_only, search criteria, and default read behavior, with concrete examples.

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

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

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes beyond that with genuinely useful behavior: config_hash is stable across consecutive reads of an unchanged config (enabling change detection), and the returned script_id is canonicalized by the REST client with a documented fallback path. It omits error behavior when the script does not exist.

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 is front-loaded and the examples are cheap and useful, but the paragraph on script_id resolution and prefix-handling mechanism is dense implementation detail for a lookup tool, and the trailing keyword list ("read inspect fetch view existing...") is pure noise. Roughly a third of the text could be cut without losing call-relevant information.

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

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

For a single-parameter read tool with full annotation coverage and an output schema, the definition supplies everything needed to invoke it correctly: lookup forms, id normalization, and hash stability semantics. Only the failure mode (unknown script_id) is left unaddressed, which is a minor gap given the 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% and the schema's script_id description already documents the bare-key and entity_id forms plus the stripping of a leading 'script.' prefix. The description's restatement and its two examples duplicate that schema content rather than adding new parameter meaning, so the baseline 3 applies; the canonicalization notes are about the return value, not the input.

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

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

The description opens with a specific verb and resource ("Get Home Assistant script configuration") and then enumerates what the config contains (sequence, mode, fields). It also distinguishes itself from ha_config_set_script, ha_config_remove_script, and ha_config_get_automation by name, so an agent can place it among the ~60 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?

The purpose is unambiguous read-only retrieval, the two call forms (bare key vs. entity_id) are demonstrated, and an explicit alternative is offered for a related need ("For detailed script configuration help, use ha_get_skill_guide"). It stops short of stating when NOT to use it, e.g. that ha_get_state should be used for runtime state rather than configuration.

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 readOnly/idempotent annotations, it discloses non-obvious behavior: page-level vs aggregate counts (total_count/has_more vs inline_count/by_type), a token-saving preview mode for inline resources, a per-response content budget that yields '_content_truncated', and the constraint that in 'yaml' resource_mode mutations are impossible via the API.

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 pagination/summary semantics are front-loaded and the examples are compact and actionable. The closing note about Home Assistant 2026.6+ UI availability is the least load-bearing sentence, though it does warn that UI availability and API availability differ.

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 paginated list with a full output schema, the description covers everything an agent needs: paging semantics, when previews replace content, truncation signaling, ID availability for follow-up update/delete, and the yaml-mode restriction.

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

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

Schema coverage is already 100%, so the base is 3; the description earns extra by tying parameters to intent — offset for next page, include_content for full content, include_hash for verifying an edit or passing config_hash without refetching. It doesn't add new syntax, but it maps each flag to a concrete 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 gives a specific verb and resource ('List Lovelace dashboard resources') and scopes the content with examples ('custom cards, themes, CSS/JS'), which immediately separates it from siblings like ha_config_get_dashboard or ha_config_set_dashboard_resource.

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

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

It supplies concrete usage contexts (paging with offset=100, include_content=True for full content, include_hash=True to verify an edit) and points at ha_config_set_dashboard_resource for the create path. The one gap is that no explicit 'do not use this to...' exclusion is stated, so the agent must infer that mutations belong to the set/delete siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: one page is returned while total_count/has_more report the full set, `auto` distinguishes service-created from YAML groups, and Core does not expose all/any mode — a useful limitation disclosure.

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

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

Front-loaded with the core purpose, then scope exclusion, then return shape, then a one-line example — logically ordered and free of filler. It is somewhat dense with detail (auto flag, all/any limitation) that could be trimmed, but each 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?

For a read-only paginated list tool with an output schema and full annotation coverage, this covers scope, pagination, member representation, and a known Core limitation. Nothing an agent needs before calling 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% and both limit/offset are documented there, so the baseline is 3. The description adds value by explaining the pagination contract (one page returned, total_count/has_more signal the remainder) and gives a concrete offset example, tying the parameters to observable behavior.

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

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

Specific verb+resource (list Home Assistant entity groups with members) plus an explicit scope boundary: old-style group.set/YAML groups, not platform-specific light/cover groups. An agent can distinguish it from ha_config_set_group and from entity-level tools 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?

Clearly frames when this applies (old-style groups created via group.set or YAML) and warns that platform-specific groups are separate entities, which is a real selection criterion. It stops short of naming a sibling tool for the platform-group case, so it is context-rich but not a full when-to-use/when-not matrix.

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, yet the description adds substantial behavior beyond them: pagination semantics (total_count/has_more), the exact per-record fields, the id vs entity_id resolution distinction and which one ha_config_set_helper resolves against, the degraded-registry case where only id/name survive plus a warning, and COMPONENT_NOT_INSTALLED failure modes for flow types and 'all'. It also discloses scope boundaries (storage-backed vs YAML-defined) and the person 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?

Front-loading is good — purpose, then record shape, then edge cases, then examples. But the body is unusually long and partly redundant, and it ends with an unpunctuated keyword fragment ('list all helpers input_boolean input_number ...') that reads as scraped trailing text rather than guidance, weakening the structure at the exact place an agent expects a clean closing 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?

For a six-parameter listing tool with an output schema, the description is more than sufficient: it covers scope, error modes, degraded behavior, cross-tool dependencies, and worked examples. Nothing an agent needs to invoke it or interpret the result 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, but the description adds real meaning on top: it explains each helper_type class (storage type, listed flow type, 'all'), states that 'all' requires the custom component rather than returning a partial list, and clarifies that describe with helper_id attaches current values. The examples also show offset and menu_choice 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?

Opens with a specific verb and resource: 'List Home Assistant helpers of a specific type with their configurations.' It also names the companion tool (ha_config_set_helper) whose lookup relies on this one, so the agent can separate read-listing from mutation without opening either schema.

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

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

Gives clear when-to-use guidance in two places: 'Call it before ha_config_set_helper to learn the config keys for a type' for describe mode, and 'For detailed helper documentation, use ha_get_skill_guide' as the alternative for docs. It also states the preconditions (ha_mcp_tools component >= 1.1.0) that decide whether a call succeeds. It does not, however, address when to prefer this over generic entity reads such as ha_get_entity.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond them: disabled automations are also deleted, and the response returns the resolved entity_id with a documented fallback. The Claude Desktop timeout workaround is operational context but is client-specific noise rather than general 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 purpose and examples are front-loaded and tight, but the final Claude Desktop troubleshooting paragraph consumes roughly a third of the text and does nothing to help an agent select or correctly invoke this tool. It distracts from the core definition.

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

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

With an output schema, full annotation coverage and 100% schema description coverage, almost all an agent needs is present, including the permanent-deletion and disabled-automation semantics. The only shortfall is the mismatched emphasis on a specific desktop client's timeout quirk rather than general failure handling.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the entity_id-or-config-id duality and the meaning of 'wait'. The description echoes the dual-id acceptance but adds no new syntax or format detail, making 3 the appropriate baseline.

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

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

The opening sentence states a specific verb and resource ('Delete a Home Assistant automation permanently'), and the follow-up clarifies that disabled automations are also removed. An agent can distinguish this from ha_config_set_automation or 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?

Two concrete examples show the two accepted invocation styles (entity_id vs. config id), giving clear usage context. It stops short of naming when to prefer this over a generic sibling like ha_remove_entity, so no explicit exclusions are provided.

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 already declare destructiveHint=true and idempotentHint=true, yet the description adds genuinely new consequences: automations referencing the group may fail, YAML-defined groups reappear after group.reload or restart, and platform-specific groups are out of scope. The Claude Desktop timeout paragraph adds real operational context but is client-specific and reads as noise relative to the core call contract.

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

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

Purpose is front-loaded and the bold when/when-not/warning sections make scanning easy. The final Claude Desktop troubleshooting paragraph is three sentences of client-specific workaround that inflate the definition without helping 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 destructive, 2-parameter tool with an output schema and rich annotations, the description covers everything an agent needs: scope limits, side effects, reversibility caveats, and where to find valid IDs. The presence of an output schema means return values need not be explained.

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%, with object_id's slug format and the wait flag both fully documented in the schema. The description only reinforces object_id via the example ('living_room_lights') and never mentions `wait`, so it does not add meaning beyond the structured fields — baseline 3.

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

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

States a specific verb and resource ('Remove a service-based Home Assistant entity group via the group.remove service') and immediately scopes it to old-style/YAML groups versus config-entry-backed ones. An agent can distinguish it from ha_remove_helpers_integrations and ha_config_set_group 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 provides both a 'When NOT to use' branch with the correct alternative tool and a 'When to use' branch describing which groups this tool can reach. It also names ha_config_list_groups for discovery and gives 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?

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 only declare destructiveHint=true and idempotentHint=false; the description goes far beyond them by disclosing that HA validates the config and returns its own error text, that a changed alias without config_hash is rejected before writing, that best_practice_warnings must be fixed before resubmitting, and that take-control is one-way and does not release the blueprint's user count. It also names the response fields ('operation', 'took_control_of_blueprint'), so the agent knows what to check after a write.

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

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

Purpose is front-loaded and the MODES/IDENTITY/EXAMPLES structure is easy to scan, but the block is bloated: six worked examples plus a lengthy Claude Desktop timeout workaround paragraph that is client-specific troubleshooting rather than tool-selection guidance. Several points (mutual exclusivity of config and python_transform) are stated both in the description and the schema.

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

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

For an 11-parameter destructive write tool with an output schema and annotations, this covers the essential ground: identity/creation semantics, mode preconditions, validation feedback, and take-control consequences. Gaps are minor — `category` and `wait` are never discussed in the description, and the client-specific timeout advice is noise relative to those omissions.

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 earns above baseline by explaining parameter interactions the schema states only in isolation: entity_id alone with enabled toggles state without a config write, run_actions can be used standalone, and the three modes are mutually exclusive. It still leaves `category`, `wait`, and `MandatoryBPS` largely to their schema text.

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

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

Opens with a specific verb+resource ('Create or update a Home Assistant automation') and immediately differentiates itself from siblings by pointing at ha_config_set_scene and ha_config_set_helper for adjacent use cases. The three named modes make the scope of the write operation unambiguous.

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

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

Explicitly routes the agent: dedicated tools first for snapshots, template-derived values, and counters/timers/schedules/booleans; then mode selection (python_transform for surgical edits, config for new/full restructures, take_control_of_blueprint for de-bluerpinting), each with prerequisites. It also states the preconditions for each path (entity_id + config_hash for python_transform, read-before-rename rule), which is exactly the when/when-not guidance this dimension rewards.

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 flag destructiveHint=true, openWorldHint=true and idempotentHint=false, but the description adds substantive behavior beyond them: config 'Replaces everything', patch/python_transform require a config_hash for optimistic locking, metadata updates are rejected when combined with patch, index shifting after delete/add requires chaining operations, and only storage-mode dashboards are handled. The Claude Desktop timeout/hang workaround is operational context not derivable from any structured field.

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

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

The description is front-loaded with the purpose and then organized under labeled MODES, an EXAMPLE, and a storage-vs-YAML scope note, which makes a genuinely complex 13-parameter tool scannable. It is long, and the Claude Desktop hang paragraph plus the external docs URL are marginal relative to the core selection logic, keeping it short of the top mark.

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, open-world, three-mode write tool with no output schema, the definition covers everything an agent needs before calling: which mode to pick, what gets replaced, hash requirements, metadata-only call rules, strategy-dashboard and YAML-mode limits, and post-write verification. The remaining detail lives in the already-rich schema.

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

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

Schema coverage is 92%, so the schema already documents most parameters well; the description's added value is cross-parameter semantics, notably the mutual exclusivity of patch/config/python_transform, the config_hash requirement differing by mode, and the rule that title/icon/require_admin/show_in_sidebar must be sent in a separate call when using patch or python_transform. It does not restate obvious per-field meanings, but it also doesn't explain every parameter (e.g. view_path and return_screenshot are left to the schema).

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

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

The opening line 'Create or update a Home Assistant dashboard' names a specific verb pair and resource. The MODES section then decomposes the tool into its three operating shapes (patch, python_transform, config), which lets an agent distinguish it from siblings like ha_config_get_dashboard and ha_config_delete_dashboard 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?

Guidance is explicit and conditional: patch for 'known paths with literal values', python_transform for 'loops or pattern-based changes', config for 'new dashboards only, or a full restructure'. It also names alternatives and prerequisites (call ha_config_get_dashboard for paths, ha_search/ha_get_overview for entity IDs, ha_get_dashboard_screenshot for re-checks, UI 'Take Control' for strategy dashboards), and states exclusions such as move/copy being unsupported.

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

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

Goes well beyond the destructiveHint=true / idempotentHint=false annotations: it discloses that any failing edit or hash mismatch aborts the whole call and saves nothing, that data: URIs are deterministic and capped at ~128KB, that CSP-blocked resources still report success but never render, and that a hard refresh is required after adding. These are exactly the failure modes an agent cannot infer from annotations.

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

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

Front-loaded with the core rule and organized into scannable per-mode bullets, so structure is strong. The final Claude Desktop timeout paragraph is the one section that sprawls and is tangential to the tool's contract, keeping this 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?

An output schema exists, so return values need no explanation, yet the description still notes that inline writes return the stored content's config_hash. For a destructive, non-idempotent write with six optional parameters, everything an agent needs — mode selection, atomicity, limits, post-write behavior — is covered.

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

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

Schema coverage is already 100%, so the baseline would be 3, but the description adds real meaning: the mutual-exclusivity rule across url/content/edits, the type support matrix (content accepts only 'module' and 'css', url accepts all four types), and why config_hash matters (abort-on-mismatch, with the caveat that it is preflight-only). It also explains that resource_type is ignored for edits.

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?

"Create or update a dashboard resource (inline code or external URL)" gives a specific verb pair, the resource, and the two supported content modes. It is immediately distinguishable from siblings like ha_config_list_dashboard_resources and ha_config_delete_dashboard_resource.

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

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

Explicitly states "Provide exactly one of" the three modes, tells the agent when to prefer edits over content ("small changes to a large card"), and gives an exclusion: store-managed HACS/Marketplace cards need no call because re-adding duplicates them. It also routes to url='/local/...' when a reverse proxy injects CSP — a concrete when-not condition for the content 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?

Beyond the annotations, it discloses important lifecycle behavior: groups are only removable via `ha_config_remove_group`, are not found by `ha_remove_helpers_integrations`, survive group.reload but not restart, and core creates or updates depending on existence. It also states mutual exclusivity among entities, add_entities, and remove_entities, plus a 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?

The description is well structured and front-loads the most important routing guidance: when not to use, then when to use. It is somewhat long, especially the Claude Desktop timeout workaround, but the length is largely justified by the tool's complex behavior and compatibility caveats.

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

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

Given the tool's mutation behavior, 8 parameters, and existing output schema, the description is complete enough for correct invocation. It covers creation/update semantics, lifecycle and removal constraints, restart behavior, mutual exclusivity, and a client-specific failure mode.

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 every parameter well. The description adds value beyond the schema by stating that entities, add_entities, and remove_entities are mutually exclusive and by providing concrete usage examples. It does not need to restate parameter formats, but the extra semantic clarification is helpful.

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

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

The description states a specific verb and resource: create or update a service-based Home Assistant entity group via group.set. It explicitly distinguishes this from config-entry-backed helper groups and names the sibling tool that should normally be used instead.

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

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

It provides explicit 'When NOT to use' and 'When to use' guidance, naming `ha_config_set_helper(helper_type="group", ...)` as the preferred alternative for typical group requests. It also explains the compatibility and registry-membership conditions that select this tool.

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

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

Goes far beyond the annotations (destructiveHint=true, idempotentHint=false): it states that UPDATE is a patch that preserves type-specific fields, that the omitted `action` falls back to a helper_id/subentry_id presence discriminator, that undeclared flow config keys are silently ignored, that validation errors return data_schema/menu_options enabling self-correction, and that repeated menus take `next_step_id` as a list. It even discloses an environment-specific hang/timeout behavior on Claude Desktop, which annotations could never 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?

Well front-loaded and sectioned (purpose → prerequisite → type families → behavior → examples), but bloated: the Claude Desktop timeout paragraph and the trailing keyword dump ('create update new add helper input_boolean...') do not earn their space and read as SEO filler. Roughly a third of the text could be cut with no loss of actionable signal.

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 16-parameter destructive mutation tool, the description covers everything an agent needs: the prerequisite skill call, the type taxonomy, create vs update discriminators, patch semantics on update, config-key expectations, flow self-correction via validation errors, and four concrete examples. With an output schema present, no return-value prose is required, so 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 description coverage is already 94%, so the baseline is 3; the description adds real value on top by explaining the `action` fallback semantics, the create-vs-update discriminator per family, and the shape of `config` per type (e.g. input_datetime has_date/has_time, zone lat/long required) plus the `step_values` escape hatch. It slightly duplicates the schema's own type-by-type key list rather than adding new meaning, which keeps it off 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?

Opens with a specific verb+resource ('Create or update Home Assistant helpers') and immediately scopes it into three distinct families (storage/SIMPLE types, FLOW types read from HA at call time, and config subentries), which is exactly the taxonomy the schema's helper_type accepts. An agent can tell this apart from ha_config_list_helpers or ha_remove_helpers_integrations 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 an explicit prerequisite ('MUST call ha_get_skill_guide OR refer to your locally installed skills first'), an explicit exclusion ('Do not create otp here... user sets it up in the HA UI'), and per-family create/update rules (create needs name, update needs helper_id; flow updates use entry_id because options flows reject name). It stops short of naming read/delete siblings as alternatives, so the routing guidance is context-rich but not fully comparative.

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 already declare destructiveHint=true and idempotentHint=false, but the description adds real behavior: a mandatory skill-guide prerequisite, the fact that a write triggers a Home Assistant scene reload before activate runs, python_transform's sandbox rules (no imports, no while loops, infinite loops hang the server), and a Claude Desktop timeout failure mode with a recovery step. The one gap is that it never says explicitly that a full config replacement discards existing entity entries not present in the new config, which is the main destructive risk 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?

The WHEN TO USE / WHEN NOT TO USE / EXAMPLE structure is well front-loaded, but the description is bloated: the skill-content and Claude Desktop workaround paragraphs sit in the middle of a tool definition, and it ends with raw keyword stuffing ('create update modify edit scene entities snapshot activate apply turn on'). Several sentences restate what the field descriptions already say verbatim, so trimming would cost nothing.

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

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

For a 9-parameter destructive mutation tool with an output schema present (so return values need not be explained), the description covers mode selection, activation, the skill-read protocol, and transform safety. What is missing is failure semantics: what happens on a config_hash mismatch, and what an agent should do when a full replacement is rejected or partially applied.

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 baseline is 3, but the description adds meaning the schema does not: the scene-vs-automation shape contrast ('scenes capture a snapshot of states as a dict', entities keyed by entity_id, not a list) plus a worked config example, and the note that activate alone works even on integration/YAML scenes. The python_transform examples further anchor the field's intent, though the long ALLOWED/FORBIDDEN inventory mostly duplicates the field description.

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

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

The opening line states a specific verb pair and resource ('Create or update a Home Assistant scene'), and the following sections break the tool into three distinct modes (config replacement, python_transform, activate-only). It also names ha_config_get_scene and ha_config_remove_scene as the alternatives, so an agent can separate this tool from its siblings 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?

Explicit WHEN TO USE bullets map each mode to a concrete situation ('surgical edits to an existing scene' vs 'creating a new scene, or wholesale replacement'), and a WHEN NOT TO USE bullet redirects listing/lookup to ha_config_get_scene. A callable example for activate-only is given, 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?

Goes well beyond the annotations (destructiveHint, non-idempotent): take control is one-way and does not free the blueprint (HA still counts the script as a user, so deletion stays refused), the script reload signals no completion, python_transform expressions with infinite loops hang the server, and config_hash provides optimistic locking. The documented 'wait' semantics and the known Claude Desktop hang workaround add further operational context the schema hints at but does not fully explain.

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 and organized with a MODES block and EXAMPLES, but it carries avoidable weight: the appended keyword dump ('create update modify edit script sequence actions new script write save...') earns nothing, and the Claude Desktop timeout paragraph is verbose relative to its payoff. Substantively dense for an 11-parameter tool, so length is partly justified, but trimming is possible.

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

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

For an 11-parameter, multi-mode, destructive write tool with an output schema, this covers what matters: mode selection, required inputs per mode, irreversibility of take-control, reload timing, and best-practice warning reporting under best_practice_warnings. Nothing an agent needs in order to call it safely appears to be missing.

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

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

Schema coverage is 91%, so the baseline is 3; the description still adds real value by explaining cross-parameter constraints the per-property docs cannot — which parameters are mutually exclusive, that python_transform requires config_hash, that run is used alone, and worked examples of config/use_blueprint/take_control payloads. It does not cover wait, category, or BestPracticeKey, leaving those entirely to the schema.

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

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

Opens with a specific verb+resource ('Create or update a Home Assistant script') and immediately draws the boundary against the nearest sibling: scripts use 'sequence', and trigger-based execution belongs to ha_config_set_automation. An agent can route between the two script/automation tools without opening either schema.

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

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

Enumerates four mutually exclusive modes with the condition that selects each (python_transform for surgical edits with config_hash; config for new/restructured; take_control for blueprint conversion; run alone with script_id), and names alternatives — ha_config_get_script for hashes, ha_manage_blueprints(substitute) for previewing without writing. It also excludes: 'write config changes in a separate call first'.

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.