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

Annotations only carry destructiveHint=true and openWorldHint=false, so the description bears the burden of behavioral disclosure — and it delivers richly: parallel-by-default execution, invalid items not aborting valid ones, all-fail batches dispatching nothing, group+member batch failing closed, non-transactional selector dispatch, the 100-entity MAX_SELECTOR_ENTITIES fail-closed cap, and dry_run semantics. This far exceeds what the annotations alone communicate.

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 long but front-loaded: purpose first, then when-not-to-use, then mode-specific behavior in labeled sections. Every paragraph carries non-obvious failure semantics that an agent needs before calling. The density is justified by the tool's complexity (two modes, 8 params, multiple failure modes), though it is heavier than the leanest possible version.

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 high-complexity tool with 8 parameters, two mutually exclusive modes, and destructive behavior, the description covers all decision-relevant context: mode selection, failure behavior, group/member edge cases, entity-count limits, retry guidance, and dry_run. An output schema exists, so return-value documentation is not required. The only minor omission is top-level validate_first/timeout_seconds semantics, which are addressed in the nested 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?

With only 50% schema description coverage (dry_run, parallel, validate_first, and timeout_seconds lack top-level schema descriptions), the description compensates by explaining mode-level semantics: which params combine (operations without selector; selector + action), what exclude_entity_ids does after recursive expansion, what dry_run previews, and the shared timeout behavior. It does not explicitly walk through every top-level parameter, but the gaps are mostly covered by the nested operations schema.

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

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

The description states a clear purpose — managing explicit operations or one deterministic structural bulk action — and immediately distinguishes itself from siblings by naming ha_call_service and ha_search in the 'When NOT to use' section. The two-mode structure (operations vs. selector) gives an agent a precise mental model of what the tool does and what it is not.

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 guidance names the exact alternative tools and the conditions that select them: ha_call_service for service-specific payloads/backend-native group targeting, ha_search for fuzzy discovery. It also gives conditional routing within the tool itself, e.g., 'Use selector mode with exclude_entity_ids when a group action must exclude specific members' and 'narrow it ... and retry' for oversized selectors.

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 annotations (destructiveHint=true), the description reveals fire-and-forget behavior and that tool confirms bus acceptance but not subscriber action. This adds value and does not contradict annotations.

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

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

The description is well-structured with a clear first sentence, usage guidelines section, and caveats. It is concise with no wasted words.

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

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

For a simple tool with two parameters and output schema, the description covers purpose, usage, exclusions, and behavioral caveats. It is fully adequate for an agent to correctly invoke the 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?

With 0% schema description coverage, the description conveys the meaning of event_type (custom event type) and data (optional payload) through context, though it does not explicitly name or detail each parameter.

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 clearly states it executes a custom event on the Home Assistant event bus, providing a specific verb and resource. It also explicitly distinguishes itself from sibling tools like ha_call_service by stating when not to use.

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 provides explicit when-to-use and when-not-to-use guidance, including specific alternatives (ha_call_service for entity control and automation triggering). It also describes the intended use case for event-triggered automations.

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

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

Despite annotations already carrying destructiveHint=true and readOnlyHint=false, the description adds substantial behavioral context: default result compaction that 'trims to the targeted entity's record' and strips context/last_* metadata, the ws_command escape hatch with explicit rejections of 'streaming/two-phase and service-invoking commands', and the Read Only Mode unavailability. The wait parameter's legacy-path fallback with '10s timeout' for multi-target calls is also disclosed.

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

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

Long but every section earns its place: purpose statement, code examples, key behavior (compaction), advanced escape hatch, and mode restriction. The structure is front-loaded with the core purpose and examples before advanced topics, uses clear section headers and formatted code blocks. The density is proportionate to a universal 10-parameter tool.

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

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

Complete for a complex universal tool: covers invocation pattern, examples, result shaping behavior, escape hatches, rejected command types, and mode restrictions. With an output schema present, return values need not be re-explained. The only possible gap, detailed per-service parameters, is explicitly routed elsewhere: 'For detailed service documentation, use ha_get_skill_guide.'

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 already-detailed per-parameter descriptions, so baseline is 3. The description adds genuine value beyond the schema: concrete usage examples mapping data to service parameters (e.g., {'temperature': 22}), the entity_id-wins-over-data precedence, the interplay between result_fields/verbose and the default compaction behavior, and the wait=False recommendation for multi-target 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?

Opens with a specific verb+resource: 'Execute Home Assistant services to control entities and trigger automations.' It then explicitly frames itself as 'the universal tool for controlling all Home Assistant entities' and explains the domain.service pattern with concrete examples. This clearly distinguishes it from siblings like ha_get_state (read), ha_call_event (events), and the config-mutation 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?

Provides explicit when/when-not guidance: 'For detailed service documentation, use ha_get_skill_guide', 'Use ha_get_state() to check current values before making changes', 'Use ha_search() to find correct entity IDs', and 'Unavailable in Read Only Mode... Use dedicated read tools while that mode is enabled.' The ws_command section also clarifies when the advanced path applies versus registered services.

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 indicate destructiveHint=true, but the description adds critical details: permanent deletion, irreversibility, ID resolution behavior, and the restriction on default dashboard. No contradiction with annotations.

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

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

The description is concise and well-structured with a clear warning, bullet-point-like explanation, an example, and a note. Every sentence contributes meaning without redundancy.

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

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

