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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description only needs to add context, and it does: the view is session-scoped ("started in this session"), includes recently finished as well as running jobs, and supports incremental polling via the seq/since handshake. The one gap is that it doesn't say how long finished jobs or their lines are retained, which matters for a session-scoped buffer.

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

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

Three sentences, front-loaded with what the tool returns, then the polling contract, then the when-to-use note. Every sentence carries information; the only minor cost is that the parenthetical command list slightly lengthens the first sentence.

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

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

With no output schema, the description must convey the return shape, and it does at a high level (jobs plus their newest output lines, plus a seq cursor). It is enough to call the tool correctly, though the exact envelope (per-job fields, whether finished jobs eventually drop out) is not spelled out.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by tying the two fields together: "Pass back the returned 'seq' as 'since' to get only lines produced after it," explaining the cross-reference the schema alone does not make obvious. The instance_id parameter's refusal behavior is left entirely to the schema, which is acceptable at full 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?

The description names a specific resource (the ESPHome build commands validate/compile/upload/logs started in this session) and states precisely what is returned: each running or recently finished job with its newest output lines. It also explicitly separates itself from the build tools themselves, which return full output only on completion, so an agent can distinguish it from esphome_validate/esphome_compile/esphome_upload/esphome_logs without opening any schema.

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

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

