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

Annotations cover the safety profile (not read-only, non-destructive, non-idempotent), so the bar is lower, and the description adds genuinely new behavior: 'Staged only' signals changes are not live and require apply_changes, plus the execution semantics of Multi (ordered) vs Toggle (cycled). It stops short of stating the undo/discard counterpart.

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 does and followed by the prerequisite and staging note. 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?

An output schema exists so return values need no explanation, and the description covers purpose, prerequisite, and staging for a 10-parameter mutation tool. Coverage is strong, though deeper notes on how staged changes are later applied would round it 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 80%, so the schema already documents slot, action, device, delay_ms, and position richly, making 3 the baseline. The description adds behavioral meaning to delay_ms via the ordered/cycled distinction but gives no syntax detail beyond what the schema already states.

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 (add) plus resource (an action/child) plus the two container types it targets (Multi Action, Toggle Action), with a clear description of how each container behaves. An agent can distinguish this from siblings like set_key or remove_child 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?

Provides an explicit prerequisite ('Put the Multi/Toggle Action on the key with set_key first') and the staging constraint ('Staged only'). It does not explicitly name when to prefer this over close siblings like remove_child or set_multi_delays, but the 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?

Goes well beyond the annotations (destructive/non-idempotent/non-read-only) by disclosing the concrete side effects: OpenDeck is stopped, a backup is made, all staged changes are written, verified, then the app restarts. An agent understands exactly what state will be mutated and that a restore path exists.

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 identifying claim and the full effect sequence front-loaded, followed by the safety-critical call pattern. No filler.

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

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

An output schema exists so return values need not be described, and the annotations plus prose cover the safety profile and workflow. The remaining gap is behavioral meaning for on_conflict and allow_untested_version, which an agent would have to infer.

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 50%; confirm and show_window already have descriptions, and the prose reinforces confirm=false as the dry-run. However on_conflict (abort/skip) and allow_untested_version are undocumented in both schema and description, so the description does not compensate for the coverage gap.

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 operation ('changes OpenDeck') and enumerates the exact workflow: stops, backs up, writes staged changes, verifies, restarts. 'The only tool that changes OpenDeck' directly differentiates it from siblings like preview_changes, discard_changes and stage_plugin.

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 two-step usage pattern ('call with confirm=false first and show the user the result'), which is clear precondition guidance. It does not explicitly name sibling alternatives (e.g. preview_changes), but the 'only tool that changes' framing and the dry-run-then-apply flow cover the practical decision well.

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 (destructiveHint=false, readOnlyHint=false, idempotentHint=false). 'Staged only' adds genuinely useful context beyond those flags — the removal is not applied until a later apply step — but it does not say what happens to an already-staged change or what the response reports.

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, front-loaded with the action and immediately followed by the key behavioral constraint. 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?