Given the tool's simplicity (single parameter, destructive operation) and the presence of output schema (not shown but indicated), the description covers all necessary aspects: purpose, limitations, parameter details, and an example. No missing information for an AI agent to use it correctly.

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

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

The single parameter url_path is fully covered by schema (100%), but the description adds important context: it accepts both URL path and internal ID, explains hyphens vs underscores, and notes the tool resolves to actual registry ID. This adds value beyond the schema.

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

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

The description clearly states the tool deletes a storage-mode dashboard permanently, using a specific verb and resource. It distinguishes from siblings by specifying it works only on storage-mode dashboards, not YAML-mode, and mentions the default dashboard cannot be deleted.

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 explicitly states when to use (delete storage-mode dashboards) and when not to (YAML-mode, default dashboard). It does not name alternative tools explicitly, but the context implies alternatives like editing config files for YAML-mode.

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 include destructiveHint: true. The description adds important behavioral context: warns that deleting used resources will cause custom cards to fail to load, which goes beyond the annotation.

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?

Concise: action stated first, warning, example, and note. No superfluous words.

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?

Complete for a single-parameter delete tool. Covers what happens, prerequisite, example, and warnings. Output schema exists for return values.

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 covers resource_id with description. Description reinforces with example and advice to get ID from list function. Adds value beyond schema.

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

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

The description clearly states 'Delete a dashboard resource' and explains it removes a resource from Home Assistant. It distinguishes from siblings like ha_config_set_dashboard_resource and ha_config_list_dashboard_resources.

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

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

Provides context for when to use (to delete a resource), a warning about consequences, and an example. Mentions using ha_config_list_dashboard_resources() to find IDs, but doesn't explicitly state when not to use or mention alternatives beyond listing.

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

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

Adds value beyond annotations by explaining config_hash stability across reads, automation_id resolution with fallback, and that it returns the complete config. No contradictions with readOnlyHint and idempotentHint.

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-structured with sections for examples and details. Slightly verbose but not excessive; every sentence adds value. Front-loaded with purpose.

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 output schema existence and annotations, the description fully explains return fields (config_hash, automation_id) and behavior. No gaps for a get config tool.

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

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

Schema coverage is 100%, and description adds meaning by describing identifier as 'Automation entity_id (e.g., 'automation.morning_routine') or unique_id' with examples. Well-explained.

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 clearly states 'Retrieve Home Assistant automation configuration' and details what is returned (triggers, conditions, actions, mode). It distinguishes from sibling tools like ha_config_set_automation (write) and ha_config_remove_automation (delete) by being a read operation.

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

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

Provides examples for calling with entity_id or unique_id, and directs to ha_get_skill_guide for comprehensive docs. While not explicitly stating when not to use, the read-only nature is clear, and examples cover typical usage.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details defaults for start/end, max_results, and the return format (list with fields). This adds operational context not captured by annotations.

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

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

The description is well-structured with clear sections: purpose, parameters, example, note, and returns. It is concise and front-loaded, every sentence adds value.

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

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

Given the low complexity, full schema coverage, and presence of output schema, the description is complete. It explains purpose, parameters, defaults, example usage, and suggests how to find entity IDs.

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. The description repeats schema descriptions but adds practical context through example usage and a note on finding entities, which provides extra meaning for an AI agent.

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 clearly states the verb 'Retrieve' and the resource 'calendar events' from a calendar entity. It is distinct from sibling tools 'ha_config_remove_calendar_event' and 'ha_config_set_calendar_event', making the purpose 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?

The description provides a note on finding calendar entities via 'ha_search' and shows example usage. While it does not explicitly state when not to use, the context of read-only operation is clear from annotations and sibling names.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe, idempotent read. The description confirms read-only behavior (lists, returns configuration). Discloses domain-scoped nature. Does not contradict annotations. Adds details about optional icon, but could mention that the output schema exists (though not shown).

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-organized with sections (overview, properties, examples, related tools). About 10 sentences, but each sentence adds value. Could be slightly more concise by merging the examples into a list, but overall efficient and front-loaded with purpose.

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 simplicity (2 params) and the presence of an output schema (not shown but context indicates coverage), the description covers all behavioral aspects: parameter behavior, returned properties, usage examples, and even mentions external methods for creation and assignment. It is contextually complete for an agent to invoke 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% with both parameters documented. The description adds significant value beyond the schema: clarifies behavior based on category_id presence, lists the returned properties (ID, Name, Icon) not in schema, and provides concrete examples showing parameter usage and expected outputs.

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 explicitly states the tool lists categories for a scope or gets a specific one by ID. It distinguishes itself from sibling tools like ha_config_set_category (create/update) and ha_set_entity (assign to entities). The verb+resource is clear and specific.

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

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

Provides clear when-to-use guidance: without category_id lists all categories for a scope, with category_id returns specific. Includes multiple examples. References ha_config_set_category for creating/updating and ha_set_entity for assigning, giving alternatives and related operations.

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 readOnlyHint=true, openWorldHint=false, idempotentHint=true, so the safety profile is already covered. The description adds substantial behavioral context beyond that: cache-bypassing behavior in search mode, config_hash stability contract, warnings for non-traversed child-bearing shapes, secret-leak avoidance for YAML dashboards, and the view_path response shape change (view + view_index instead of config). It also discloses failure modes (unknown view_path errors and lists available paths; screenshot render failure errors).

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 long but well-structured with clear MODE headers, examples, and a workflow example. Every section earns its place given the tool's four-mode complexity. It is front-loaded with the core purpose and mode summary. Slight redundancy exists (e.g., YAML-mode exclusion appears twice, include_screenshot details appear in both the mode section and the parameter description), but the structure makes the length navigable.

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

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