"For watching a long build while it runs; the build tools themselves return the full output when they finish" gives a clear condition for choosing this tool over the one-shot build commands. It stops short of an explicit when-not (e.g. don't poll after the job has finished or after a session restart), but the alternative is named and the context is unambiguous.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: it names what gets destroyed (cached build files), states the transport ('runs over the VomeHome relay — no ports to open'), and prescribes recovery routing for an unreachable error.

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

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

Front-loaded with the core action, then layered with trigger, transport, and troubleshooting in a logical order. Each sentence carries information, though four sentences is slightly more than the minimum needed for a delete operation.

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

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

For a destructive 3-param tool with full schema coverage, annotations, and no output schema, the description covers purpose, trigger, transport, follow-up, and error handling. Nothing essential for correct invocation is missing, though return/confirmation behavior is left implicit.

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

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

Schema description coverage is 100%, so the schema already documents configuration, instance_id, and timeout_seconds. The description reinforces that a configuration is required but adds no syntax, format, or default detail beyond the schema. Baseline 3 is appropriate.

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

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

Opens with a specific verb+resource: 'Delete the cached build files for a configuration.' This clearly distinguishes it from siblings like esphome_compile and esphome_validate, which is exactly the differentiation an agent needs.

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

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

Gives an explicit trigger ('when a compile fails for reasons the YAML does not explain'), a root cause (stale build directory after an ESPHome version change), and the follow-up action ('Then compile again'). It also routes the agent to esphome_dashboard_info for the unreachable case instead of mislabeling it unsupported.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true; the description adds real context beyond them — expected latency of several minutes, that the work runs over the VomeHome relay with no open ports, and how unreachable errors should be handled. It does not describe build-artifact side effects or timeout behavior, but the added operational detail is substantial.

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

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

Four sentences, front-loaded with the core purpose and artifact, followed by latency, transport note, and error routing. Nothing is redundant, though the relay/ports sentence is slightly tangential to selecting or calling the tool.

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

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

With no output schema, the description carries the return-value burden and does so adequately: build output, summarised-by-default behavior is covered by the schema, latency is flagged, and the failure path is routed. Only the exact failure/timeout semantics of a failed compile are left unstated.

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 configuration, full_output, instance_id, and timeout_seconds in detail. The description adds no parameter-level meaning beyond what the schema provides, which makes the baseline 3 correct.

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

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

States a specific verb and resource ('Compile firmware for an ESPHome configuration') plus the return artifact ('build output'), which is enough to distinguish it from siblings like esphome_validate, esphome_upload, and esphome_clean. It does not explicitly name those siblings, so it stops short of a 5.

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

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

Gives clear operational context ('Can take several minutes') and an explicit failure-routing rule: if ESPHome is unreachable, call esphome_dashboard_info rather than reporting it as unsupported. It lacks guidance on when to compile vs validate or upload, so it is not a full 5.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real context beyond that: the tool is a gating check whose result depends on the relay/add-on topology, and it implies a capability answer rather than an action. It does not describe the shape of the 'not reachable' response, but for a read-only probe this is good.

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

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

Front-loaded with the core answer (reachability and what is possible), then the environment note, then the usage trigger. It is somewhat dense with em-dash clauses, but every sentence carries weight and none is redundant.

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?

There is no output schema, so the description must convey what comes back; it does by naming the capability classes it reports (config listing/editing, streaming commands). Combined with the read-only annotation and full param coverage, an agent has enough to invoke and interpret it, though the exact response format remains unspecified.

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?

One optional parameter with 100% schema description coverage; the schema already explains instance_id and the cross-home refusal behavior in detail. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb+resource: reporting whether ESPHome is reachable and enumerating what is possible (config listing/editing and the streaming commands). It is clearly a capability probe, distinguishable from the actual action siblings (esphome_validate, esphome_compile, esphome_upload, esphome_logs, esphome_clean) that it names.

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

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

Gives an explicit trigger: call this before telling a user that flashing or log-reading is unsupported. It also explains the environmental precondition (a VomeHome relay-connected Home Assistant running the Vome add-on) under which everything is available. It does not state when the tool is unnecessary, so it falls short of a 5.

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

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

Annotations only declare destructiveHint=true and readOnlyHint=false; the description goes well beyond them by disclosing atomicity ('Nothing is saved unless every edit applies'), the exactly-one-match constraint, the ordered application of edits, and the two required environment flags (HA_ALLOW_WRITE, HA_ALLOW_CONFIG_WRITE). These are precisely the mutation semantics an agent needs before committing.

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

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

Three tight sentences, front-loaded with the mechanism and the sibling preference, then prerequisites, then the follow-up workflow. Every clause carries information; no filler or restated title.

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

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

For a destructive, in-place file mutation with no output schema, the description covers matching constraints, atomic failure behavior, auth preconditions, and the surrounding validate/upload workflow. An agent has everything needed to invoke it correctly and safely.

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

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

Schema description coverage is 100%, so old_text, new_text, edits ordering, instance_id and configuration are already documented in the schema. The description restates the exact-match/unique-occurrence rule and ordered application, which largely duplicates what the schema provides rather than adding new parameter-level meaning. Baseline 3 is appropriate.

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

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

States a specific verb+resource (change part of an ESPHome configuration file in place) and immediately specifies the mechanism: exact-text replacement matching exactly once. It explicitly names the sibling it supersedes (esphome_save_config) and the reason, so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use rule ('Prefer this to esphome_save_config for any change to an existing file'), the rationale for it (thousands of lines, slow resend, slip risk), and the required follow-up chain (esphome_validate, then esphome_upload). Nothing about tool selection is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only that the target is YAML plus a filename example, and does not disclose return format, error behavior, or whether a missing file errors out.

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?

A single efficient sentence with no padding. It is front-loaded and each clause earns its place, though it is arguably under-specified rather than maximally concise.

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 read-only tool with full schema coverage and annotations carrying the safety profile, the description is nearly sufficient. The main gap is the absence of a hint about what is returned (raw YAML contents) since there is no output schema.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the instance_id scoping/refusal semantics. The description repeats the filename example already present in the schema and adds no new parameter meaning.

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

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

The description states a specific verb (Read) and resource (the YAML for an ESPHome configuration file), which implicitly separates it from esphome_save_config and esphome_edit_config. It does not explicitly name or contrast those siblings, so it stops short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The contrast with esphome_edit_config / esphome_save_config is only inferable from the word 'Read', leaving the agent to reason about selection on its own.

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 openWorldHint=true, so safety is covered. The description adds value beyond that by disclosing the payload content (configuration filenames) and its role as prerequisite data for other tools, though it says nothing about pagination, counts, or failure modes.

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?

One front-loaded sentence that names the operation, its scope, and the returned payload without any filler.

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

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

For a zero-required-param list tool with no output schema, the description covers purpose, output content, and downstream use. It is close to complete, only missing minor return-shape detail such as empty-list behavior.

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

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

Schema description coverage is 100% and the single instance_id parameter is fully documented in the schema, including the refusal-on-mismatch behavior. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb+resource ('List devices/configurations known to the ESPHome dashboard') and scopes it to the ESPHome domain, distinguishing it from the generic ha_list_devices sibling. It also names what the result contains (configuration filenames).

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 parenthetical 'needed by the other ESPHome tools' establishes this as the discovery/enumeration step before other ESPHome operations, which is real usage guidance. It stops short of explicit when-not conditions or naming alternative list tools.

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

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

Annotations only declare readOnlyHint and openWorldHint, but the description adds substantial behavioral context: what each entry contains (old spelling, new spelling, release that changed it), the operational meaning of `required: true` (config will fail to compile vs. works but is on borrowed time), and where the information surfaces in the ESPHome UI. That is real disclosure beyond the structured fields.

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

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

Two short paragraphs with the core capability front-loaded and the required-flag semantics second. Mostly efficient, though 'which is otherwise invisible from here' and 'on borrowed time' are stylistic filler rather than operational information.

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

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

With no output schema, the description correctly compensates by describing the shape of each returned entry and the meaning of its fields, plus the mutation path via esphome_save_config. Nothing an agent needs to call and interpret this read-only tool is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the instance_id refusal behavior. The description does not add format or syntax detail for `configuration` beyond 'a device's YAML', so the baseline of 3 applies.

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

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

States a specific verb and resource ('Report the ESPHome spellings a device's YAML still uses that have since been renamed') and anchors it to a recognizable artifact ('the same Config migration available notice the ESPHome dashboard shows'). An agent can distinguish it from esphome_validate or esphome_get_config without opening any schema.

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

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

Gives clear context for use and routes the follow-up action explicitly ('Apply a rename by editing the YAML with esphome_save_config'), and explains the meaning of the required flag. It does not, however, contrast itself with the closest sibling, esphome_validate, so the agent must infer that validation and migration-checking are different concerns.

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/openWorldHint, but the description adds real behavioral context beyond them: it is a streaming call that returns only when the timeout elapses, it runs over the VomeHome relay with no ports to open, and it specifies failure-handling routing. The summarised-vs-full output behavior is largely already covered by the schema, so it falls just short of 5.

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

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

Front-loaded with purpose, then usage, timeout behavior, transport, and error routing in logical order. Each sentence carries information, though the description is on the longer side for a five-parameter read 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?

With no output schema, the description carries the burden of explaining returns and does so (captured boot messages, connection problems, sensor readings, crashes), plus timeout semantics and relay transport. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description only restates timeout_seconds semantics ('set timeout_seconds to how long you want to watch'), which is largely redundant, so the baseline 3 applies.

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

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

States a specific verb+resource (stream/return logs from an ESPHome device) and enumerates what the logs reveal (boot messages, wifi/API issues, sensor readings, crashes, reboot reasons), which distinguishes it from sibling config/compile/upload tools.

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

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

Explicit when-to-use ('after flashing, or whenever a device is behaving oddly') and routes to a named alternative on failure ('run esphome_dashboard_info to see why rather than telling the user this is unsupported'). Nothing left to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true. The description adds the two env-flag preconditions and the post-write workflow, which are not derivable from annotations. It does not explicitly state that existing content is overwritten, though 'whole: for a new file' implies non-partial writes and destructiveHint covers it.

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?

Tight, front-loaded: scope first, alternative second, preconditions third, workflow last. Every clause is load-bearing. Slightly crowded into one block but 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 3-param write tool with no output schema, the description covers preconditions, the edit alternative, and the downstream validate/upload sequence. Missing only an explicit statement that the file is overwritten in place and whether validation is automatic.

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 per-parameter descriptions, so the schema carries the parameter semantics. The description adds nothing about the yaml or configuration parameters, and the instance_id cross-session guard is only in the schema. Baseline 3 is appropriate.

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

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

Specific verb 'Write' + resource 'ESPHome configuration file' with explicit scope qualifier 'whole: for a new file.' It also names the sibling esphome_edit_config for the partial-change case, making it distinguishable from all siblings at a glance.

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

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

Explicit when-to-use (new file, whole write) vs when-not (partial change → esphome_edit_config), plus required feature flags (HA_ALLOW_WRITE, HA_ALLOW_CONFIG_WRITE) and prescribed follow-up order (validate → upload). This is a complete usage contract.

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

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

Annotations declare the mutation profile (destructive, openWorld, not read-only), and the description adds material context beyond them: write access is required, the build runs first so a failed build 'never reaches the device' (a safety-relevant guarantee for a destructive tool), and it runs over the VomeHome relay with no ports to open.

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

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

Purpose is front-loaded and the following sentences each carry distinct operational information (auth, build-then-flash ordering, relay transport, unreachable-tool routing). Slightly long and drops into one marketing-flavored aside ('no cable, no manual step in the ESPHome UI'), but there is little wasted text.

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

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

For a destructive, no-output-schema tool, the description covers safety ordering, permissions, transport, and failure routing well. The one remaining gap is return/output behavior (the summarising of long output), which is only covered by the full_output schema parameter, not the description.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description's only parameter note ('port' is device address or 'OTA', the default) merely restates the schema, adding no syntax or format detail beyond it. Baseline 3 is appropriate.

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

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

States a specific compound verb and resource: 'Compile and flash firmware to a device over the air.' It also frames the outcome ('This is how you update an ESPHome device'), making its role relative to the compile-only sibling evident without opening a schema.

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

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

Gives explicit routing: use this for over-the-air updates, and if ESPHome is reported unreachable, call esphome_dashboard_info to diagnose 'rather than telling the user this is unsupported.' That names both the condition and the alternative tool, which is exactly what a routing description should do.

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, so the safety profile is covered. The description adds real operational context: it runs over the VomeHome relay with no ports to open, and it tells the agent how to handle an unreachable instance rather than misreporting. Return summarization behavior is useful but partially overlaps the schema.

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

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

Three tightly packed sentences, front-loaded with the core action and then the practical guidance. Every sentence earns its place and none restate the title.

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

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

For a non-destructive validate tool with full annotation and schema coverage, the description covers purpose, the pre-compile workflow position, and error remediation. Nothing an agent needs to invoke it correctly is missing, and no output schema is required since the return is '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 description coverage is 100%, so all four parameters (full_output, instance_id, configuration, timeout_seconds) are already documented in the schema, setting the baseline at 3. The description references 'return the output' but adds no syntax or format detail beyond what the schema provides.

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

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

States a specific verb+resource ('Validate (compile-check) an ESPHome configuration') and immediately frames its scope relative to siblings by saying it's the step before compiling or flashing. An agent can distinguish it from esphome_compile and esphome_upload without opening any schema.

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

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

Explicitly says when to use it ('the fast way to confirm a YAML edit is correct before compiling or flashing'), which implies the alternative (full compile/upload) and the condition selecting this tool. It also routes the agent on failure: use esphome_dashboard_info if ESPHome is unreachable, rather than reporting it unsupported.

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

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

Adds substantial context beyond the annotations: environment requirement (HAOS/Supervised), the authorization model (ha:config scope is authoritative, no HA_ALLOW_WRITE flag needed), and the required follow-up restart and integration step. The 'if missing' wording implies repo-add idempotency. It does not explain the destructiveHint (what a failed or repeated install may affect), so it falls short of a 5.

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

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

Three dense sentences, front-loaded with the core action and followed by prerequisites and post-steps. Every sentence carries information; minor length is justified by the multi-step workflow, though it could be tightened slightly.

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

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

For a multi-step installation tool with no output schema, the description covers the action chain, prerequisites, auth-mode nuance, and required follow-up steps. It is nearly complete, missing only explicit failure/rollback behavior given the destructiveHint.

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 skip_start, instance_id, and repository_url fully. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource chain: adds the VomeSync GitHub add-on repository (if missing), installs the Vome add-on, and starts it. It is distinguishable from generic siblings like ha_hacs_add_repository because it is scoped to the Vome add-on, and it sequences itself against ha_integration_setup_vome by noting the integration step comes afterward.

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

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

Provides clear context for use: 'Developer helper', requires HAOS/Supervised, and notes the brokered-mode scope behavior. It also lays out the post-install flow (restart HA, then add the integration). However, it does not explicitly name alternatives or state when not to use it versus the generic HACS repository tools.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the mutation risk is covered. The description adds genuinely useful context beyond them: the write-enable gate, domain denylist blocking, and that the response returns the changed entities.

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 sentences, front-loaded with the core action and followed by the gating constraint. The parenthetical example is long but earns its place by demonstrating parameter structure; nothing here is filler.

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

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

Without an output schema, the description responsibly states what comes back (the entities that changed), and it surfaces the write gate and denylist behavior an agent must know before invoking. Nested target/data objects are covered by the schema, so remaining gaps are minor.

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

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

Schema description coverage is 100%, so the baseline is 3, but the inline example maps domain/service/data/target to a realistic brightness_pct call and shows the target selector shape, adding practical meaning beyond the field descriptions.

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

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

States a specific verb (call) and resource (Home Assistant service) and immediately shows the exact shape of an invocation with a concrete working example. An agent can tell this is the generic service-dispatch tool, distinct from siblings like ha_update_entity or ha_fire_event, without opening the schema.

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

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

It gives important preconditions ('refused unless writes are enabled', 'blocked for denied domains') but never says when to prefer this over alternatives such as ha_update_entity, ha_trigger_automation, or ha_fire_event. Usage is implied by the example rather than explicitly scoped.

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

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

Annotations cover the safety profile (readOnly, openWorld), so the bar is lower, and the description still adds substantial detail: base64 RGB encoding, 3 bytes per pixel, row-by-row layout, and the credential requirement. It omits error/rate-limit behavior, which keeps it from a 5.

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

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

Purpose is front-loaded and every sentence carries information (format, target consumer, alternative, auth). The nested parentheticals (base64, 3 a pixel, two pixels a character cell) make it dense but not wasteful.

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

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

With no output schema, the description carries the burden of explaining the return value, and it does so thoroughly (base64 RGB bytes, 3 per pixel, row-major). Combined with the auth note and sibling routing, an agent has what it needs to call it correctly.

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

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

Schema description coverage is 100%, and the schema already documents width, height, entity_id, and instance_id. The description adds the notion of downscaling to at most width x height but no per-parameter semantics beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: it fetches a camera's current still, decodes it, and shrinks it to at most width x height pixels. It also names the sibling ha_camera_image as the tool for looking at a camera yourself, so an agent can distinguish it without opening either schema.

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

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

Explicitly scopes usage to clients that draw pictures in text (terminal dashboard panes, two pixels per cell with half blocks) and routes the user to ha_camera_image for direct viewing. It also states the VomeHome auth prerequisite (Cameras ticked under Sensitive devices).

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

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

Annotations cover the read-only/open-world profile, and the description adds real behavioral detail: the still is scaled to 'width' pixels (default 1024), the snapshot-file semantics, and an auth prerequisite ('the API key needs Cameras ticked under Sensitive devices'). It does not cover latency or rate limits, but for a read tool this is solid added context.

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

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

Three tight sentences, front-loaded with what the tool returns; the scale info and the VomeHome API-key prerequisite each earn their place. Slightly dense but no filler.

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

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

There is no output schema, so the description correctly explains the return is an image, plus scaling and auth prerequisites. Complete enough to invoke correctly, with only minor gaps around failure modes.

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

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

Schema description coverage is 100%, so entity_id, width (with min/max/default), and instance_id are already fully documented. The description restates the width default and instance-scoping behavior but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: 'Return a camera's current still as an image you can see,' and clarifies the snapshot-file semantics. It does not name its nearest sibling (ha_camera_frame) to disambiguate, so it falls just short of a 5.

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

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

Gives clear use context — 'to check framing, exposure, or what the camera shows' — which tells the agent when this is the right tool. It offers no explicit exclusions or alternative (e.g. why ha_camera_frame instead), so it is short of 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the write semantics are covered. The description adds real context beyond that: the ha:config permission requirement and the owner-account precondition, both of which affect whether a call succeeds. It does not mention whether existing sessions/tokens are invalidated by the reset.

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

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

Three short sentences, front-loaded with the core action and its main precondition. The clause 'which is how it always authenticates' is slightly redundant and weakens the owner-account constraint, but overall the text earns its space.

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

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

For a destructive, no-output-schema mutation, the description covers the key prerequisites (existing local login, owner-account auth, ha:config permission). The main gap is the post-call effect on the user's existing sessions or credentials, which an agent might want to know before invoking it.

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 all three parameters carry their own descriptions (including the instance_id refusal behavior), so the schema does the heavy lifting. The description adds only the constraint that user_id must reference a user with an existing local login, not new syntax or format detail. 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?

The description states a specific verb and resource ('Reset the password for a user') and explicitly scopes it to users that already have a local login, naming ha_set_user_credentials as the sibling that creates such logins. An agent can distinguish this from ha_create_user, ha_update_user, and ha_set_user_credentials without opening any schema.

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

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

It gives clear preconditions: the user must already have a local login, and the broker must be acting as the owner account. It also states the required permission (ha:config). It stops short of explicitly saying 'use ha_set_user_credentials first if the user has no local login', so the routing is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description still adds value beyond that by disclosing the return shape ('valid' or the specific errors) and positioning it as a pre-reload gate, though it says nothing about permissions, timeouts, or validation cost.

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

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

Three tight sentences, front-loaded with the core purpose, followed by return format and workflow timing. No filler, and each sentence carries distinct information.

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

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

For a zero-required-parameter, read-only validation tool with no output schema, the description covers purpose, timing, and return values, and the lone parameter is fully specified in the schema. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single optional instance_id is fully documented in the schema, including the refusal-on-mismatch behavior. The description adds no parameter detail, so the baseline 3 is appropriate.

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

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

States a specific verb (validate) and resource (the current Home Assistant configuration), anchored to a known equivalent (Developer Tools -> Check configuration). The 'Home Assistant' scoping cleanly separates it from siblings like esphome_validate and ha_get_config, which reads rather than validates.

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

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

Gives an explicit workflow cue: run after editing YAML and before reloading. That is clear when-to-use guidance, but it names no alternatives or when-not conditions (e.g., versus esphome_validate for ESPHome configs), so it stops short of a full 5.

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

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

Annotations already declare destructiveHint=true, but the description goes further by scoping the destruction ('structured error store', explicitly NOT home-assistant.log on disk) and stating a prerequisite ('Requires HA_ALLOW_WRITE=true in direct mode'). This is meaningful added context beyond the annotations.

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

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

Three tight sentences, front-loaded with the action and then the rationale; every sentence carries distinct information (what it empties, why, what it does not touch, and the required flag).

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

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

For a destructive no-arg mutation with no output schema, the description covers scope of effect, prerequisites, the companion read tool, and the non-effect on disk logs. Nothing an agent needs to invoke it safely is missing.

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

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

Schema description coverage is 100% and the single optional instance_id parameter is fully documented in the schema, including the refusal behavior on home mismatch. The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific verb+resource ('Empty Home Assistant's structured error store') and immediately distinguishes itself from its sibling by naming ha_get_system_log and the relationship between them. An agent can tell it apart from ha_get_error_log/ha_get_supervisor_log without opening any schema.

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

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

Explicitly describes the intended workflow ('clear, reproduce the problem, then ha_get_system_log shows only what your reproduction caused'), which is exactly the when-to-use condition. It also names the alternative tool and clarifies the boundary (does not touch the on-disk log).

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

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

With annotations already declaring destructiveHint=true, the description goes further and explains *why* it is destructive: submitting a form sets every field it contains, so omitting a field does not preserve it. That is exactly the behavior an agent must know before invoking, and it exceeds what the annotations convey.

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

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

Front-loaded with the core action, then the read-vs-write pattern, then the destructive caveat. Slightly padded by the ESPHome backstory ('buried several clicks deep in the UI'), but every sentence is relevant and none is filler.

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

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

Complete for a 4-param, no-output-schema tool: it covers the read/write modes, the entry_id source, the destructive submit semantics, and a concrete use case. The remaining parameter (instance_id) is fully documented in the schema, so no gap remains.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds interpretation beyond the schema: entry_id alone means 'read the form', user_input means 'submit answers', and it names real fields (allow_service_calls, subscribe_logs). This gives practical meaning to how the parameters combine.

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

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

States a precise verb+resource+scope: 'Open a config entry's *options* flow — the per-integration settings panel — and optionally submit answers to it.' It also clarifies the two-phase nature (call with entry_id to read, again with user_input to write), distinguishing it from the sibling ha_config_flow which handles initial setup.

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

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

Explicit when-to-use with a concrete motivating case (ESPHome's allow_service_calls switch that is unreachable elsewhere) and a pointer to ha_list_config_entries for obtaining entry_id. It also gives a crucial operational instruction: read the form first and resubmit with only intended changes, since omission is not equivalent to leaving a field alone.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the write profile is covered; the description adds genuinely new context by naming the required authorization ('ha:config (brokered) or HA_ALLOW_CONFIG_WRITE'). It stops short of explaining the consequence of the destructive hint (e.g., that a completed flow creates a persistent config entry) or what happens to an abandoned flow.

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

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

Three tight sentences with no filler, and the core purpose plus the start/continue split are front-loaded before the authorization note. Every clause carries information.

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

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

For a 5-parameter, 0-required, nested-object tool with no output schema, the description covers the two invocation modes and the auth requirement well. The gap is the flow lifecycle: it doesn't say what a completed flow yields (e.g., a new config entry) or that multi-step flows must be driven iteratively, which an agent needs to know for a config-flow API.

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 80%, so the baseline is 3, but the description adds cross-parameter semantics the schema cannot express: handler selects 'start' mode while flow_id + user_input select 'continue' mode, and user_input doubles as defaults on start. That mode-dependency is real added meaning beyond the per-field schema descriptions.

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

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

States a specific verb+resource ('Add or configure an integration via Home Assistant's config flow API') and immediately splits the operation into its two distinct modes (start vs. continue), which distinguishes it from siblings like ha_integration_setup_vome, ha_list_discovery_flows, and ha_config_entry_options.

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

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

It gives clear conditional context for the two modes ('Start: pass handler... Continue: pass flow_id + user_input'), which tells the agent how to invoke it, but it names no alternatives or exclusions — it never says when to prefer ha_integration_setup_vome or ha_config_entry_options, nor what happens if a flow is already partially complete.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true. The description adds real context beyond that: the required environment toggles HA_ALLOW_WRITE and HA_ALLOW_CONFIG_WRITE, and the fact that views/cards are not set at creation and must be added via a separate call.

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

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

Three short sentences, front-loaded with the action, then the follow-up step, then the prerequisites. Nothing extraneous; each sentence carries distinct information.

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

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

For a write tool with thin annotations and no output schema, the description covers prerequisites and the post-creation workflow, which is what an agent needs. It omits failure behavior (e.g., duplicate url_path, invalid slug) and whether a value is returned, though the no-output-schema case lowers that burden.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema with examples (mdi icon, url_path slug). The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Register a new storage-mode Lovelace dashboard'), including the storage-mode qualifier that separates it from YAML-mode dashboards. It also names the sibling ha_save_dashboard and clarifies the division of labor, so an agent can tell them apart without opening a schema.

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

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

Explicitly states the follow-up step ('call ha_save_dashboard to set its views/cards'), which routes the agent correctly between creation and configuration. It gives no explicit when-not or alternative-for-creation guidance, but the sequencing context is clear.

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

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

With annotations covering the safety profile, the description still adds substantial context beyond them: the account is a standing entity independent of the creating API key, deleting the token does not remove the user, admin grants owner-equivalent control, and the call requires the ha:config permission. These are real behavioral traits not present in the structured fields.

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

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

The critical fact (no login yet) and the follow-up step are front-loaded, and the persistence warning is bolded for emphasis. Slightly verbose in places ('or they exist but cannot sign in' is an awkward restatement), but nothing is wasted.

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

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

For a creation tool with no output schema, the description covers what is produced (an account with no credentials), how to finish the job, the persistence semantics, and the required permission. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning to 'role' by warning that 'admin' is equivalent to the owner and that the choice should be deliberate. It does not elaborate on name or local_only, but those are already well documented in the schema.

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

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

States a specific verb and resource ('Create a new Home Assistant user') and immediately scopes it: the account has no login yet. It also distinguishes itself from ha_set_user_credentials and ha_delete_user by explaining the two-step credential flow and that the user persists after token deletion.

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 tells the agent to call ha_set_user_credentials afterwards to make the account usable, and gives guidance on choosing 'role'. It lacks an explicit when-not or a comparison against alternatives like ha_provision_service_login, but the sequencing guidance is clear 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 declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful operational context beyond them: the call requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true, otherwise it will be refused. It still omits whether deletion is irreversible or what happens if the id is unknown.

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 short sentences with zero waste; the action and its target are front-loaded ahead of the prerequisite. Nothing is padded or repeated.

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

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

For a single-parameter destructive call with no output schema and full annotation coverage, the description supplies the essential enablement prerequisite. It could add irreversibility/error semantics, but nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%: automation_id and instance_id are both documented in the schema, including instance_id's home-mismatch refusal behavior. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (Delete) and resource (automation) plus the lookup key (unique id), which cleanly separates it from ha_get_automation, ha_set_automation and ha_trigger_automation. It does not name any sibling explicitly, so it falls just short of the 5 bar for sibling differentiation.

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

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

Implies the use case (remove one automation identified by id) and states the enablement prerequisite, but gives no guidance on when to delete versus alternatives such as disabling via ha_set_automation, and no exclusions. Adequate but with a clear 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 flag the write/destructive profile, but the description adds genuinely new context: the deletion is permanent, it requires the ha:config scope, it was previously impossible outside the UI, and the response's require_restart signals whether a restart is needed. These go meaningfully beyond destructiveHint/readOnlyHint/openWorldHint.

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

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

Front-loaded with the core action in the first sentence, followed by the motivating scenario, the prerequisite lookup, and the auth/return notes. Every sentence contributes actionable information with no filler.

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

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

For a destructive tool with full annotations and 100% schema coverage but no output schema, the description covers target acquisition, auth requirements, irreversibility, and the one response field of interest (require_restart). Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by telling the agent where entry_id comes from and how to identify the correct stale entry (match on name/domain/state). The instance_id guard semantics are left to the schema, but the entry_id guidance is a useful addition.

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

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

States a specific verb and resource ('Permanently delete one config entry (integration instance) by id') and distinguishes itself from siblings like ha_remove_entity and ha_delete_automation. The orphaned/duplicate-entry scenario sharpens exactly what is being 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?

Explains clearly when to use it (orphaned or duplicate entries causing a '_2' entity_id suffix) and routes the agent to ha_list_config_entries with matching criteria (name/domain/state). It lacks an explicit 'when not to use' or a named alternative for the entity-vs-config-entry distinction, so it falls just short of the top tier.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, but the description adds important behavioral detail beyond them: deletion is irreversible, certain files and paths are refused, and deleting an included file can break Home Assistant's configuration check. This is exactly the kind of consequence detail an agent needs for a destructive tool.

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

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

The description is front-loaded with the core action and then layered with warnings and constraints, all of which earn their place for a destructive operation. It is slightly verbose and contains an awkward phrase ('Vome component on the home'), but the structure remains readable and purposeful.

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

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

For a destructive file-deletion tool with no output schema, the description covers the operation, restrictions, irreversible nature, permission scope, and pre-deletion checks. Given the annotation and schema richness, nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, and the schema already explains both 'path' and 'instance_id' clearly, including relative-path formatting and instance mismatch behavior. The description adds some path-scope context by naming refused files and directories, but it does not add parameter-specific semantics beyond the schema baseline.

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

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

The description uses a precise verb and resource: 'Delete one file under the config directory.' It immediately scopes the operation to a single file ('never a directory') and distinguishes deletion from directory removal. This is clear enough for an agent to select it over file read/write/edit/list siblings.

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

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

It gives concrete when-to-use examples ('a throwaway test file, a superseded package') and clear preconditions: read first if contents matter, ask the owner before deleting someone else's file, and remove !includes references before deletion. It also states required scope and protected path exclusions, leaving little to inference.

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

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

Annotations already flag destructiveHint=true/openWorldHint=true, so the safety profile is covered. The description adds non-obvious context the annotations cannot express: two environment gates that must be enabled and the storage-mode-only constraint. It does not say whether deletion is reversible or cascades.

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 sentences, no filler: the action and constraint come first, then the environment prerequisites. Nothing redundant or hedged.

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

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

Given a simple two-parameter destructive tool with no output schema, the description covers scope, id source, and required flags. Minor gaps remain around irreversible side effects (e.g., whether views/cards or referencing automations are affected), but nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents both parameters, including 'not url_path' and the instance_id refusal behavior. The description largely echoes the schema's id wording, so the baseline 3 applies with little added detail.

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

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

States a precise verb+resource ('Delete a storage-mode Lovelace dashboard') and even narrows the scope to storage-mode dashboards, which distinguishes it from the YAML-mode path and from sibling deleters like ha_delete_automation or ha_delete_helper. 'by its id' clarifies the keying.

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

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

Gives the precondition set (HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true) and names where the id comes from (ha_list_dashboards or ha_create_dashboard), which routes the agent usefully. It stops short of explicit when-not guidance or naming an alternative deletion path.

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

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

Far exceeds the destructiveHint annotation by disclosing the immediate effect on referencing entities, the shared-id registry collision that can destroy a YAML-defined helper, that a reload will not restore it and only a full restart will, and the built-in refusal plus the confirm_shared_id override. This is exactly the non-obvious failure mode an agent needs before calling.

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

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

Front-loads the core action and immediate consequence in the first sentence, then escalates to the shared-id hazard and the refusal/override behaviour. Long but every sentence carries distinct, decision-relevant information.

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

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

No output schema exists, but none is needed for a delete tool. The description covers the mutation effect, the destructive edge case, the guard and its override, and the alternative path for YAML-only helpers, leaving nothing an agent needs to call it safely.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by explaining the reasoning behind confirm_shared_id (overriding the shared-id refusal and the restart consequence) and the origin of helper_id, which materially deepens the schema's text. instance_id's cross-instance guard is left to the schema, so not a full 5.

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

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

Specific verb (Delete) plus specific resource (a stored Home Assistant helper by id), with the id's provenance named as ha_list_helpers. It is clearly separable from siblings like ha_set_helper, ha_list_helpers and 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?

States when to use it (stored helper id from ha_list_helpers) and explicitly when it cannot be used (an id not in ha_list_helpers, i.e. a configuration.yaml-only helper, which must be removed by editing the file and restarting). It also directs the caller to check referencing automations/dashboards/template sensors first.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, yet the description goes further and discloses the downstream consequence (dependent automations will fail at that step) plus the two environment flags required for the call to succeed. That is exactly the kind of context annotations cannot carry.

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

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

Three short sentences, zero filler, with the action first, the hazard second, and the prerequisites last. Every sentence earns its place.

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

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

For a destructive mutation with full annotations, complete schema coverage, and no output schema, the description supplies the two things that matter: the blast radius on dependent automations and the required write flags. Nothing an agent needs before calling it is missing.

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

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

Schema description coverage is 100%, including a detailed script_id description and the optional instance_id scoping semantics, so the schema does the heavy lifting. The description adds only 'by id' and nothing about the instance_id guard, meriting the baseline 3.

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

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

States a specific verb and resource ('Delete a script by id'), which cleanly separates it from siblings like ha_delete_automation and ha_delete_dashboard. It does not explicitly name a sibling or call out what it is not, so it falls just short of the top score.

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

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

Gives concrete preconditions ('Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true') and a when-not-to-call-this-yet warning ('remove those calls first'). It stops short of pointing to an alternative tool for fixing the dependent automations, so it is clear context rather than full routing guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds the details that matter: deletion is permanent, it cascades to attached login credentials, it is gated on the ha:config permission, and it will refuse specific protected accounts. This is behavioral context beyond what the structured fields provide.

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

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

Three short sentences, front-loaded with the destructive action, then constraints, then the permission requirement. No filler and nothing an agent needs is buried.

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

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

For a destructive, annotated, no-output-schema mutation tool, the description covers permanence, cascade effects, permission gate, and refusal cases. Return values need not be described since no output schema exists, and safety is already carried by 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 description coverage is 100% and both parameters (user_id, instance_id) are fully documented in the schema itself, including the cross-tool reference to ha_list_users. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete a user') plus the cascade scope ('any login credentials attached to it'), which cleanly separates it from siblings like ha_remove_user_credentials (credentials only) and ha_update_user (mutation without deletion). An agent can select it without opening any schema.

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

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

Gives explicit when-not conditions (cannot delete the currently in-use owner account or a system-generated user) and the prerequisite 'Requires ha:config'. It stops short of naming the closest alternative (ha_remove_user_credentials) for the case where only credentials should be removed, so it is strong but not fully routing.

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

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

Goes well beyond the destructiveHint=true / openWorldHint=true annotations: it discloses atomicity ('Nothing is written unless every edit applies'), automatic post-edit verification with restore-on-failure, the exact-match-once constraint, ordering semantics, and the required ha:files scope. These are the operationally decisive facts an agent needs before mutating a config file.

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

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

Front-loaded with the core mechanic, then the sibling comparison, then atomicity, then verification, then scope — a logical order with no filler. It runs slightly long, and the 70 KB example is a flourish, but every sentence carries real information.

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

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

For a destructive, no-output-schema mutation tool, the description covers safety profile, atomicity, verification/rollback, scope requirements, and the alternative — nearly everything an agent needs. Minor gaps remain (e.g. behavior when an old_text fails to match uniquely or what the response/error looks like), but the essentials are present.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description reinforces edit semantics ('replaces one exact piece of text with another, and must match exactly once') but largely restates what the schema's old_text/new_text descriptions already say, adding little parameter-level detail beyond the schema.

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

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

States a specific verb and resource ('change part of a text file under the config directory') and immediately narrows scope to surgical, single-occurrence text replacement. It explicitly distinguishes itself from the closest sibling ha_write_config_file, so an agent can tell them apart without opening either schema.

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

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

Explicitly routes: 'Prefer this to ha_write_config_file for any change to an existing file', and gives the condition (editing an existing file) plus the reason (resending a 70 KB file is slow and error-prone). This is when-to-use guidance with a named alternative, not just an implied context.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the write/open-world nature is known. The description adds a useful precondition ('Requires writes to be enabled') and an audience hint ('advanced'), but says nothing about effect on state, idempotency, or failure modes.

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

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

Three short sentences, front-loaded with the action, then the use case. No padding; only mild redundancy between the title and the first clause.

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

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

For a mutation tool with no output schema but with annotations, the definition covers what it does and its prerequisite, but omits return/failure behavior and any routing guidance against the many other triggering siblings. Adequate but with clear 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 description coverage is 100% and all three parameters (event_type, event_data, instance_id) are documented in the schema. The description adds no format, syntax, or payload guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: fire a custom event on the Home Assistant event bus, and flags it as advanced. It does not name a sibling alternative (e.g. ha_trigger_automation or ha_call_service), so the agent still has to infer how it differs from other triggering tools.

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

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

Gives an implied use case (triggering event-based automations during testing) but no explicit when-not-to-use or named alternative. The condition selecting this over ha_trigger_automation is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds value by disclosing the returned shape (triggers, conditions, actions), which partially compensates for the absent output schema, but says nothing about error behavior or whether the returned config is editable.

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 tight sentences with the purpose and return shape front-loaded and no filler. The second sentence is somewhat redundant with the schema's automation description, a minor waste.

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

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

For a read-only getter with annotations covering safety and full schema coverage, the description is nearly sufficient, and naming the returned components partly substitutes for a missing output schema. It could still say more about the config's editability or failure modes.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the instance_id refusal semantics. The description merely restates the automation parameter's accepted forms (entity_id or unique id) with no added syntax or format detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Get the full configuration ... of an automation') and enumerates the returned components (triggers, conditions, actions), which separates it from a bare list tool. It does not explicitly name the sibling it is not, e.g. ha_list_automations or ha_get_config, so an agent must infer the distinction.

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 no when-to-use or when-not guidance and never mentions alternatives such as ha_list_automations (for enumerating) or ha_set_automation (for mutation). The intended usage is only weakly implied by the purpose statement.

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 openWorldHint=true, so safety and world-scope are covered. The description adds the return content and implies cheap orientation, but says nothing about auth requirements, cost, or caching; the instance-targeting refusal rule lives in the schema, not the description. Adequate, but not rich additional context.

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

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

Two tight sentences with the returned fields front-loaded and the orientation hint second. No filler or restatement of the tool name.

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

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

With no output schema, the description carries the burden of describing the return payload and does so by enumerating the key fields. For a zero-required-param read tool this is close to complete; only a note on response shape (flat object vs nested) is missing.

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

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

Schema description coverage is 100% and the single optional instance_id is thoroughly documented in the schema, including the refusal behavior when targeting a different home. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb ('Return') and resource ('core Home Assistant configuration') and enumerates exactly what is included: version, location name, time zone, unit system, loaded integrations/components. This cleanly separates it from siblings such as ha_get_system_log or ha_list_config_entries, which return different artifacts.

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?

'A good first call to understand the instance' gives an explicit usage context, which is real guidance for an agent orienting itself. It does not name an alternative or state when-not to use it, so it falls short of the 5-level routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the payload is the full configuration including views and cards, which hints at response size, but says nothing about auth, rate limits, or failure modes; the instance-mismatch refusal behavior lives in the schema, not the description.

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 tight sentences: the purpose first, then the argument-sourcing guidance. No filler or repetition of the title.

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

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

For a read-only two-parameter tool with full schema coverage and no output schema, the description conveys what is returned and where the input comes from. Only minor gaps remain around how large/structured the returned config is.

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

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

Schema description coverage is 100%, so both parameters are already documented, including that 'lovelace'/omission means the default overview. The description's 'sam-energy' example adds a small amount of value about custom paths but does not go beyond the schema baseline.

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

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

States a specific verb and resource ('Get the full Lovelace configuration for one dashboard') and scopes the return ('views, cards, etc.'), which cleanly separates it from ha_list_dashboards, ha_save_dashboard, ha_create_dashboard and ha_delete_dashboard.

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

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

Explicitly routes the agent to ha_list_dashboards as the source of the url_path argument and explains what a path looks like. It does not state exclusions (e.g. what to do if you only want a summary), but the invocation context is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the output includes disabled/hidden flags, but says nothing about auth requirements, rate limits, or how the multi-home instance_id refusal behaves (that detail lives only in the schema).

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

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

Two sentences, zero filler, and the core capability is front-loaded before the use-case sentence. Nothing is repeated from the title or schema.

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

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

For a read-only inspection tool with full parameter coverage and no output schema, the description covers what is returned well enough to call it correctly. It could state the response shape (a list of registry entries) or filtering interactions, but nothing essential is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the instance_id refusal semantics and the include_disabled default. The description adds no syntax, format, or interaction detail beyond the schema, so baseline 3 applies.

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

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

The description names a specific verb ('Inspect') and resource ('entity registry') and enumerates the metadata returned (platform, area, device, unique-id, disabled/hidden). It is clearly distinct from ha_get_state (state vs. registry metadata), though it never names a sibling tool to route against.

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?

'Useful for finding disabled entities or the area/device an entity belongs to' gives a concrete use context, but there is no explicit when-to-use vs. when-not guidance and no mention of alternatives like ha_list_entities or ha_get_state, which an agent selecting between registry and state lookups would need.

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 openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: this is the raw, ungrouped log and the structured store may drop lines, which explains why the two tools can disagree. It doesn't mention the default tail size or the foreign-instance refusal, but those live in the schema.

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

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

Two sentences with no filler, and the primary routing decision is front-loaded immediately after the one-line purpose statement.

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

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

For a two-parameter read-only log tool with full schema coverage and no output schema, the description supplies enough to call it correctly and to pick it over the structured-log sibling. Only the return shape/pagination is unaddressed, which is minor here.

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

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

Schema description coverage is 100% for both parameters, including the default of 200 lines and the instance_id refusal semantics, so the schema carries the load. The description adds no parameter-level detail beyond what is 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?

States a specific verb and resource ('Return the tail of the raw Home Assistant error log') and contrasts it with the sibling ha_get_system_log, so an agent can distinguish the two logs without opening either schema.

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

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

Explicit routing guidance: ha_get_system_log is named as the usual better first stop, and the exact conditions for choosing this tool instead (raw ordering, lines the structured store drops) are spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds non-obvious behavior beyond that: the default time window and the fact that this tool overrides Home Assistant's native 24-hour cutoff. It does not discuss result size or rate characteristics, which keeps it below a 5.

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

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

Three dense sentences, front-loaded with the core purpose followed by time-window semantics. The parenthetical about Home Assistant's native cutoff earns its place, though the phrasing is slightly wordy.

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

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

For a read-only query tool with a fully documented 6-parameter schema and no output schema, the description covers the critical ambiguity (default time ranges) that would otherwise cause wrong calls. It could hint at the returned shape (per-entity series) since no output schema exists, but overall it is sufficient.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds meaning the schema does not: the default/fallback behavior of start_time and end_time and the ISO 8601 format expectation. It still doesn't clarify minimal or max_points trade-offs, which are covered only in the schema.

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

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

States a specific verb+resource ("Get historical state changes") plus scope ("one or more entities over a time window"), which cleanly separates it from sibling readers like ha_get_state (current state) and ha_get_logbook. An agent can route to it without opening the schema.

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

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

Gives clear operational context: default window is the last day, and a start_time without end_time runs to now (with the note that Home Assistant alone would stop after 24h). It does not name alternatives (e.g. ha_get_logbook for event-style history), so it stops short of explicit when/when-not routing.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true). The description adds a genuinely non-obvious behavioral fact: with start_time and no end_time it runs to now, whereas Home Assistant alone would cap at 24 hours. That is useful context beyond the structured fields, though no return-shape or pagination behavior is described.

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

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

Two sentences, both earning their place: the first defines the resource and filtering, the second covers timestamp format and the end_time default caveat. Front-loaded with the purpose and no filler.

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

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

With no output schema, the description wisely characterizes the return content (human-readable 'what happened and when'), and the annotations carry the safety profile. It omits any mention of the instance_id refusal behavior that the schema documents, but that gap is minor given full schema coverage.

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 documents all four parameters. The description still adds value by stating the timestamp format (ISO 8601) and the end_time default semantics, i.e. behavior the schema's terse per-property descriptions do not convey.

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

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

States a specific verb and resource — 'Return human-readable logbook entries (what happened and when)' — with the filter scope made explicit. It separates itself conceptually from sibling log tools (ha_get_history, ha_get_system_log, ha_get_error_log), but never names them, so differentiation is inferred rather than stated.

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

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

Usage is implied by the resource ('logbook entries'), and the optional entity/time filtering hints at typical calls, but there is no explicit when-to-use, when-not-to-use, or routing to the many sibling log/history tools. An agent must infer the choice from the name alone.

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 openWorldHint=true, so the safety profile is covered structurally. The description adds the shape of the returned configuration, which is genuinely useful, but says nothing about auth needs, failure modes, or behavior for unknown script ids beyond what the schema's instance_id text already conveys.

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

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

Two tight sentences with the core purpose front-loaded and the disambiguation trailing. Every clause earns its place; no filler.

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

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

With no output schema, the description correctly carries the burden of describing the return shape (alias, sequence, fields, mode), which is adequate for a read-only getter. The field list is slightly coarse but sufficient for an agent to decide to call it.

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

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

Schema description coverage is 100% and both parameters are fully documented in the schema, including the 'script.raise_heat' id form and the instance_id refusal semantics. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get a script's full configuration') and enumerates what the config contains (alias, sequence, fields, mode), so an agent knows exactly what comes back. It also differentiates itself from the listing path by naming ha_list_entities as the sibling to use for enumeration.

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

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

It explicitly routes the enumeration case to ha_list_entities domain='script', giving one clear when-to-use alternative with a condition. It does not address the get-vs-other-getters case (e.g. ha_get_automation, ha_get_config), so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds that it returns full state plus attributes, but says nothing about behavior for unknown entities, unavailable states, or cross-instance refusal (that detail lives only in the instance_id schema field).

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

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

Two tight sentences with no filler; the core action leads and the usage cue follows immediately. Every clause 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?

With no output schema, the description should carry more of the return-shape burden; it only gestures at 'full state and attributes' without indicating the state/attributes structure an agent must parse. Adequate for selection, thin for consumption.

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%: entity_ids format and examples plus the instance_id refusal semantics are fully documented in the schema. The description adds only the 'one or more' cardinality, so 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?

Names a specific verb (get) and resource (entity state/attributes) and adds a scope qualifier ('one or more entities'), which distinguishes it from the list-style sibling ha_list_entities and the time-series ha_get_history. It does not explicitly name a sibling, but the purpose is unmistakable.

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

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

Gives a clear usage context: read exact current values before mutating them or writing template/automation logic. That is real when-to-use guidance, though it names no alternative tool to use instead (e.g., ha_list_entities for bulk browsing).

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 openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: a Supervised/HAOS prerequisite and the fact that it works through the VomeHome broker with read scope.

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 dense sentences, front-loaded with the action and resource list, with the differentiator and the constraint following. No filler and nothing that could be cut without losing meaning.

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

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

With no output schema, the description could say more about what the tail output looks like (format, truncation, whether it streams), but it does cover scope, prerequisites and the broker path. Adequate for a read-only log accessor.

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 target, addon_slug, tail_lines and instance_id are all already documented, including the enum values and defaults. The description adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a concrete verb (tail) and enumerates the exact resources (add-on, HA Core, Supervisor, host), and explicitly distinguishes itself from HA's own error log. An agent can tell it apart from ha_get_error_log / ha_get_system_log without opening any schema.

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

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

Gives a clear when-to-use trigger: problems that never reach HA's error log, with concrete symptoms (crash-looping add-on, failed install, host-level trouble). It does not name the sibling log tools as explicit alternatives, so it stops short of a full routing rule.

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

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

Annotations already cover the read-only safety profile, but the description adds real behavioral detail: deduplication semantics, that tracebacks are omitted by default yet the final exception line is retained, and that include_exception returns full stacks. That default-vs-opt-in behavior is not derivable from annotations or schema.

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

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

Four dense sentences, front-loaded with what the tool returns and its differentiator before the filtering and traceback guidance. No filler; every clause carries information.

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

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

With no output schema, the description compensates by enumerating the record shape (level, logger, source file:line, occurrence count, first/last seen). Annotations handle safety, so an agent has everything needed to call it and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine interaction tip not in the schema: pairing include_exception=true with 'contains' to narrow a stack read. It also summarizes the filter axes (min level, logger, free text), which reinforces rather than merely repeats the schema.

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

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

States a specific verb and resource ('get system log') and characterizes the resource precisely as a 'deduplicated error store: one record per distinct problem' with the fields returned. It explicitly distinguishes itself from the sibling ha_get_error_log, so an agent can route correctly without opening either schema.

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

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

Gives an explicit preference rule ('Prefer this over ha_get_error_log — 20 grouped issues instead of 200 raw lines') and conditions for the include_exception toggle ('usually narrowed with contains'). When-to-use and the alternative are both named.

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

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

Annotations already establish read-only/open-world. The description adds real behavioral context beyond them: output is summarised by default, full=true returns the raw trace including config and is 'large', and it explains that logs stay silent about false conditions. It doesn't cover pagination or error behavior, but that is minor against the 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?

Front-loads the return-shape summary, then the use case, then the argument rules. Roughly four dense sentences with no filler, though it is on the longer side for a single-get tool and could trim the 'why didn't my automation run' aside slightly.

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

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

With no output schema, the description carries the burden of describing returns and does so well: trigger, ordered conditions/actions, results, and failed_at. The summarised-vs-full distinction is covered. It stops short of describing the shape of the summarised payload or error cases, leaving a small gap.

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

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

Schema coverage is 100% (baseline 3), but the description goes further by explaining the interaction semantics: give item and omit run_id for the latest run, or give run_id and item becomes optional because the run's own item is looked up. That relational behavior is not spelled out in the schema and adds genuine value.

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

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

States a specific verb and resource ('Get', trace) and enumerates what one run's output contains: trigger, ordered conditions/actions with results, and 'failed_at'. It distinguishes itself from the sibling ha_list_traces by being the drill-down for a single run while that tool enumerates runs.

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

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

Explicitly routes the agent: 'This is the tool for why didn't my automation run', and names ha_list_traces as the source of run_id. It gives concrete when-to-use rules for the item vs run_id combination, so there is no ambiguity about which argument to supply in which situation.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), and the description adds traits annotations cannot express: the ha:config authorization requirement, the scope of the mutation ('only registers it'), and the critical quirk that HACS reports false success so the tool self-verifies by re-listing repositories.

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 tight paragraphs: the first covers action, inputs, and the prerequisite follow-up; the second covers the silent-failure verification. Front-loaded and largely waste-free, though the parenthetical category list duplicates the schema's enumeration.

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

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

With no output schema, the description compensates by explaining the observable outcome and the confirmation mechanism, plus prerequisites and the required follow-up call. An agent has everything needed to invoke it correctly and interpret the result.

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 repository, category, and instance_id semantics in detail. The description's category examples and 'owner/repo' format restate schema content rather than extending it, so the baseline of 3 applies.

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

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

The description gives a specific verb+resource ('Add a custom repository to HACS'), states the identifier format ('owner/repo' or URL) and the category taxonomy, and explicitly distinguishes itself from the sibling ha_hacs_download_repository by clarifying it only registers rather than installs.

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

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

It states the exact follow-up needed ('call ha_hacs_download_repository afterwards to actually install it') and the condition that selects this tool (a fork, private project, or repo not in the default store). The auth prerequisite 'Requires ha:config' further scopes when the call will succeed.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds real value on top: it discloses that files are written to the config directory, that HACS entities get reloaded for brand-new integrations, and that a restart is conditionally needed. It does not say what an update overwrites or whether a failure leaves partial files, which is the main remaining gap for a destructive write.

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

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

Three dense sentences with the core action front-loaded, followed by accepted inputs, then prerequisites. Every sentence carries information, though the restart caveat and auth requirement could be trimmed slightly for a tighter read.

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

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

No output schema exists, and the description covers the essentials an agent needs: write semantics, auth scope, accepted identifier forms, and post-install behavior. It stops short of describing the return payload or what happens on a failed download, which keeps it from a 5.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds provenance the schema lacks: it says where the repository id comes from (ha_hacs_list_repositories or ha_hacs_add_repository) and confirms the 'owner/repo' alternative. It does not elaborate on version or instance_id beyond the schema text.

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

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

States a specific verb+resource ('Install or update a repository HACS already knows about') and immediately scopes it against siblings by naming the registration step (ha_hacs_add_repository) as the prior step. The phrase 'the step that actually writes its files into the config directory' tells the agent exactly what distinguishes this tool from the other ha_hacs_* tools.

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

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

Explicitly names the two sources for the repository id (ha_hacs_list_repositories or ha_hacs_add_repository), the implicit precondition that HACS must already know the repository, and the post-install requirement (restart for integrations/add-ons, not for plugin/theme/dashboard resources). It also states the required auth scope (ha:config).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description still adds real behavioral context beyond them: it discloses the error behavior when HACS is absent and mentions pending background tasks as part of the returned state.

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 tight sentences with the returned fields front-loaded and the failure mode last. No filler, nothing redundant.

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

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

No output schema exists, so the description carries the burden of describing the return value, which it does concisely. Missing only a pointer to related HACS tools for workflow context.

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

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

Only one optional parameter and schema description coverage is 100%; its description is quite detailed, including the refusal behavior for a mismatched session. The tool description adds nothing about instance_id, so the baseline 3 for high schema coverage applies.

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

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

States the specific resource (HACS) and exactly what the call reports: install status, version, configured country, and pending background tasks. This distinguishes it from the sibling HACS tools, which all act on repositories (list/add/download/remove) rather than reporting installation state.

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?