An output schema and full-annotations set mean the description does not need to explain return values, and it is adequate for a 3-param tool. The one gap is the staging workflow dependency, which is stated but not explained (which tool applies 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%, so slot/device/profile are fully documented in the schema. The description's 'key or dial' phrase loosely reinforces the slot vocabulary but adds no format or defaulting information beyond it; 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: removing an action from a key or dial. Relative to siblings like set_key and update_key, it is understandable that this clears rather than writes an action, but the description never explicitly contrasts itself with those siblings, so it falls 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?

'Staged only' hints at a workflow but does not say when to use this over set_key/update_key, nor does it name apply_changes or discard_changes as the follow-up. No explicit when/when-not guidance is given.

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, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description adds genuine value beyond them: it discloses data provenance (curated schema vs. plugin-page hints vs. real settings from existing keys) and that secrets are redacted. It could go further on behavior for unknown/unsupported actions, but the data-source and redaction disclosure is substantive.

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 sentence, front-loaded with the verb and resource, with the colon-separated apposition carrying the fallback logic. Dense but not padded; the nested comparative clause ('a curated schema ... otherwise hints ... plus real settings') is slightly hard to parse on first 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?

For a one-parameter, read-only tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what is explained, when, and where the returned data comes from, including the redaction guarantee.

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 the single 'action' parameter with a UUID/name example, so the baseline of 3 applies. The description says 'one action' but adds no format, naming, or disambiguation detail beyond what the schema already provides.

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

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

States a specific verb ('Explain') and resource ('one action's settings') and pins the timing ('before placing it'). It is distinguishable from list_actions and get_plugin_settings by scoping to a single action's settings, but it never names those siblings, so the differentiation is implicit rather than explicit.

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 phrase 'before placing it' specifies the workflow stage at which this tool is called, which is real context an agent can act on. However, no alternatives are named (e.g., when to prefer list_actions or get_plugin_settings) and there are no exclusions or prerequisites for unknown actions.

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=false and destructiveHint=false, so the agent already knows this writes to staging without touching live state; 'without applying them' reinforces that scope. However, nothing is said about whether discarding is recoverable, whether it can be undone, or what happens to the pending operation records.

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 front-loaded sentence that states action, target, and the key constraint with zero filler. Nothing could be removed without losing 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 one optional parameter fully documented, an output schema present, and annotations covering the safety profile, the remaining burden on the description is small. The only meaningful gap is reversibility/undo guidance for a discard operation.

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 'which' parameter is fully documented, including the 'all'/'last'/op-id forms and a cross-reference to preview_changes. The description adds no parameter meaning 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 gives a specific verb ('drop') and resource ('staged changes') plus a scope qualifier ('without applying them'), which implicitly separates it from apply_changes. It doesn't name siblings, but the contrast with the apply step is inferable.

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?

Use is implied by the staging workflow: reject pending changes rather than commit them. It never states when to prefer this over preview_changes or apply_changes, nor any prerequisites (e.g., that changes must first be staged).

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 open-world scope are covered. The description adds nothing beyond that: no notes on search matching behavior, result ranking, pagination/limit semantics, or that results are names only (not rendered icons).

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 seven-word sentence with zero waste, and the purpose is front-loaded before the consumer reference. It is efficient, though the brevity borders on under-specification rather than pure conciseness.

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

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

An output schema exists, so return values need not be described, and annotations cover safety. Still, for a three-parameter search tool the description omits any guidance on how results should be used (e.g. passing a returned name to make_icon) or how limit/icon_set affect the search, leaving real gaps.

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

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

Schema coverage is 67% – query and icon_set carry good descriptions (including the mdi vs brand semantics), but limit is undocumented, and 'Find icon names' adds no syntax or matching guidance beyond the schema. This is the baseline case where the schema does most of the work.

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 ('Find icon names') and ties it to the sibling tool that consumes the results ('for make_icon'). That pairing separates it from unrelated siblings like find_plugins or ha_search, though it doesn't explain what an icon name is or how results are shaped.

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 phrase 'for make_icon' implies the intended workflow (search here, then call make_icon), which is useful implied usage. However, there is no explicit when-to-use statement, no mention of when not to use it, and no alternative search path 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results carry author, repository, and installed/available versions, which is useful context, but says nothing about pagination, result limits, 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?

A single efficient sentence, front-loaded with the core action. No filler, though it is terse to the point of omitting useful scoping detail.

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

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

An output schema exists, so return values need not be explained, and annotations cover safety. For a 3-param search tool, however, the missing 'limit' documentation and lack of usage guidance leave it only minimally complete.

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

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

Schema coverage is 67%; the 'source' enum has a rich inline description and 'query' has 'Search text.', but 'limit' is undocumented. The description adds nothing about parameters beyond what the schema provides, so it neither compensates for the gap nor earns extra credit.

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 ('Search for plugins') and adds intent ('to install'), clearly distinguishing it from the resource-oriented siblings like find_icons. It does not, however, explicitly contrast itself with other search/discovery tools.

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

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

The phrase 'to install' and the 'source' enum (catalogue/archive/installed) imply the usage context, but there is no explicit when-to-use, when-not, or named alternative. Guidance is inferred rather than stated.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds useful domain context by defining what an 'app rule' actually is (device-to-profile mapping triggered by app focus), but it says nothing about scope, volume of rules returned, or whether inactive/unmatched apps appear.

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 front-loaded sentence that names the outcome first and then clarifies it after the colon. No filler, no repetition of the tool name, nothing that could be cut.

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 zero parameters, a full annotation safety profile, and an output schema that documents the return shape, the description only needed to explain the domain meaning of 'app rules' — which it does. The one missing piece is how this snapshot relates to sibling tools like set_app_rule and get_overview.

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

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

The tool takes zero parameters, so there is no parameter surface for the description to compensate for; the baseline of 4 applies. The description correctly implies the call is unfiltered rather than suggesting any implicit scoping argument.

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 (show) and a concrete resource (automatic profile switching rules mapping apps/devices to profiles). An agent can tell it returns per-device/per-app rule mappings, but the description never contrasts itself with the write counterpart set_app_rule or the broader get_overview, so sibling differentiation is left to inference.

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 when-to-use or when-not-to-use guidance and no alternatives named. Given a sibling set_app_rule exists, plus get_overview/show_profile for inspection, the description should say when this read view is the right one; as written, usage must be inferred from the verb 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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that this aggregates state across devices, profiles, plugins and staged changes (a multi-subsystem read), but the enumerated contents largely restate what the output schema already delivers, so added behavioral value is modest.

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 opens with the imperative usage cue and then enumerates scope compactly. No filler or repetition.

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

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

With zero parameters, an output schema present, and annotations covering the read-only profile, the description supplies everything an agent needs to select and call it: it's the entry point and says what state it reports.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate. Baseline for a zero-parameter tool is 4.

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

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

States a specific verb ('Lists') plus the exact resources covered: devices with grid size, dials, touchpoints and connection state, per-device profiles and the selected one, installed plugins, OpenDeck running state, and staged change count. The opening 'Start here' immediately distinguishes it from narrower siblings like show_profile or list_backups.

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?

'Start here' is explicit entry-point guidance that tells an agent to call this before drilling into siblings. It does not name a when-not case or a specific alternative for follow-up, so it stops short of 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 establish readOnly/non-destructive/non-openWorld, so the safety profile is covered. The description adds genuinely new behavioral context: it returns global (plugin-wide) scope rather than per-device settings, and secret values are redacted so the agent knows not to expect usable secrets.

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 front-loaded sentence with no filler; the scope qualifier and redaction caveat both earn their place.

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

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

With an output schema present, return values needn't be explained, and annotations cover safety. A simple 1-param read tool is adequately covered, though the absence of any when-to-use or prerequisite context leaves 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% with a single documented parameter ('Plugin name or folder id'). The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Show') and resource ('a plugin's global settings') with a scope qualifier ('plugin-wide'). The read framing contrasts implicitly with the sibling set_plugin_settings, but no sibling is named explicitly, so it lands 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?

No statement of when to use this versus set_plugin_settings, nor any prerequisite such as needing the plugin to exist or be staged. Usage is only inferable from the verb itself.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, so the safety profile is known. The description adds real value beyond that: 'Acts on the real home' reinforces the live side effect, and the confirm=false dry-run pattern is essential behavioral guidance not derivable from annotations alone.

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, front-loaded with the action and followed by the safety constraint. The 'e.g. to test what a key will do' clause earns its place as a concrete use case, though it is somewhat narrow.

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

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

An output schema exists so return values need not be explained, and annotations carry the safety profile. Combined with the description's dry-run guidance, an agent has what it needs, though the undocumented entity_id and lack of sibling routing leave minor gaps.

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

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

Schema coverage is 75% (service, data, confirm documented; entity_id bare). The description adds no syntax or format detail beyond what the schema provides, only restating the confirm workflow already 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?

States a specific verb+resource ('Call a Home Assistant service') and gives a concrete example use ('test what a key will do'). It is clearly distinct from read-only siblings like ha_search or ha_describe_entity, though it does not explicitly name those alternatives.

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

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

Provides a clear workflow: call with confirm=false first, get the user's OK, then call for real. This tells the agent when and how to invoke it safely. It lacks explicit when-not conditions or named sibling alternatives, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value by listing the returned content categories, but discloses no auth, rate-limit, or failure behavior beyond that; with annotations doing the safety work, this is adequate.

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 front-loaded sentence with no wasted preamble; the one weakness is the trailing clause about 'ready-made settings for a Home Assistant key,' which is slightly convoluted and could be firmer.

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

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

An output schema exists, so return values need not be spelled out, and annotations cover the read-only nature. The remaining gaps are the undocumented parameter format and the absence of any when-to-use routing against ha_search/ha_call_service, which a 1-param tool of this kind should still provide.

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

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

Schema description coverage is 0% for the single required entity_id, and the description does not compensate – it never states the expected format (e.g. domain.object_id) or how to obtain a valid identifier. The schema therefore leaves the only parameter undefined.

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 enumerates exactly what a caller receives for one entity: state, attributes, area, domain services, and prebuilt settings. That is specific enough to distinguish it from ha_search (discovery) and ha_call_service (mutation), though it never names those siblings explicitly.

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 statement of when to reach for this tool versus ha_search or ha_call_service, and no note that an entity_id is typically obtained from ha_search first. Usage must be inferred entirely from the name.

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 two things beyond the annotations: authentication context ('using the Home Assistant plugin's saved login') and the un-filtered fallback behavior of returning areas and domains rather than entities. It does not discuss pagination or result ordering, but that is minor here.

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, front-loaded with the core verb+resource and no redundant restatement of the name or title. Every clause carries information (returned fields, auth source, fallback behavior).

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

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

An output schema exists, so return-value explanation is unnecessary and correctly absent. What remains is covered: what is searched, the four filter parameters implied, and the no-filter behavior. Only the otherwise-undocumented limit parameter is left unaddressed.

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

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

Schema coverage is 75% (limit has no description), so the schema does most of the work for area, query and domain. The description's mention of 'filters' and the no-filter case hints that the null defaults are pass-through filters, but it adds no syntax, format, or matching-rule 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 ('Find Home Assistant entities') and even enumerates the fields returned (id, name, state, area), so the agent knows this is a discovery/search operation. It does not name the closely related siblings (ha_describe_entity, ha_call_service), so the distinction is inferable but not 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?

The phrase 'to put on keys' implies a use context, and 'With no filters, lists the areas and domains' tells the agent how to use it for browsing. However, there is no explicit guidance on when to prefer ha_describe_entity or ha_call_service, nor any stated exclusions.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description's genuine additions are the inclusion scope (Multi Action, Toggle Action, plugins staged for install), which usefully signals that unstaged/installed-only plugins won't appear. It says nothing about ordering, pagination, or result size for what could be a large list.

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, and the core scope statement is front-loaded before the inclusion caveat. Every clause carries information an agent can use.

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

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

With a full output schema, complete parameter descriptions, and rich annotations, the description only needs to supply scope and inclusion nuance — which it does. The one remaining gap is result behavior (ordering/pagination/volume) for a potentially long action list.

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

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

Schema description coverage is 100%, so all three filters (query, plugin, controller) are already documented inline, and the return-schema fields are covered by the output schema. The description does not add filter semantics 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?

The description gives a specific verb+resource ("List actions that can be placed on keys or dials") and enumerates the returned fields (name, plugin, uuid, controllers, states), plus names two built-in action types and staged plugins. Purpose is unmistakable, but it never explicitly distinguishes itself from the sibling describe_action, which is the natural confusion point in this toolset.

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

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

"Actions that can be placed on keys or dials" implies the use case (discovering assignable actions, presumably before set_key), but there is no explicit statement of when to call this versus describe_action or find_plugins, and no exclusions. Guidance is inferable rather than stated.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely behavioral context beyond them: results are ordered newest-first, and the entries originate from two named mutation tools. Return format and pagination are not discussed, but the output schema covers that.

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 compact sentence with no filler, front-loaded with the resource and immediately followed by the two most useful facts (provenance, ordering). Everything present 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?

An output schema exists, so return values needn't be explained, and annotations cover safety. However, for a one-parameter tool the lone 'limit' parameter is left completely unspecified, and the absence of usage guidance leaves the agent to infer the inspect-before-restore workflow.

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?

There is one parameter (limit) with 0% schema description coverage, so the description carries the full burden and must compensate. It says nothing about what limit controls, its default of 10, or any maximum, leaving the only tunable knob undocumented in both places.

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 resource (backups) and adds scope via provenance ('taken by apply_changes and restore_backup') plus ordering ('newest first'). An agent can distinguish this from restore_backup (which consumes backups) without opening the schema, though it never explicitly names that routing.

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?

No when-to-use or when-not-to-use guidance. The provenance hint weakly implies this is how you inspect available backups before calling restore_backup, but that relationship is never stated, and no alternatives or exclusions are given.

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 a non-readOnly, non-destructive, non-idempotent mutation, so the safety profile is covered. The description adds real behavioral context on top: 'Staged only' tells the agent nothing is committed until apply_changes runs, and the one-level limit plus the generated Back key describe structural side effects not present in 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 short sentences with zero filler. The core action is front-loaded in the first clause, the structural caveat follows, and 'Staged only.' closes with the one operational fact an agent most needs. Nothing can be cut without losing 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?

An output schema exists, so return values need not be described, and annotations carry the safety profile. The description covers the nesting limit and staging requirement, which are the non-obvious behaviors. It could have named apply_changes or discard_changes as the follow-up to 'staged only', which is the only real gap for this 7-parameter mutation tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond it by explaining how 'name' is consumed — the folder is created as '<this profile's folder>/<name>' — which clarifies the path composition and the implicit link to the selected profile. It adds no detail on image, back_slot, or back_image, but those are fully 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 ('Make a folder') and explains what a folder actually is in this system: 'a new profile opened by a key on this one, with a Back key inside.' That is well beyond a restated name. It does not name or contrast any sibling (add_child, manage_profile, set_key), so it loses the differentiation point.

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 one-folder-level constraint and the staged nature imply context, but the description never says when to choose make_folder over add_child, manage_profile, or set_key, nor does it state prerequisites such as the slot needing to be empty (that lives only in the 'slot' schema description). Usage is implied rather than stated.

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

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

Annotations already establish it is non-destructive (destructiveHint=false) but does perform work with open-world lookups (openWorldHint=true). The description adds genuinely useful behavioral context beyond that: it produces a preview and writes a file artifact, and the schema-supplied defaults (colour, background) are complemented by the note that defaults are auto-chosen for readability and brand colour. No permission or rate-limit detail, but little is expected here.

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 zero filler, and the core purpose is front-loaded ahead of the output/usage note. Every clause carries information an agent needs.

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

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

There is no output schema, so the description usefully documents what comes back (a preview and a file path) and how to consume it. For a single-purpose asset-generation tool this is nearly complete; only minor details such as output image format or overwrite behavior are absent.

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 every parameter including the icon syntax, scale range, style values, and colour/background formats. The description only restates the input categories in prose and adds no syntax or format detail beyond what the schema provides; baseline 3 is correct.

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

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

States a specific verb and resource ('Make a key image') plus the four input modes it supports (text, emoji, brand logo, generic symbol). This clearly separates it from sibling find_icons, which only looks up icon names rather than producing the image.

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

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

The description explicitly routes the agent downstream: the returned file path is meant to be passed as `image` to set_key / update_key / add_child, and it points at find_icons for discovering icon names. It stops short of stating when this tool is unnecessary (e.g. when an image already exists), so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds genuinely new behavioral context: renaming cascades to app rules and Switch Profile keys that reference the profile, and all operations are staged only. This also implicitly explains why destructiveHint=false is correct despite the delete operation. It stops short of describing permissions, reversibility, or error behavior.

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

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

Two sentences, both earning their place. The core capability is front-loaded in the first sentence, and the two non-obvious consequences (rename cascade, staging) are packed into the second with no filler.

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

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

An output schema exists and annotations cover the safety profile, so the description need not explain return values. It covers operations, key side effects, and staging, but a brief pointer to the staging workflow (e.g. that apply_changes/discard_changes finalize or revert) would make it complete for a multi-operation mutation tool.

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

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

Schema description coverage is 80%, so the schema already documents device, profile, new_name, copy_from, and the operation enum. The description adds little parameter-level detail beyond the rename cascade side effect; per the rubric, baseline 3 is appropriate 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?

The description names a specific resource (a profile) and enumerates the exact operations it performs (create, duplicate, rename, delete, make selected), so the agent immediately knows what kind of tool this is. It does not explicitly contrast itself with the read-only sibling 'show_profile', so it falls just short of full sibling differentiation.

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

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

'Staged only' implies the mutation workflow (changes must later be applied rather than taking effect immediately), which is useful context. However, it never states when to choose this tool over siblings like show_profile, preview_changes, or apply_changes, leaving the usage model implied rather than explicit.

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

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

The annotations already settle the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent), and the description usefully adds that the operation is staged only rather than applied live, plus that child keys, images and titles are carried along. It stops short of warning about overwrite risk in swap/copy mode or stating a rollback path, 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?

Two compact sentences with no filler; the action, the payload, and the staging constraint are front-loaded in that order.

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 seven parameters, an output schema, and annotation coverage, the description supplies enough to call the tool correctly, and the staging note orients the agent in the workflow. It leaves the mode-specific preconditions and the required follow-up tool to inference, which is a minor gap rather than a blocking one.

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 (mode, device, profile, from_slot, to_slot, to_device, to_profile) is already documented with examples and defaults. The description only restates the mode values, so it adds no meaning beyond the schema and 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?

The description states specific verbs (move, swap, copy) applied to a specific resource (a key), and enumerates the payload that travels with it (settings, title, image, children) plus the scope (within a profile or to another profile/device). This clearly separates it from siblings like set_key, update_key, clear_key, and add_child.

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 implied usage through the three modes, but it never names when to prefer this over update_key or set_key, nor does it explain the preconditions for each mode (that move requires an empty destination, swap exchanges, copy duplicates). 'Staged only' hints at the workflow without spelling out that apply_changes is required.

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

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

Annotations already establish the safe read-only profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description still adds real value by disclosing what is surfaced: pending commands, plugin installs, and conflicts with OpenDeck edits made after staging.

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 dense sentence that front-loads the scope and then unpacks the three content categories. Nothing is wasted, though the parenthetical warnings list makes it slightly long.

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

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

An output schema exists, so return structure need not be spelled out, and the annotations cover the safety profile. The description covers what is previewed but omits the when-to-use context that would make it fully self-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?

There is one optional parameter with 100% schema coverage, including an enum whose two modes are fully described in the schema. The description adds nothing about 'detail', 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 ('Show') and a precisely scoped resource ('everything staged'), then enumerates the content: per device/profile/slot changes, warnings, and conflicts. An agent can distinguish it from siblings like get_overview, discard_changes, and apply_changes 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?

Usage is only implied — an agent can infer this is the read step before apply_changes or discard_changes — but the description never states when to use it, and does not rule out lookalikes such as get_overview or render_profile.

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 a safe read operation (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds a genuinely useful behavioral note beyond that: 'tokens redacted', which tells the agent output is sanitized. It doesn't mention truncation behavior of the 'lines' tail, but the redaction disclosure earns credit.

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 compact sentences with the resource scope front-loaded and the usage hint trailing. Every element earns its place, though the usage hint is terse enough to be marginally under-specified rather than 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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description covers the two log sources and the redaction behavior; the only minor gap is no mention of what a tail/filter operation returns or how 'lines' bounds output.

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

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

Schema coverage is 67% – the 'grep' and 'plugin' params are documented in the schema, while 'lines' is not. The description reinforces the plugin-omission semantics ('OpenDeck's log or a plugin's log'), matching the schema's plugin description, but adds no new syntax or format detail. Baseline 3 is appropriate given partial schema coverage.

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

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

The description states a specific verb ('Tail') and resource ('OpenDeck's log or a plugin's log'), and explicitly covers both log sources, which an agent can distinguish from other read tools. It does not differentiate from siblings beyond naming the log resource, but the purpose is unambiguous.

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

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

The phrase 'Useful after apply_changes' implies a usage context, effectively pointing to the apply/verify workflow. However, it offers no explicit alternatives, no when-not conditions, and no guidance on choosing between OpenDeck's log and a plugin's log beyond the schema default.

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 a non-read-only, non-idempotent, non-destructive mutation, so the safety profile is covered. The description adds the useful "staged only" context that the change is not immediate, but says nothing about index shifting of remaining children or how staged changes are committed.

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 terse sentences with the operation and its staging constraint front-loaded and zero waste.

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

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

An output schema exists and annotations carry the safety profile, so much is covered structurally. However, for a mutation that is "staged only," the description never tells the agent how staged changes take effect, leaving a meaningful workflow 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 description coverage is 100%, so device, slot, child, and profile are all documented in the schema. The description adds no additional meaning about parameter format or constraints, 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 ("Remove") and resource ("one action from inside a Multi/Toggle Action"), which is clear and actionable. It doesn't explicitly name the sibling add_child as its inverse, but the operation 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?

"Staged only" implies the change is queued rather than applied, which is light workflow guidance. There is no explicit when-to-use vs alternatives (e.g., add_child, set_multi_delays) or statement of prerequisites.

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 destructiveHint=false, so the safety profile is covered. The description adds that staged changes appear outlined and that this is a visual render, but does not disclose return format, image type, or auth/permission needs.

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

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

Two tight sentences with no waste: the render content is front-loaded, then the usage. 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?

For a 4-param read-only render tool with no output schema, the description conveys that the result is a visual picture, which is the key thing an agent needs. Minor gaps remain around output format and comparison behavior, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema fully documents device, staged, compare and profile. The description's 'staged changes outlined' loosely echoes the staged parameter but adds no syntax or format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb+resource: rendering a picture of the deck as OpenDeck draws it, enumerating the visual content (icons, titles, colours, dials). An agent can distinguish it from mutation siblings, though the boundary with preview_changes/show_profile is not spelled out.

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 usage context: 'Use it to check a layout before applying, or to show the user.' That covers the two main scenarios, but it does not name alternatives (e.g. preview_changes, show_profile) or state when not to use it.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the operation restarts OpenDeck, and the confirm=false preview pattern gives a safe dry-run path. It doesn't state irreversibility or whether the restore can itself be undone.

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, purpose front-loaded, no filler. The restart side effect and the confirm=false workflow both earn their 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?

The output schema exists so return values need no explanation, and annotations cover the destructive profile. However, for a destructive 3-param tool, the required backup_id is undocumented and no sibling (e.g. list_backups) is named as the source of a valid ID, leaving a real gap in how to invoke it correctly.

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

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

Schema description coverage is 0% across 3 parameters, so the description must compensate. It explains the semantics of 'confirm' via the preview flow, but leaves 'backup_id' (the required parameter) and 'show_window' entirely unexplained, including how a backup_id is obtained.

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 ('Undo an apply') and resource ('the files it changed back as they were'), which distinguishes it clearly from apply_changes and undo_live. An agent can identify the operation without opening the schema.

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

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

Gives an explicit two-phase procedure: 'Call with confirm=false first to see what would be restored', which is real when-to-use guidance. It doesn't disambiguate from the sibling undo_live, which leaves some routing ambiguity for a similar-sounding operation.

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=false and destructiveHint=false, so safety is largely covered. The description adds one genuinely useful behavioral fact beyond annotations: the change is staged, not live. It omits other relevant traits such as overwrite semantics for duplicate app/device rules and the fact that idempotentHint=false implies repeat calls are not no-ops.

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 the effect front-loaded and the staging constraint second. No filler. 'Staged only' is slightly telegraphic, but it earns its place as the key operational caveat.

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

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

An output schema exists and annotations cover the safety profile, so return values and risk need not be restated. Still, for a mutation that participates in the stage/apply workflow alongside apply_changes, discard_changes and preview_changes, the description does not explain precedence, overwrite behavior, or how rules interact, leaving an agent to infer the workflow.

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 explains all three parameters in detail, including the 'opendeck_default' fallback and null-to-remove semantics. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource and outcome: create an app rule that automatically switches a device to a profile when an app is focused. That is clearly distinguishable from the read-side sibling get_app_rules and from set_key/manage_profile. It stops short of explicitly naming those siblings, so it is clear but not fully differentiated.

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?

'Staged only' implies the change must be committed via apply_changes/discard_changes, which is a real usage hint. However there is no explicit when-to-use guidance, no mention of get_app_rules for inspection, and no note about whether an existing rule for the same app/device is replaced.

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

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

The annotations declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), and the description adds genuinely new context: the value is stored locally and does not touch OpenDeck. That clarifies the blast radius in a way the annotations alone don't. It stops short of saying what happens on overwrite of an existing layout.

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 action and its condition, then the caution. 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?

An output schema exists, so return values need not be explained, and the annotations cover safety. The description handles the when-to-use question well. It is only slightly short on parameter constraints and overwrite semantics for a local-config mutation.

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 33% – only 'device' is documented (pointing to get_overview). The description's phrase 'key grid size' loosely implies what rows/columns mean, so it partially compensates, but it adds no units, ranges, or validity constraints for those two required integers.

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 verb+resource is specific: it sets a device's key grid size and states the trigger condition ('when it can't detect it'). The parenthetical 'stored locally; doesn't touch OpenDeck' further scopes what kind of write this is, distinguishing it from live-mutation siblings. It doesn't name a sibling explicitly, but the purpose is unambiguous.

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

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

It gives an explicit condition for use ('when it can't detect it') and an explicit when-not ('Usually unnecessary: the bridge plugin records it automatically'), naming the automatic path that normally replaces this call. An agent can decide whether to invoke this without 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 provide the safety profile (write, not destructive, not idempotent), but the description adds two traits beyond them: 'replacing whatever is there' (overwrite semantics) and 'Staged only' (the change is not live until applied). The staging disclosure is especially valuable for an agent that must later call apply_changes. Nothing here contradicts the annotations.

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

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

Three tight sentences, front-loaded with the core purpose before the dial and Multi/Toggle conditions. No filler, though the trailing conditional tips could be grouped more cleanly.

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

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

An output schema exists, so return values need no explanation, and all parameters are covered by the schema. The description correctly closes the loop on the staging model and the dial/Multi/Toggle workflows, leaving little an agent 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%, so the schema already documents all eight parameters, including the slot, device, action, image and title_style formats. The description's only parameter-level addition is that dial actions must 'support Encoder,' which is marginal beyond what the schema states. 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 ('Place an action on a key or dial') with the scope qualifier 'replacing whatever is there,' so an agent knows this overwrites rather than appends. It distinguishes itself implicitly from add_child by routing Multi/Toggle follow-ups there, but does not explicitly differentiate from update_key or clear_key, so it falls short of full sibling disambiguation.

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 conditional guidance ('For dials use dial<N> with an action that supports Encoder' and 'For a Multi/Toggle Action, set it here, then add_child'), which is genuinely useful workflow context. However it never states when to use set_key versus update_key or clear_key for the ordinary key case, leaving the main selection decision 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 this is a non-read-only, non-destructive, non-idempotent mutation. The description adds genuinely useful context beyond them with 'Staged only,' telling the agent the change is deferred rather than applied immediately. It stops short of explaining defaults or error behavior.

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

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

Two short sentences with the action front-loaded and the critical staging qualifier stated immediately after. 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?

With annotations, full schema coverage, and an output schema, the description needs only to convey purpose and the staging behavior, which it does. A pointer to apply_changes for committing would make it airtight, 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 coverage is 100%, so all four parameters including slot, device, profile, and delays_ms are already documented in the schema. The description adds no parameter detail, so the baseline of 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 (set) and resource (the pauses between the children of a Multi Action), so the operation is clear. It does not name or differentiate itself from siblings, but the function is distinct enough that confusion is unlikely.

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?

'Staged only' implies the change does not take effect until apply_changes runs, which is implied usage guidance. However, it does not explicitly say when to use this versus alternatives like set_key or add_child, nor does it spell out the staging workflow.

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, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds the genuinely non-obvious lifecycle fact that the write is staged-only and the settings scope is global rather than per-instance, which is real value beyond the annotations.

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

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

Two short sentences, zero filler, with the verb and scope front-loaded and the staging caveat at the end. Nothing could be cut without losing 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?

An output schema exists, so return values need not be explained. Still, for a mutation with a nested object payload and an undocumented remove_keys parameter, the description omits the removal capability entirely and does not state how the staged change becomes live, leaving a meaningful gap.

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

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

Schema coverage is 67%: plugin and values are documented (including merge semantics and the secret-preservation behavior), but remove_keys has no description anywhere. The description adds no parameter-level detail beyond the word 'global', so it only partially compensates for the undocumented removal parameter.

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

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

States a specific verb+resource ('Change a plugin's global settings') and scopes it ('plugin-wide'), with a concrete example ('e.g. a server URL'). It does not name the read-side sibling get_plugin_settings, but the write/read distinction is unambiguous from the verb.

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?

'Staged only' implies the change is queued rather than applied immediately, which hints at the stage_plugin / apply_changes / discard_changes workflow in the sibling set. However, it never says how to commit the change or when to prefer this over alternatives, so the agent must infer the full lifecycle.

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 this a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower, yet the description adds genuinely useful behavior: staged-but-unapplied changes are included and marked with '*', and the slot labels shown are exactly those the editing tools accept. It stops short of explaining ordering or how 'state' is encoded, but the mutation-vs-staged disclosure is valuable.

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, purpose front-loaded and zero filler. The second sentence carries two distinct pieces of useful info (staged markers, editable labels) without padding, though its fragment style is slightly denser than needed.

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

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

With an output schema present the description needn't explain return values, and annotations cover the safety profile. It supplies the staged-change and label semantics an agent needs, leaving only sibling disambiguation (render_profile, preview_changes) unaddressed.

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

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

Schema coverage is 75% (device, profile, and show_settings are documented; show_children is not), which puts this near the high-coverage baseline. The description adds no parameter-level meaning beyond display conventions, so it neither compensates for the undescribed flag nor exceeds 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 (render) and resource (profile) plus what the output contains: a grid sketch, every occupied slot with its action, title and state. Clear on its own, but it never distinguishes itself from the sibling render_profile or preview_changes, which an agent must otherwise disambiguate by schema inspection.

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 only implied: reading a profile's current layout. Nothing states when to prefer this over render_profile, preview_changes, or get_overview, and no prerequisites or exclusions are given. The closing note about labels feeding editing tools hints at workflow but not at selection.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, but the description adds the crucial behavioral facts: installing executes third-party code on the user's machine, a two-phase confirm gate protects the user, and removal clears the plugin's keys everywhere. The destructiveHint=false annotation is consistent because this only stages changes (apply_changes actually applies them), so no contradiction arises.

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 highest-risk fact (third-party code execution) and the required safety protocol. Every clause earns its place; no filler or restated schema fields.

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

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

With an output schema present, return-value explanation isn't needed, and the description still previews the inspection payload (author, version, checksum, AI-assisted flag). For a mutation-capable, open-world tool it covers operations, the safety workflow, and side effects such as key clearing, leaving no material 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?

At 60% schema coverage, the description compensates by explaining the confirm flag's two meanings (inspect vs stage) and enumerating the operation set (install/update/remove). It also names find_plugins for the plugin_id, though it doesn't clarify the source/url relationship beyond what the schema already documents.

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 triplet plus resource: "Install, update or remove a plugin." An agent can immediately tell this manages plugin lifecycle, distinct from siblings like find_plugins (discovery) and get_plugin_settings (configuration). No ambiguity about the resource or the operations available.

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 conditional workflow: call with confirm=false first, show the user what was found, and only stage with confirm=true after they agree. It also routes the agent to find_plugins for catalogue ids, naming the sibling alternative. Nothing is left to inference about when and how to invoke it.

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

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

Annotations already flag destructiveHint=true, readOnly=false, and non-idempotent, so the safety profile is covered. The description adds genuine context: the ordering semantics ('newest first') and the exact payload that gets reverted. It stops short of saying whether an undo is itself reversible or what happens when no live edits exist, so a 4 rather than 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?

Two sentences, zero filler. The action and scope are front-loaded, and the routing guidance to alternatives is packed into the second 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. Scope, ordering, and sibling routing are all present; the only minor gap is error/no-op behavior when there is nothing left to undo.

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 'count' parameter is fully documented in the schema. The description only reinforces the ordering ('newest first'), which implies how count selects edits but adds no format or edge-case detail 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 (undo) plus the resource (latest instant/live edits), scopes it to edits made by update_key, and enumerates what reverts (titles, images, settings). This distinguishes it cleanly from update_key, discard_changes, and restore_backup 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 names the alternatives (discard_changes, restore_backup) and the condition that selects them ('staged changes and applied plans'), leaving the agent no inference work to pick the right tool.

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

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

Annotations mark this as non-read-only, non-destructive, non-idempotent, but the description goes further: it explains the live-vs-staged routing, that live edits land on the plugin as if edited in OpenDeck's own panel, and that an open settings panel must be reopened to see the change. Those are exactly the behavioral traits annotations cannot convey.

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

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

Three dense but well-ordered sentences: purpose first, then the routing rule, then the panel caveat. Every sentence carries information, though the panel-reopening aside is somewhat niche detail layered on an already long description.

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

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

For a 12-parameter mutation tool with an output schema present, the description covers the significant unknowns: how changes are applied, how to undo, and what the result tells you. Nothing an agent needs to invoke it correctly appears 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 75% and the schema itself documents mode, slot, image, state, profile, title_style, settings_merge etc. in detail, so the description adds useful framing rather than raw syntax – it tells the agent which parameters drive the live vs staged decision. It doesn't enumerate the settings-merge/replace/remove triple, but the schema handles that.

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 an existing key') and immediately bounds the scope with 'without replacing its action,' which cleanly separates it from set_key/clear_key. A list of the mutable attributes follows, so an agent knows exactly what this tool edits.

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 partitions what applies instantly (title text, image, settings on the connected device's profile) from what is staged for apply_changes (title style, current state, other profiles, staged devices), and names the alternatives undo_live and apply_changes. This is a textbook when/when-not/alternatives breakdown.

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