For an 11-parameter, 4-mode tool with no output schema, the description is remarkably complete. It covers activation conditions for every mode, return-shape differences, error behavior, cache semantics, security considerations (secrets), and the follow-up write workflow. The examples cover all major modes. Nothing an agent needs to select and invoke the correct mode 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. The description adds meaningful semantics beyond the schema: it explains mode interactions (mode='search' takes precedence and ignores list_only/entity_id/card_type/heading), the python_path/jq_path contract with the required `config` prefix, wildcard support, and the include_config payload-multiplication caveat. It doesn't add much per-parameter syntax beyond the schema, but the cross-parameter mode logic is genuinely valuable.

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 clear verb+resource ('Get dashboard info') and then enumerates four distinct modes (List, Search, Get, Search all) with explicit activation conditions. It distinguishes itself from siblings like ha_config_set_dashboard and ha_get_dashboard_screenshot by naming them and stating when to use them 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?

The description explicitly states when each mode activates (e.g., 'MODE 1 — List: list_only=True', 'MODE 3 — Get: Active when list_only=False and no search parameters are provided'), and names alternatives: 'use the dedicated ha_get_dashboard_screenshot tool instead' and 'ha_config_set_dashboard(python_transform=...)' for follow-up writes. It also gives exclusions: YAML-mode dashboards are not included, strategy dashboards are not searchable.

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 provide readOnlyHint and idempotentHint, but description adds value by listing label properties and explaining dual behavior (list vs fetch). No contradiction.

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-structured with sections, examples. Every sentence adds essential information without fluff.

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 low complexity, full schema coverage, and presence of output schema, description is complete with usage, alternatives, and examples.

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

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

Schema coverage is 100%, but description adds meaning: omitting label_id lists all, providing it fetches specific. Also lists returned properties.

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?

Description clearly states it gets label info, lists all labels or a specific one by ID. Differentiates from sibling tools like ha_config_set_label and ha_set_entity.

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

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

Explicitly states when to use with or without label_id, provides examples, and mentions alternative tools for create/update and assigning labels.

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 indicate readOnlyHint and idempotentHint. Description adds that it returns complete config including entities dict and other settings. No contradictions. Sufficiently transparent beyond 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?

Two concise sentences for main description, plus examples and related tools in a well-structured format. Every sentence adds value, no fluff.

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 output schema exists and annotations are rich, description is complete for a read-only retrieval tool: purpose, return fields, examples, and related modifications 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 has 100% coverage with clear description for scene_id. Examples reinforce usage but description adds little beyond schema. Baseline 3 is appropriate.

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

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

Explicitly states 'Retrieve Home Assistant scene configuration' with clear verb and resource. Distinguishes from sibling ha_config_set_scene. Specifies return fields (entities, name, icon, id).

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

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

Provides examples and related tools section pointing to ha_config_set_scene and mentions passing config_hash for updates. Though no explicit 'when not to use', the context and examples give sufficient guidance.

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

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

Adds rich behavioral details beyond annotations: config_hash stability contract, script_id resolution fallback, prefix stripping mechanism. The annotations already mark idempotent and read-only, which the description complements without contradiction.

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-structured with clear sections and examples. The trailing keyword list ('read inspect fetch...') is slightly extraneous but does not detract from clarity. Overall concise and front-loaded with the core purpose.

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 existence of an output schema (not shown but assumed comprehensive), the description provides sufficient context on return values (config_hash, script_id) and behavior. Mentions skill guide for further help, completing the user's informational needs.

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 covers script_id with 100% documentation, but the description adds significant value by explaining the returned script_id resolution, prefix stripping, and behavioral parity with ha_config_get_automation, enhancing the parameter meaning beyond the schema.

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

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

Explicitly states 'Retrieve Home Assistant script configuration' and details the returned content (sequence, mode, fields). Distinguishes from sibling tools like ha_config_set_script and ha_config_remove_script by referencing them in the script_id resolution behavior.

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

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

Provides clear usage context with input examples and notes about prefix stripping. Mentions ha_get_skill_guide for detailed help. Does not explicitly state when not to use this tool, but the read-only nature and sibling relationships are implied.

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

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

Annotations indicate readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral details: pagination via 'one page' and 'total_count'/'has_more', preview for inline resources to save tokens, and summary fields. No contradiction with annotations.

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

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

The description is concise (three sentences) with the main purpose in the first sentence. Every sentence provides essential information without redundancy. It is well-structured and front-loaded.

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 presence of an output schema, the description covers key return fields (total_count, has_more, inline_count, by_type) and explains inline resource behavior. It is sufficient for an agent to use the tool correctly, though it does not detail every field in the output.

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. The description enhances parameter understanding by explaining the practical effect of 'include_content' (preview vs. full content to save tokens), adding context not in the schema. This adds meaningful value beyond the schema alone.

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

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

The description clearly states the tool lists Lovelace dashboard resources and specifies types (custom cards, themes, CSS/JS). It is distinct from sibling list tools like ha_config_list_helpers, but lacks explicit differentiation. However, the purpose is unambiguous and well-communicated.

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 implies usage (listing registered resources) but does not provide explicit when-to-use or when-not-to-use guidance. It does not mention alternatives like ha_config_set_dashboard_resource or ha_config_delete_dashboard_resource, leaving the agent to infer appropriate contexts.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds significant behavioral context: pagination (one page, limit/offset, total_count and has_more reporting), and the specific fields returned. No contradictions with annotations.

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

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

The description is concise and well-structured: a clear opening sentence, a bullet list of returned fields, two examples, and a clarifying note. Every sentence is necessary and earns its place.

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

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

Given the presence of an output schema, comprehensive annotations, and the description covering purpose, pagination, scope, and field list, the description is complete. No gaps are evident for this tool.

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

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

Schema coverage is 100% with descriptions for limit and offset. The description adds value by explaining pagination behavior ('one page' and examples showing usage), which goes beyond the schema's parameter descriptions.

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

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

The description clearly states 'List Home Assistant entity groups with their member entities,' specifying the verb and resource. It differentiates from sibling tools by noting that this returns old-style groups created via group.set or YAML, while platform-specific groups are separate entities.

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 implicitly provides usage context: it is for listing old-style groups, and platform-specific groups are not included. However, it lacks explicit 'when to use' vs alternatives or 'when not to use' guidance, though the note offers some differentiation.

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 description discloses crucial behavioral details: the distinction between storage-based and flow-based types, the handling of renamed helpers (entity_id vs id), the fallback behavior when the registry read degrades, and the fact that each record includes its own helper_type. It also notes that 'all' mode requires the component. These transparency points exceed the bare annotation hints (readOnlyHint, idempotentHint) and provide valuable expectations for callers.

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 excessively verbose and repetitive. It lists the same set of helper types in at least two separate blocks (SUPPORTED HELPER TYPES and EXAMPLES) and again within the note about storage vs flow. It includes redundant examples and a seemingly accidental trailing line 'list all helpers input_boolean input_number input_text counter timer input_datetime input_select'. The overall structure could be streamlined significantly without losing information, making it harder to parse quickly.

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?

The description is comprehensive: it covers error cases (COMPONENT_NOT_INSTALLED), explains the distinction between storage and flow types, details pagination, clarifies the 'all' mode, and mentions integration with the skill guide. Given the tool's complexity (multiple helper types, conditional behavior, pagination), it provides all necessary context for correct usage.

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

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

The input schema fully documents all three parameters (helper_type, limit, offset) with descriptions and ranges. The description goes beyond the schema by explaining the significance of helper_type values, the storage vs flow split, and the behavior of 'all'. It also clarifies pagination semantics. Schema coverage is 100%, and the description adds substantial context, so this dimension is well covered.

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 clearly states the tool's purpose: to list Home Assistant helpers of a specific type. It distinguishes from sibling tools like ha_config_get_helper (retrieves a single helper) and ha_config_set_helper (modifies helpers). The mention of 'list all helpers' and the enumeration of supported types makes the intent 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?

The description provides explicit guidance on when to use this tool, including pagination via limit and offset, the special 'all' mode, and the requirement for the ha_mcp_tools component for flow-based types. It also explains error conditions (COMPONENT_NOT_INSTALLED) and how to enumerate all types. This is thorough and actionable.

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 indicate destructiveness, and the description adds the return value behavior and a warning about permanent deletion. No contradictions.

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 concise with a clear front-loaded purpose, followed by return value explanation, examples, and warning. No unnecessary content.

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 deletion tool with annotations and output schema, the description covers purpose, return behavior, examples, and warning. Could mention error handling or prerequisites but is fairly complete.

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

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

Input schema covers both parameters fully, so baseline is 3. The description adds explanation of the return value depending on identifier but does not elaborate on the 'wait' parameter.

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 clearly states it deletes a Home Assistant automation, with specific verb and resource. It distinguishes from sibling tools by targeting automations specifically.

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 implies usage for deleting automations and provides examples, but does not explicitly state when to use this vs other removal tools, nor any prerequisites or when-not-to-use.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering safety and idempotency. The description adds useful context: it uses the WebSocket 'calendar/event/delete' command, returns success status and confirmation, and clarifies that delete is only available via WebSocket. This supplements the annotations without contradiction.

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 with a clear title, short purpose statement, detailed parameter list, example usage, a note on prerequisite, and return value. Every sentence serves a purpose, and the format is easy to scan. It is appropriately sized for a tool with 4 parameters and an output 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?

Given the tool's moderate complexity (4 parameters, 2 required, output schema exists), the description covers the essential workflow: obtaining the UID, using required and optional parameters, and understanding the return. It could benefit from mentioning error handling or permission requirements, but overall it is sufficiently complete for an agent to use correctly.

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

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

The input schema has 100% description coverage, so baseline is 3. The description repeats parameter descriptions exactly as in the schema and includes examples demonstrating usage. While examples are helpful, they do not add new semantic information beyond what the schema already provides (e.g., recurrence_range values are already documented).

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 clearly states 'Delete an event from a calendar', using a specific verb and resource. It distinguishes itself from sibling tools like ha_config_get_calendar_events (get events) and ha_config_set_calendar_event (set/create event) by explicitly focusing on deletion. The mention of the WebSocket command further clarifies the action.

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

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

The description provides a prerequisite note: use ha_config_get_calendar_events to obtain the event UID before deletion. It also explains that delete operations only exist on WebSocket, contrasting with REST services for create/get. However, it does not explicitly exclude usage for modifications or specify when not to use this tool, leaving a minor gap.

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. The description adds crucial context: 'This will also remove the category assignment from all entities in that scope' and 'This action cannot be undone.' This goes beyond annotations.

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

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

The description is concise: a clear opening sentence, followed by effect, example, reference to get_category, and warning. Every sentence adds value and the structure is front-loaded.

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 presence of an output schema (not shown), the description adequately covers the delete operation's effect and irreversibility. It does not mention error conditions, but this is acceptable for a simple destructive tool with good annotations.

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 descriptions for both parameters. The description adds example usage with parameter names but no additional semantic details beyond what the schema already provides.

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

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

The description clearly states 'Delete a Home Assistant category' with specific verb+resource. Among sibling tools, it is distinct from other removal tools like ha_remove_zone or ha_remove_entity.

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

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

The description explains the scope of use (category registry, given scope) and provides an example. It advises using ha_config_get_category() to find IDs. It could be more explicit about when not to use this tool versus alternatives, but gives sufficient 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?

Adds important behavioral warnings beyond annotations: automations may fail, YAML groups reappear after restart, only removes old-style groups. Annotations already indicate destructiveHint, but description provides specifics.

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-structured with clear sections, warnings, and an example. Front-loaded with main purpose, then conditional guidance. No wasted words.

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 purpose, usage, behavioral traits, and mentions runtime behavior. Missing details on permissions or side effects beyond automations, but overall comprehensive given output schema exists.

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

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

Schema coverage is 100%, so parameters are well-documented. Description adds minimal value beyond schema (only an example usage of object_id). Baseline 3 is appropriate.

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

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

Clearly states the action (remove), resource (service-based Home Assistant entity group), and method (via group.remove service). Differentiates from sibling tools by specifying which groups are covered.

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

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

Provides explicit 'When NOT to use' with reference to sibling tool ha_remove_helpers_integrations, and 'When to use' with examples. Also suggests listing groups first with ha_config_list_groups().

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

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

The description explains that deleting a label removes it from all entities, devices, and areas, and that the action cannot be undone. This adds significant behavioral context beyond the annotations (destructiveHint true, idempotentHint 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 description is well-structured: clear purpose, then details, then example, then warning. Each sentence is informative and necessary.

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 single required parameter, annotations, and presence of an output schema, the description fully covers what the tool does and its effects.

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

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

The schema describes label_id as 'ID of the label to delete' (100% coverage). The description adds value by mentioning where to find label IDs (ha_config_get_label()).

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 clearly states 'Delete a Home Assistant label' and explains the action (remove from registry and assigned entities). It distinguishes itself from sibling tools like ha_config_set_label and ha_config_get_label by its delete operation.

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

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

The description provides an example command and suggests using ha_config_get_label() to find label IDs. It warns about irreversible removal, but does not explicitly state when to use this tool over alternatives.

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

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

Annotations already indicate destructive and idempotent behavior. Description adds critical context: the tool fails with 405 for YAML scenes and may cause automation failures if referenced. No contradiction with 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?

Well-structured with examples, an important limitation section, and a warning. Each element adds value, though the description could be slightly tighter without losing clarity.

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

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

Given the output schema exists, the description adequately covers purpose, limitations, and caveats. It addresses the key behavioral aspects and constraints, making it sufficiently complete for an agent.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description does not add new meaning beyond what the schema provides, meeting the baseline expectation.

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?

Description states 'Delete a Home Assistant scene.' This is a clear verb+resource pair. It distinguishes the tool's scope (scenes) from sibling tools that remove other entities, though it doesn't explicitly differentiate.

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

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

Provides explicit guidance: only UI-created scenes can be deleted; YAML-defined scenes require editing configuration. Also warns about references in automations/scripts causing failures. This clearly tells the agent when to use and when not to use.

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

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

Annotations already provide destructiveHint=true, but the description adds critical behavioral details: the tool only works on UI-created scripts and may break automations. It does not discuss idempotency, but overall adds value beyond 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?

Description is well-structured with sections (examples, limitation, warning). Each part adds value, though slightly verbose. Could be more concise but remains clear and organized.

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 purpose, usage, limitations, side effects, and examples. Given the tool's simplicity (2 params, destructive) and presence of output schema, the description is thorough and leaves no important gaps.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains script_id can be bare key or entity_id with prefix stripping, and clarifies wait default. This extra context merits a 4.

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

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

The description clearly states 'Delete a Home Assistant script' and distinguishes it from sibling tools like automation or scene removal by specifying scripts. The limitation about UI vs YAML-created scripts adds further specificity.

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

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

Provides explicit guidance on when to use (deleting UI-created scripts) and when not to (YAML-defined scripts, instructing to edit configuration directly). Warns about potential automation failures, giving clear context for tool selection.

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

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

Beyond the destructiveHint annotation, the description discloses key behavioral traits: take_control_of_blueprint is irreversible, the blueprint remains counted as in use, alias changes without config_hash are rejected before writing, and infinite python_transform loops can hang the server. It also explains return-value semantics for automation_id and the best-practice checker behavior. No contradiction with annotations.

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

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

The description is long but well-structured with clear headings, examples, and front-loaded critical guidance (MUST call skill, prefer native solutions). Some redundancy exists around repeated skill references and the bottom documentation link, but the length is largely justified by the tool's complexity.

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 tool with 9 parameters, three operating modes, blueprint edge cases, and an output schema, the description is remarkably complete. It covers creation, update, python_transform, blueprint take-control, troubleshooting, return behavior, and alternative tools, leaving little ambiguity for an agent.

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?

Although schema coverage is 89%, the description adds substantial meaning beyond the schema: full config examples, python_transform patterns with allowed/forbidden operations, mode selection rules, mutual exclusivity constraints, identifier/config_hash requirements, and blueprint input examples. This significantly helps an agent construct correct parameter values.

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 clear verb and resource: 'Create or update a Home Assistant automation.' It goes further by naming sibling tools for alternatives (ha_config_set_scene, ha_config_set_helper) and explicitly distinguishing modes, so an agent can tell this tool apart from nearby automation-related tools.

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

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

The description gives explicit when-to-use guidance: use ha_config_set_scene for state snapshots, ha_config_set_helper for computed values, and this tool for automations. It also details which mode to use (python_transform for edits, config for new automations, take_control_of_blueprint for blueprint conversion) and requires calling ha_get_skill_guide 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 mark destructiveHint=true, but the description adds crucial context: exclusive end date for all-day events, requirement for recurrence support, and failure modes for mixed date formats. No contradiction with annotations.

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

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

The description is well-organized into clear sections (purpose, when not to, examples, notes, returns). Every sentence adds value without unnecessary fluff.

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 7 parameters, 4 required, and an output schema, the description covers all critical aspects: differences between event types, integration limitations, return values, and common pitfalls (date mixing, exclusive end). A complete guide 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 through examples (all-day vs timed events, rrule format) and notes on exclusive end dates, which clarifies parameter interaction beyond the schema descriptions.

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

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

The description clearly states the tool creates calendar events, distinguishes between one-off and recurring, and explicitly contrasts with sibling tools for retrieval (ha_config_get_calendar_events) and deletion (ha_config_remove_calendar_event).

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

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

Provides a dedicated 'When NOT to use' section naming specific alternatives, along with multiple examples and detailed notes on date format mixing and integration support. This is explicit guidance.

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

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

The description reveals the tool can create or update, implying mutation. This aligns with the destructiveHint=true annotation. It adds context about domain scoping and update behavior (providing category_id updates). No contradiction with annotations.

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

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

The description is well-structured with clear sections: summary, explanation, and examples. It is front-loaded with the core purpose and is not overly verbose. The examples add length but are helpful.

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 presence of an output schema, the description does not need to explain return values. It covers creation vs update, scoping, and provides examples for typical use cases. It also references a related tool (ha_set_entity) for assigning categories, making it complete for the user.

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 handles basic meaning. The description adds value through examples that clarify usage of icon and category_id, and emphasizes the create/update distinction. While schema already describes each parameter, the examples provide practical 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?

The description clearly states the tool creates or updates a Home Assistant category, specifying the resource (category) and action (create/update). It distinguishes from labels by noting categories are domain-scoped, but does not explicitly differentiate from sibling tools like ha_config_get_category or ha_config_remove_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?

The description provides clear guidance on when to use the tool: create new (no category_id) or update existing (with category_id). It includes examples for each case and references ha_set_entity for assigning categories. However, it does not explicitly state when not to use it or mention alternatives beyond the label comparison.

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 provide destructiveHint=true, so the description carries the burden of behavioral disclosure. It warns about index shifts after delete/add, requires fresh config_hash, explains that move/copy are unsupported in patch, states metadata updates cannot be combined with patch/python_transform, notes strategy dashboards cannot be converted, and details the storage-mode vs YAML-mode limitation. This far exceeds what annotations convey.

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

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

The description is long but well-organized with clear headers, code examples, and front-loaded critical requirements ('MUST call ha_get_skill_guide...'). Some content, such as the extensive Python security whitelist and modern dashboard best practices, could be trimmed or moved to the referenced skill guide, but the structure makes key information easy to locate.

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 complex write tool with no output schema, this description is remarkably complete: it covers prerequisites, mode selection, patch syntax, python_transform security, metadata handling, entity ID discovery, screenshot behavior, and YAML-mode exclusions. An agent has all the context needed to invoke the tool correctly and avoid common pitfalls.

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?

Despite 92% schema coverage, the description adds substantial parameter-level meaning: it gives worked examples for python_transform expressions, explains patch path syntax and escape rules, clarifies config_hash requirements per mode, documents metadata-only calls, and elaborates on the BestPracticeKey read-receipt protocol. This goes well beyond the baseline for high schema coverage.

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?

Description opens with a clear, specific verb+resource statement: 'Create or update a Home Assistant dashboard.' It further distinguishes itself from related siblings by referencing ha_config_get_dashboard for reading config and ha_get_dashboard_screenshot for visual checks, and the detailed mode breakdown (patch/python_transform/config) makes the tool's scope 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?

The description explicitly states when to use each mode under 'WHEN TO USE WHICH MODE' and gives alternative-tool guidance: use ha_config_get_dashboard to get fresh config_hash after index-shifting operations, use ha_get_dashboard_screenshot for visual re-checks instead of return_screenshot, and use ha_get_overview/ha_search for entity discovery. It also clearly excludes YAML-mode dashboards and routes to ha_config_set_yaml for registration edits.

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 description extensively discloses behaviors beyond destructiveHint: true, such as inline content being stored as data: URI, deterministic URLs, ~128KB limit, CSP blocking issues, and supported types per mode. No contradictions with annotations.

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

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

The description is verbose but well-structured with sections, bullet points, and examples. It front-loads the core purpose. Some redundancy exists (e.g., examples could be condensed), but every sentence adds meaningful 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?

Given the tool's complexity (4 parameters, output schema present), the description covers all aspects: purpose, modes, parameters, limitations, examples, and update mechanism. It is fully complete for an AI agent to use 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?

Although schema coverage is 100%, the description adds significant value by explaining mutual exclusivity of url and content, inline mode limitations (supports only 'module' and 'css'), and the source of resource_id (from list). Examples demonstrate parameter combinations.

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 clearly states 'Create or update a dashboard resource (inline code or external URL).' It distinguishes two modes (inline vs URL) and specifies resource types, making the purpose specific and distinct from sibling tools like deletion or listing.

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 provides clear when-to-use guidance by detailing inline vs URL modes, including prerequisites for URL mode (e.g., files in /config/www/ for /local/) and alternatives for CSP-blocked environments. It lacks explicit 'when not to use' but sufficiently implies 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?

While annotations provide destructiveHint: true, the description adds critical context: groups are only removable via ha_config_remove_group (not ha_remove_helpers_integrations) and notes mutex condition among entities, add_entities, remove_entities. No contradiction with annotations.

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

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

The description is well-structured with clear sections (When NOT to use, When to use, For NEW groups, For EXISTING groups, EXAMPLES, NOTE). It is front-loaded with essential information, no unnecessary words, and each sentence serves a purpose.

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 8 parameters and 1 required, the description covers all key use cases (create, update, add/remove entities) and addresses lifecycle considerations. It also notes the existence of an output schema (though not shown). The description is fully adequate for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that entities is required for new groups, explaining the mutex condition, and providing examples that demonstrate parameter usage. This surpasses the schema alone.

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

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

The description clearly states 'Create or update a service-based Home Assistant entity group via the group.set service.' It uses specific verbs (create, update) and resource (group), and distinguishes itself from the sibling tool ha_config_set_helper for typical group creation.

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 explicitly provides when NOT to use (prefer ha_config_set_helper) and when to use (compatibility with existing groups, entity-registry membership unwanted). It also gives clear examples for new and existing groups.

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

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

Beyond the destructiveHint=true annotation, the description discloses rich behavioral traits: update patch semantics (omitted fields keep current value, null clears), silent ignoring of undeclared config keys (with the submit-once-then-read-data_schema recovery protocol), the rename trap ('Options flows reject the name key on update — to rename a flow helper, delete and recreate'), and the multi-menu `next_step_id`-as-list behavior. It also explains that validation errors carry data_schema and menu_options in the response context for self-correction. No contradiction with 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?

Long (~550 words) but structurally justified for a 30-type, 43-parameter tool. It is front-loaded: purpose, prerequisite, type taxonomy, required-parameter patterns, then behavior notes, then examples. The main blemish is minor redundancy — update-preservation semantics and the rename-delete-recreate rule appear in both the description and the schema's `config`/`name` descriptions, and the MUST-call instruction is stated twice.

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 the most complex tool in its family, the description covers everything needed for a correct first call: required arguments per operation type (name vs helper_id vs entry_id/subentry_type/subentry_id), update semantics, silent-failure handling, error self-correction protocol, routing to alternatives, and worked examples for the non-obvious first-call payloads (template, group, tod, config subentry). With an output schema present and annotations covering safety, nothing essential is missing.

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

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

Schema coverage is 98% and the schema itself is exemplary (e.g., `initial` restore-disable semantics, `tag_id` auto-generation, `config` patch rules, `name` flow-update note). The description adds the cross-cutting semantics the schema cannot express: the SIMPLE/FLOW/CONFIG_SUBENTRY taxonomy that maps which parameters apply to which type, entry_id doubling as helper_id for flow updates, and the action-fallback discriminator. This is meaningful added value, though individual parameter meaning was already well covered.

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 'Create or update Home Assistant helper entities and config subentries (30 types, unified interface)' states a specific verb pair, a concrete resource, and the scope in one line. It also distinguishes itself from siblings by explicitly routing the excluded `otp` case to ha_set_integration and clarifying that this is the create/update counterpart to list/remove tools like ha_config_list_helpers and ha_remove_helpers_integrations.

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 states a hard prerequisite ('MUST call ha_get_skill_guide OR refer to your locally installed skills first'), names the one alternative for an excluded case (ha_set_integration(domain='otp')), and points to the helper-selection.md decision matrix shipped in skill_content. It also gives precise when-to guidance for the `action` parameter, explaining the implicit helper_id/subentry_id presence discriminators and when to disambiguate explicitly.

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 description discloses that the tool modifies state (create/update), consistent with destructiveHint annotation. It adds context about the purpose of labels and how assignments work, going beyond the annotation's simple destructive flag.

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 concise, front-loading the core action, followed by a brief explanation and well-structured examples. Every sentence is useful with no redundancy.

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

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

Given the schema coverage, annotations, and presence of an output schema, the description is complete. It explains the create/update behavior, provides examples for all parameters, and links to a related tool for assignment.

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

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

The input schema covers all 5 parameters with descriptions (100% coverage). The tool description adds value through concrete examples showing how to use parameters like color, icon, and description in context, which aids understanding 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?

The description clearly states the tool creates or updates a Home Assistant label, with explicit differentiation between create (no label_id) and update (with label_id). It distinguishes from siblings like ha_config_get_label and ha_config_remove_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?

The description explains when to use create vs update based on label_id presence, and provides examples for various use cases. It also advises on subsequent steps (use ha_set_entity to assign). While it doesn't explicitly state when not to use it, sibling tools cover other operations.

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?

Discloses destructive nature (destructiveHint true) and adds extensive behavior: optimistic locking, mutual exclusivity of parameters, infinite loop risk in python_transform, and a complete list of allowed/forbidden Python operations. No contradiction with 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?

Well-structured with clear sections, front-loaded with purpose and mode overview. The python_transform security section, while lengthy, is justified by the need for safe execution. Could trim slightly but maintains clarity.

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

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

Handles tool complexity comprehensively: covers two modes, prerequisites, security, alternatives, and required preparatory steps (skill guide). With output schema present, return value documentation is unnecessary. No gaps remain.

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?

Adds significant meaning beyond schema (88% coverage): explains config shape (entities as dict, not list), provides python_transform examples and security rules, clarifies config_hash role, and describes BestPracticeKey protocol. Adds example and context for each key parameter.

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?

Clearly states 'Create or update a Home Assistant scene', distinguishing from sibling tools like ha_call_service for runtime activation and ha_search for listing. Explicitly contrasts with ha_config_get_scene and ha_config_remove_scene by defining its role.

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

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

Provides explicit WHEN TO USE and WHEN NOT TO USE sections, detailing two modes (python_transform vs config) with specific prerequisites (config_hash), and names alternative tools (ha_call_service, ha_search) and prerequisite calls (ha_get_skill_guide).

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

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

With annotations only providing destructiveHint:true and openWorldHint:false, the description carries full behavioral disclosure. It warns of infinite loops in python_transform, details the irreversible nature of take_control_of_blueprint, explains that it does not free the blueprint, and describes the best-practice checker and skill_content embedding. It also clarifies side effects like remaining counted as a blueprint user, far exceeding annotation coverage.

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 long but well-structured with clear section headers (MUST call, PREFER NATIVE ACTIONS, WHEN TO USE WHICH MODE, PYTHON TRANSFORM EXAMPLES, SCRIPTS vs AUTOMATIONS, EXAMPLES, TAKE CONTROL). It front-loads the critical prerequisite and preference. Some redundancy exists (e.g., a repeated sentence about creating/updating near the end) and the note about checking documentation is generic, but the overall organization earns its length given tool complexity.

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?

The description covers all critical aspects for correct invocation: mode selection, prerequisites (config_hash), side effects (irreversibility, blueprint usage), interplay with related tools (ha_get_skill_guide, ha_manage_blueprints), and the distinction from automations. With an output schema present, return-value explanation is not required. Nothing an agent needs to call this tool correctly is missing.

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

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

Although schema coverage is high (89%), the description adds substantial meaning beyond the field definitions. It expands on config structure with examples, explains mutual exclusivity between config/python_transform/take_control_of_blueprint, clarifies config_hash's role in optimistic locking, and gives concrete usage examples for each parameter. This enriches the schema without redundancy.

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

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

The description states a specific verb-resource combination ('Create or update a Home Assistant script') and clearly differentiates from the sibling tool ha_config_set_automation, noting scripts use 'sequence' not 'trigger'. It also enumerates three operation modes (config, python_transform, take_control_of_blueprint), giving the agent an unambiguous picture of scope.

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-to-use advice for each mode (python_transform for edits, config for new/full restructures, take_control_of_blueprint for converting), requires a prior call to ha_get_skill_guide or local skills, and names the alternative for trigger-based execution (ha_config_set_automation). It also states that python_transform requires config_hash from ha_config_get_script. This leaves no ambiguity about selection criteria.

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 provide readOnlyHint, idempotentHint, openWorldHint. Description adds context about access to all HA states, security model, timeouts, and performance impact. No contradiction with 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?

Well-structured with sections and examples, but overly verbose with a large catalog of common template functions. Could be more concise while retaining essential 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?

Covers purpose, usage guidelines, parameter details, common functions, examples, and important notes. Output schema exists, so return values need not be described. Complete for the tool's complexity.

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

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

Schema description coverage is 0%, but the description compensates with a 'Parameters:' section giving clear one-line explanations for each parameter (template, timeout, report_errors). Adds meaning beyond the bare 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?

Clearly states 'Evaluate Jinja2 templates using Home Assistant's template engine', with specific verb and resource. Distinguishes from sibling tools like ha_get_state and ha_search by explicitly stating when not to use for plain state queries and providing alternatives.

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

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

Provides explicit when-to-use (one-shot derived answers, template testing) and when-not-to-use (automation/script logic) guidance, with specific alternatives for native constructs. Includes examples and references to ha_get_skill_guide for best practices.

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, openWorldHint, and idempotentHint, covering the safety profile. The description adds useful context beyond annotations: the Home Assistant OS or Supervised platform requirement and that include_stats only applies to installed-app listings. No contradiction with annotations.

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