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

With no annotations, the description carries the full burden. It adds one genuine behavioral fact — 'Audit-logged' — and notes the return is a post-action CoverState, but says nothing about permissions, whether the move is interruptible, or how conflicting action+position inputs are resolved.

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, so the agent gets the core semantics immediately. No filler; every clause carries either parameter meaning or behavioral context.

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

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

An output schema exists, so the brief CoverState mention is sufficient rather than redundant. Core invocation semantics are covered, with the only real gap being device/channel resolution that no structured field or description explains.

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%, so the description compensates partially by enumerating action values (open|close|stop) and the position range (0-100), which the schema does not express. However, device and channel — including the channel default of 0 — remain undocumented anywhere.

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 ('Move') and resource ('roller/cover'), making it clearly distinguishable from shelly_switch_set and shelly_light_set which target other device classes. It stops short of explicitly contrasting itself with siblings, but the resource framing 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 description tells the agent the two operating modes (discrete action vs. positional), which implies usage, but offers no when-to-use versus alternatives or exclusions. An agent still has to infer which mode to prefer and whether device types matter.

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 'Safe, read-only' is largely redundant. The genuinely additive parts are the disclosure that mDNS discovery is time-bounded and that the result is a 'lightweight identity' set requiring a follow-up probe, which tells the agent not to expect full device state 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?

Three short segments, front-loaded with the core action, then parameter notes, then safety/return caveat. No padding or filler sentences; the markdown-style backticks are slightly noisy but harmless.

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

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

With an output schema present, return values need not be spelled out, and the description still adds the useful 'probe for detail' caveat. Covers purpose, both parameters, safety, and LAN/cloud behavior; the only real gap is interaction with the shelly_list_devices sibling.

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%, so the description carries the full burden and does explain both parameters: timeout_s as the mDNS browse window and use_cloud=false as the LAN-only switch. It omits the schema defaults (5 and true), but the meaning and effect of each parameter are clear.

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 with its discovery mechanism: 'Discover Shelly devices on the LAN via mDNS, merged with the cloud account list.' It is concrete about scope (LAN + cloud), though it does not distinguish itself from the sibling shelly_list_devices, which an agent could reasonably confuse it with.

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

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

Gives a conditional usage hint for a parameter ('Set use_cloud=false to skip the cloud list (LAN-only)') and implicitly routes detail-seeking callers elsewhere via 'probe for detail'. However, it never explicitly says when to prefer this over shelly_list_devices or which sibling to call for the referenced detail.

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

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

Annotations only declare readOnlyHint=true, so the description carries the behavioral burden and does well: it flags the 'best-effort' nature, degraded cloud coverage, device-model specifics (Pro 3EM EMData/CSV, Gen1 em_data.csv), and that richer queries depend on unimplemented local backends. It stops short of return/auth details, but adds substantial context beyond the annotations.

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

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

Two compact sentences with the core capability front-loaded and the limitation/roadmap detail secondary. Dense but not wasteful, though internal jargon (M2, EMData) adds minor noise.

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 narrated, and the behavioral limitations are covered. The gap is parameter semantics: for a 2-param tool with 0% schema coverage, the definition is incomplete on how device/channel steer the result.

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

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

Schema description coverage is 0% for two parameters (device, channel), and the description does not mention either. With no schema documentation to fall back on, the description fails to explain what device or channel mean or how channel maps to per-minute series, so it 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?

The description states a specific resource and scope: lifetime energy totals plus per-minute series exposed in device status. The 'history' framing implicitly distinguishes it from shelly_energy_live, but it never names that sibling, so the distinction is inferred 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?

It discloses real usage constraints (cloud only yields totals + recent per-minute; richer history needs a local connection), which helps the agent set expectations. However, it never states when to prefer shelly_energy_live over this tool or any explicit selection criteria, leaving usage implied.

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

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

readOnlyHint already declares the safety profile, but the description adds genuinely useful behavior beyond annotations: 'None where a device can't report it (e.g. Gen1 plugs have no voltage/current)' explains null handling per device generation. The trailing 'Safe, read-only' is redundant with the annotation rather than additive.

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

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

Three short sentences, front-loaded with the metric list, then null behavior, then channel guidance. Efficient, though the final 'Safe, read-only' clause repeats the annotation and could be dropped.

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 detailed, yet the metric list plus the null caveat give the agent enough to interpret results. The only real gap is the unexplained required 'device' parameter, which is minor given the obvious device-identifier context.

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

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

Schema description coverage is 0%, so the description must carry the parameter load. It explains the optional channel param ('narrow to one'), but the required 'device' param is left undocumented in both schema and description. Partial compensation warrants a baseline 3.

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

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

States a specific verb+resource ('live power/energy per channel') and enumerates the returned metrics (power_w, voltage, current, pf, freq, totals). 'Live' implicitly contrasts with the shelly_energy_history sibling, but no sibling is named, so the differentiation is only suggested 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?

Implied usage is clear from 'Live' (real-time readings) and 'Pass channel to narrow to one,' but it never says when to choose this over shelly_energy_history or shelly_get_status. No exclusions or alternatives are given, leaving routing 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?

With readOnlyHint already covering the safety profile, the description adds high-value behavior: credential fields are masked as ***, Gen1 /settings would otherwise leak Wi-Fi/MQTT secrets, and cloud-only devices get an actionable error. This is exactly the security and failure-mode context an agent 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?

Purpose is front-loaded in the first clause, followed by supporting security and locality notes. The dense parenthetical is justified by the security rationale, and there is little wasted text.

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

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

An output schema exists so return values need not be explained, and annotations cover read-only safety; the description adds masking and error behavior. The one real gap is the undocumented 'component' parameter.

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% and there are two parameters. The description implies the 'device' target but never explains the optional 'component' parameter, leaving half the inputs undocumented in both schema and description.

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

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

States a specific verb and resource ('Get a device's configuration') and adds meaningful scope via credential masking and the local-only constraint. However, it never explicitly distinguishes itself from similar-sounding siblings like shelly_get_info and shelly_get_status, so the agent must infer which to pick.

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 'Local-first — the Shelly Cloud API can't expose config' note is a genuine usage constraint, telling the agent this only works for locally reachable devices and errors for cloud-only ones. But no alternative tool is named for when this isn't appropriate, and there is no explicit when-not guidance beyond the cloud limitation.

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 'Safe, read-only' largely restates that rather than adding new behavioral detail. The description does add that the device may be addressed by id or configured name, which is operationally useful, but says nothing about failure behavior or lookup cost.

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

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

Two sentences, front-loaded with the purpose and the returned information, then the parameter clarification, then the safety note. No filler; every sentence earns its place.

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

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

An output schema exists, so return-value documentation is not required, and annotations cover the safety profile. The only notable gap is error/not-found behavior and how the identifier forms differ, which would help an agent recover from a bad lookup.

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%, so the description carries the burden for the single parameter, and it does so: '``device`` is a device id or a configured name' explains the accepted identifier forms beyond the bare 'string' type in the schema. It stops short of format examples or how to obtain a configured name.

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 ('Identify') and resource ('one device') and enumerates what the response covers (generation, model, firmware, online state, capabilities). It implicitly contrasts with the list-style siblings ('one device'), but never names an alternative such as shelly_list_devices or shelly_get_status to make the boundary 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 'one device' hints that this is the single-device lookup as opposed to the list tools, and the field enumeration implies a low-level inventory use case. However, there is no explicit when-to-use statement, no guidance on choosing this over shelly_get_status or shelly_get_config, and no mention of what happens for an unknown device.

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

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

Annotations only declare readOnlyHint=true; the description adds real context by stating the output folds Gen1/Gen2/Cloud into one canonical shape while also returning the raw per-generation payload. 'Safe, read-only' partially restates the annotation, but the normalization behavior is genuinely additive.

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

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

Three tight sentences, each earning its place: purpose and scope first, then the optional narrowing parameter, then the safety profile. No filler.

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

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

With an output schema present, return values needn't be spelled out, and the description still adds the normalization framing. The one gap is the undescribed required `device` parameter, though its meaning is fairly self-evident.

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%, so the description must carry the load. It explains `component` with a concrete example ('switch:0') and its narrowing effect, but says nothing about `device`, leaving the required identifier parameter undocumented.

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

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

States a specific verb and resource ('Get a device's normalized live status') and clarifies the scope with the Gen1/Gen2/Cloud normalization detail, which meaningfully separates it from shelly_get_config and shelly_get_info. It does not explicitly name a sibling, but the scope 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 tells the agent how to narrow scope with `component`, but gives no when-to-use guidance relative to the many sibling readers (get_config, get_info, energy_live). Usage is implied rather than contrasted with alternatives.

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

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

Annotations only declare destructiveHint=true; the description adds genuinely new behavioral context — that a confirm:true gate is enforced and that the action is audit-logged. It stops short of saying whether deletion is reversible or what scope of data is removed.

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, each earning its place: action, precondition, side effect. The core action is front-loaded with zero preamble.

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

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

For a destructive mutation, the description covers the safety gate and audit trail, and an output schema exists so return values need not be explained. The remaining gap is that the two required identifier parameters are undocumented, which slightly weakens the definition.

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%, so the description must carry the load. It clarifies that 'confirm' must be true (beyond the schema's default:false) but leaves 'device' and 'key' unexplained — no format, no naming convention, no indication of what a device identifier looks like.

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

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

States a specific verb and resource ('Delete a KVS key'), which cleanly separates it from shelly_kvs_get, shelly_kvs_set, and shelly_kvs_list. It doesn't explicitly name or contrast a sibling, but the operation 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 description states a precondition ('Requires confirm:true') but gives no when-to-use vs. alternatives guidance, e.g. when to delete a key versus mutating it with shelly_kvs_set or going through shelly_rpc_write. Usage is implied rather than explained.

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?

readOnlyHint=true already establishes the safe-read profile, so the bar is lower. The description adds genuinely useful context that the returned value carries its etag, but says nothing about error behavior for missing keys or the fact that a device must be targeted.

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; every element (scope, resource, lookup key, etag detail) 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 read-only annotation covers safety. The remaining gap is that a required parameter (device) is left semantically undefined in both the description and the schema, which is thin for a two-parameter required-argument 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 0% for both parameters. The description explains the 'key' argument implicitly, but the required 'device' parameter is never addressed anywhere — it is unclear whether it expects a device ID, name, or address, and 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?

The description states a specific verb (Get), a precise resource (one KVS value), and the lookup key, which cleanly separates it from the sibling kvs_list (many), kvs_set, and kvs_delete. It does not name those siblings explicitly, so it stops short of full differentiation, but an agent can route correctly from the text alone.

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: read a single value when the key is known, as opposed to listing all pairs. There is no explicit when-to-use/when-not guidance and no alternative tool is named, leaving the agent to infer the list-vs-get distinction.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that key etags are returned and that match defaults to all, which is useful, but it says nothing about pagination, result limits, or the required device binding.

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

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

Two short sentences with zero filler; the core action is front-loaded and the parameter note follows. Nothing is redundant.

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

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

An output schema exists, so return-value detail is not required. However, for a two-parameter tool with a required device argument, the definition omits any explanation of that required parameter and of result scoping, leaving a real 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 0%, so the description carries the burden. It fully clarifies the non-obvious 'match' parameter (wildcard pattern, default '*'), but the required 'device' parameter is never mentioned, leaving its expected format (ID vs name vs host) unexplained.

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

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

States a specific verb and resource ('List KVS keys') and adds that etags are included, which distinguishes it from the sibling shelly_kvs_get. It never explicitly names the alternative, but the read/list shape 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?

No guidance on when to use this versus shelly_kvs_get or shelly_kvs_set; the agent must infer that 'list' means enumerate keys rather than fetch one value. No prerequisites or scope constraints are stated.

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

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

Annotations only supply idempotentHint=true, so the description carries most of the burden. 'Audit-logged' is genuine added context beyond the annotation, but it omits overwrite semantics for existing keys, required permissions/auth, and any rate or size limits.

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 core action and no wasted words. The trailing 'Audit-logged' fragment is terse but functional rather than padding.

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

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

An output schema exists so return values need not be explained, and the tool is a simple setter. Still, with zero schema coverage and only an idempotency annotation, the undocumented 'device' parameter and absent overwrite/permission notes leave meaningful gaps.

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

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

Schema description coverage is 0% across three required parameters. The description clarifies that the value is JSON, partially covering 'key' and 'value', but the required 'device' parameter is never mentioned or explained anywhere.

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 (KVS key) with the value format (JSON), which distinguishes it from the sibling get/delete/list KVS tools. It does not, however, explicitly name those siblings or contrast scope with them.

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 guidance, no prerequisites, and no mention of alternatives such as shelly_rpc_write or the other shelly_kvs_* tools. The agent must infer usage purely from the verb.

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

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

With only idempotentHint=true in the annotations, the description carries meaningful extra load: partial-update semantics ("Only the provided fields are changed"), the post-action return (LightState), and the audit-logging trait of a write operation. It stops short of stating permission requirements 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?

Purpose is front-loaded in the first line, then behavioral and parameter detail follows in compact sentences with no waste. The generation-mapping parenthetical is dense but short.

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

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

An output schema exists, so the return value needn't be re-explained, and the description correctly covers update semantics and audit logging. However, for an 8-parameter mutation with zero schema description coverage, half the parameters and any auth/prerequisite context remain undocumented.

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 0% across 8 parameters, so the description must compensate. It documents brightness (0-100), rgb (three 0-255 values) and temp_k (white colour temperature), but leaves on, white, channel, transition_s, and the required device parameter unexplained in both schema and description.

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

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

States a specific verb (Set) plus the exact resource and channel types (light/dimmer/RGB(W)/CCT), which cleanly separates it from shelly_switch_set, shelly_cover_move and shelly_rpc_write. An agent can identify the tool without opening the schema.

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

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

The channel-type phrasing implies when to reach for this tool versus switch/cover siblings, but no alternative is named and no when-not condition is given. Usage 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?

'Safe, read-only' merely restates the readOnlyHint annotation already present, so it earns no credit. Beyond that the description adds the discovery-purpose context but says nothing about behavior on an unknown device, auth requirements, or error semantics; with an output schema present, return-format disclosure isn't needed either.

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, front-loaded sentences with a useful inline example and no filler. The only wasted phrase is 'Safe, read-only,' which duplicates the annotation.

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

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

With annotations covering the safety profile and an output schema covering the return shape, the description only needs to establish purpose and workflow placement, which it does. The remaining gap is the undocumented 'device' parameter format.

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 'device' parameter, so the description carries the full burden. It implies the parameter is a device identifier ('present on a device') but never specifies the expected format (device ID, IP, name) or how to obtain it, leaving the agent to guess.

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

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

States a specific verb+resource ('List the component keys present on a device') and gives a concrete example output (['switch:0', 'input:0']), which pins down the return shape. It implicitly separates itself from shelly_list_devices by scoping to a single device's components, though it never explicitly names a sibling it could be confused with.

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

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

Gives a clear when-to-use rule: 'Use this to discover what a specific device exposes before reading status or controlling it,' which places it as a prerequisite step ahead of shelly_get_status / shelly_switch_set. No when-not conditions or named alternatives are provided, so it falls short of a 5.

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

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

The description repeats the readOnlyHint annotation ('Safe, read-only') and restates return fields that the output schema already documents. Its genuinely additive content is the source scope ('configured + cloud account'), which is modest but useful. No auth, pagination, or failure behavior is disclosed.

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

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

Two sentences, front-loaded with the scope-defining clause and with zero filler. Every phrase adds either scope or routing context.

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 enumerate return values, and it correctly limits itself to source scope and sequencing. A short note distinguishing it from shelly_discover would make it airtight given the 40+ sibling surface.

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 nothing to disambiguate and the schema carries no semantic load. Baseline 4 applies; no filtering or scoping arguments exist that would need explanation.

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 (list) and resource (Shelly devices) and scopes it precisely as 'configured + cloud account'. It stops short of naming the nearest siblings (shelly_discover, shelly_list_components, shelly_get_info), so an agent must infer the boundary itself.

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 starting point before any status or control call' gives clear contextual placement among the status/control siblings. However, it names no explicit alternative and no exclusion, so the agent gets direction without disambiguation.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful behavioral context beyond annotations: the Gen1/cloud failure mode and that the error is actionable, which tells the agent how to interpret a failure rather than blindly retrying.

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 constraint. No filler and nothing needing to be read twice.

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

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

An output schema exists, so return-value detail is unnecessary, and the readOnly annotation covers safety. The description rounds this out with the Gen2+ applicability and error behaviour; only the device parameter's format remains unspecified.

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

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

Schema description coverage is 0% and the sole required parameter 'device' is undocumented in both places. The description only implies a device is targeted; it never says whether the parameter expects an IP, device ID, name, or discovery handle, so it fails to 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 verb (list) and resource (RPC methods a device supports), and names the underlying API (Shelly.ListMethods) plus the Gen2+ scope, which separates it from sibling list tools like shelly_list_components. An agent can identify what it returns without opening the schema.

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

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

Explicitly states the when-not condition: Gen1/cloud devices cannot enumerate methods and will yield an actionable error, implying use only against Gen2+. It does not name an alternative for those cases (e.g., shelly_rpc / shelly_list_components), 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them: method classification happens server-side and unknown methods are treated as writes and rejected, which tells the agent how failures will occur. It doesn't cover return shape or error format, but the output schema 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?

Three short sentences, zero redundancy, with the read-only constraint and the method naming patterns front-loaded. Every sentence earns its place.

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

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

With annotations and an output schema present, the description only needs to cover invocation semantics, and it covers the key ones: read-only scope, write refusal, sibling routing, and server-side classification. The only real omission is the expected format of 'device' and 'params'.

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 0%, so the description must compensate. It does add the method-naming convention (*.Get*/*.List*/*.Check*), which is genuinely useful syntax. However, the 'device' parameter (name vs ID vs IP) and the free-form 'params' passthrough are left completely unexplained, so compensation is only partial.

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

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

States a specific verb (Call), resource (read-only RPC method on a device), and scope (only *.Get*/*.List*/*.Check*). It explicitly distinguishes itself from the sibling shelly_rpc_write, so an agent can route without opening either schema.

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

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

Clearly states when not to use it (mutating methods are refused) and names the correct alternative, shelly_rpc_write. It doesn't mention that specialized read siblings such as shelly_get_status or shelly_get_config may be preferable for common cases, leaving a small routing gap.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, and the description goes well beyond them: it discloses the mandatory confirm:true gate, that calls are audit-logged, that read calls are rejected, and that destructive methods require a second gate params.i_understand_data_loss=true. The description is consistent with (and enriches) the annotation safety profile.

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 compact sentences, front-loaded with the core behavior and gating requirement, then the rejection rule and the destructive-operation exception. 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 gating, rejection, and the destructive override. The remaining gap is that device/method are left undefined despite 0% schema coverage, though shelly_list_methods and shelly_list_devices provide the discovery path.

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 4 parameters, so the description carries the burden. It explains confirm's required value and the params.i_understand_data_loss escape hatch, but never characterizes device or method (the two required params). Partial compensation for a documented-schema 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 verb and resource: 'Call any mutating RPC method', and explicitly distinguishes itself from the read-path sibling shelly_rpc by declaring that read methods are rejected. An agent can route between shelly_rpc and shelly_rpc_write without opening either schema.

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

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

Explicit when-to-use (mutating RPCs) and when-not (read methods, with the named alternative shelly_rpc). It also names the condition that triggers the elevated path: destructive methods like factory reset, wipe-all, reset-wifi.

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

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

Annotations only supply idempotentHint, so the description carries most of the burden and does well: it discloses the validation rules (methods must be non-destructive mutating methods, devices must be known), the name-collision failure mode and the overwrite escape hatch, and the Toggle warning. Missing only what happens to an existing scene that is overwritten.

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 definition and followed by validation constraints and the preference rule. No filler or restatement of the tool name.

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

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

An output schema exists so return values need not be described, and the description covers creation semantics, failure modes and content constraints. The only gap is the undocumented optional 'description' field.

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%, so the description must compensate, and it does: it explains the actions element structure as {device, method, params}, the semantic of name, and the effect of overwrite=true. Only the optional 'description' parameter goes unexplained.

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

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

States a precise verb ('Define (save)') and resource ('a named scene') plus the shape of the input it consumes, so an agent can immediately separate it from shelly_scene_run, shelly_scene_get and shelly_scene_delete in the sibling list.

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

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

Gives concrete operating conditions: fails if the name already exists unless overwrite=true, and prefer absolute Set methods over Toggle. It does not explicitly name sibling alternatives (e.g. scene_run for execution, scene_delete for removal), so the when-to-use-this-instead-of-that routing is left to inference.

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

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

Annotations already declare destructiveHint=true, so the safety profile is partly covered. The description adds genuine behavioral context beyond the annotations by disclosing the confirm gate, which the schema alone does not enforce (confirm defaults to false and is not in the required list). It still doesn't say whether deletion is permanent or how failures/unknown names behave.

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 invocation prerequisite. Every clause earns its place with no filler.

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

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

For a destructive tool whose annotations carry destructiveHint and whose output schema covers return values, the description supplies the missing invocation constraint and the target resource. Only the consequences of deletion (e.g., scene removal being permanent or affecting running schedules) are left unstated.

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

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

Schema description coverage is 0% with 2 parameters, so the description must compensate. It does so for the critical parameter by stating confirm:true is required, correcting the schema's default-false, non-required representation; 'name' is left implicit but is self-evident from 'a named scene'.

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

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

States a specific verb and resource ('Delete a named scene'), which cleanly separates it from the sibling scene operations like shelly_scene_create, shelly_scene_get and shelly_scene_run. It stops short of explicitly naming those alternatives, so it is clear but not sibling-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?

The one usage-relevant fact given is the prerequisite that confirm:true is required, which tells the agent how to invoke it. There is no explicit when-to-use vs. when-not guidance, nor any pointer to alternatives for managing scenes.

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 the description merely restates this with 'Read-only', earning no credit. The only added value is the semantic characterization of the return payload as ordered actions, which is thin given an output schema 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 short sentences, front-loaded with the action and resource. The trailing 'Read-only.' duplicates the readOnlyHint annotation and is the one element that does not earn its place.

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

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

An output schema exists, so return values need no explanation, and the tool is a simple single-param read. However, the ambiguous 'name' parameter and the absence of any failure behavior (e.g., unknown scene) leave the definition only minimally adequate.

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% and the description says nothing about the sole 'name' parameter. It does not clarify whether this is a scene display name, an ID, or a case-sensitive key, so it fails to compensate for the undocumented 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 ('Show a scene's full definition') and even characterizes the payload as 'its ordered actions'. It implicitly distinguishes itself from shelly_scene_list by promising the full definition rather than a listing, but it never names that sibling to make the contrast 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?

Usage is only implied: an agent can infer this is the tool to call when it needs a scene's actions rather than just its name. There is no explicit when-to-use, no when-not-to-use, and no reference to shelly_scene_list or shelly_scene_run as alternatives.

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

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

Annotations already declare readOnlyHint=true, and the description's 'Read-only' simply restates that with no added behavioral context. The parenthetical field list duplicates what the output schema already exposes; no auth, rate-limit, or scope caveats are provided.

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 plus a two-word safety tag; nothing is wasted and the essential verb+resource leads. Appropriate size for a trivial no-argument list tool.

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

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

With an output schema present, return values need not be explained, and with zero parameters and full annotation coverage the description is nearly complete. It only lacks any routing hint versus its sibling scene tools, keeping it just short of 5.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool is 4. No parameter-level detail is needed.

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

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

States a specific verb and resource ('List defined scenes') and even enumerates the returned fields (name, description, action count), so the agent knows exactly what it gets. It does not explicitly differentiate itself from the closely related shelly_scene_get sibling, which is the one place an agent could pick the wrong tool.

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

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

No explicit when-to-use or when-not-to-use guidance is given, and the obvious alternative shelly_scene_get (single-scene detail) is never named. Usage is only implied by the name and purpose, which is the definition of a 3.

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

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

With no annotations, the description carries the full burden and does so well: it discloses sequential best-effort execution, that a failing action does not abort the rest, the exact status vocabulary (ok/partial/failed), idempotency because scenes use absolute states, and that every action is audit-logged. This is the behavioral context an agent needs before invoking a mutating tool.

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

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

Front-loaded with the core action in line one, then structured into behavioral detail. Every sentence carries information; the only mild redundancy is restating 'best-effort and sequential' after the first line already implied it.

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

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

An output schema exists so return-value documentation is not strictly required, yet the description still defines the status field semantics, and it covers failure handling and re-run safety. Nothing needed to invoke this one-parameter tool correctly is missing.

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

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

Schema coverage is 0% and the single 'name' parameter has no schema description, so the description must carry the meaning. 'Run a named scene' makes clear the parameter identifies a scene, which is adequate compensation although no naming/format convention is given.

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

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

Specific verb+resource: 'Run a named scene', immediately setting it apart from shelly_scene_list, shelly_scene_get, shelly_scene_create and shelly_scene_delete. The first line alone tells an agent exactly what the tool does.

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

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

Explains the execution model (best-effort, sequential) and gives concrete operational guidance: a partial run can simply be re-run later. It does not explicitly contrast with direct-control siblings like shelly_switch_set or shelly_light_set, so the alternative-selection guidance is implicit 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 only supply idempotentHint, so the description carries most of the burden and does well: it discloses validation of the timespec and each method, the ≤5-call cap, the ≤20-per-device limit, and that the operation is audit-logged. It stops short of stating whether repeated identical calls create duplicates or which permission scope is required.

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

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

Dense but front-loaded: the core action and payload come first, then grammar, limits, and side effects. Every sentence is load-bearing and the code formatting aids scanning; there is 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 description covers the hard parts of the call (timespec syntax, call shape, limits, validation). It omits the meaning of the enable flag and any note on behavior when a matching schedule already exists.

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

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

Schema description coverage is 0%, so the description must compensate and largely does: it fully specifies timespec grammar (cron fields, shorthands, sun-relative offsets with ±12h cap) and the calls array (1-5 objects of {method, params}). The device parameter is only obliquely referenced (location prerequisite) and enable is never explained, leaving a 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?

The description opens with a specific verb+resource ("Create a schedule") and immediately defines the payload shape ("timespec + calls (1-5 × {method, params})"). It is trivially distinguishable from the schedule_list, schedule_update, and schedule_delete siblings.

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

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

Usage is implied by the verb — there is no explicit statement of when to create vs. update an existing schedule, nor any prerequisite/auth guidance. The one conditional note ("the device needs its location set" for sun-relative timespecs) is a useful but narrow hint rather than real when-to-use guidance.

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

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

Annotations already declare destructiveHint=true, so the destructive nature is covered structurally. The description adds two genuine pieces of context beyond that: the confirm gate and that the action is audit-logged. It does not state whether the deletion is permanent/irreversible or what errors result from a missing confirm, so it exceeds annotations only modestly.

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, front-loaded sentences with no filler; the destructive action and its precondition come first. Every sentence carries information the 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?

An output schema exists, so return values need no explanation, and the destructive hint plus confirm/audit notes cover the safety profile reasonably. However, the undocumented required 'device' parameter and the absence of any note on reversibility or confirm-missing behavior leave gaps for a destructive 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 0%, so the description carries the full burden. It explains 'id' (the target schedule) and the confirm flag's required value, but the required 'device' parameter is never mentioned in either the schema or the description, leaving a required input completely unexplained.

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

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

States a specific verb and resource ('Delete a schedule') plus the identifying key ('by id'), which cleanly separates it from the schedule_list/create/update siblings. It stops short of naming or contrasting any sibling explicitly, so it is clear but not fully sibling-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?

The description gives an invocation prerequisite ('Requires confirm:true'), which is useful guidance on how to call it safely. It does not say when to prefer this over shelly_schedule_update or other destructive siblings, nor what happens if confirm is omitted, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds a genuinely non-obvious operational constraint (local-only, cloud cannot manage schedules), but says nothing about failure modes, auth, or pagination 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, purpose first and constraint second, with no redundant restatement of the tool name. 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?

Return values are covered by the output schema and read-only semantics by annotations, so the core is present. The remaining gap is the identifier format for 'device', which an agent needs in order to actually invoke the tool 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% and the single required 'device' parameter is undocumented in both schema and description. The agent gets no hint whether device is an ID, name, IP, or index, 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 verb and resource (list schedules) scoped to a device, which cleanly separates it from shelly_schedule_create/update/delete and from shelly_scene_list. It doesn't explicitly name a sibling, so it stops short of a 5.

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

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

The parenthetical 'Local-only (cloud can't manage schedules)' tells the agent when the call is even possible, which is real usage context. However, it gives no guidance on choosing this over related tools (e.g., get_status or scene_list) and no prerequisites for the device argument.

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 only annotation is idempotentHint=true; the description adds a useful behavioral trait ('Audit-logged'). However, it omits key mutation semantics: whether unspecified fields are preserved (partial update), the interpretation of nullable fields (calls/enable/timespec defaulting to null), and any permission requirements. With a low annotation bar the added audit context earns partial credit, but the gaps keep it at a 3.

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 front-loaded sentences with no padding, and 'Audit-logged' earns its place as a behavioral signal. It is appropriately terse, though a touch more substance would not have hurt.

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, but for a 5-parameter mutation tool with 0% schema coverage the description is too sparse: it does not explain updatable fields, partial-vs-full update behavior, or null handling. An agent would likely need to guess.

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%, so the description carries the full burden, yet it only clarifies the 'id' parameter. The four other parameters (device, calls, enable, timespec) and their null-default semantics are undocumented in both schema and description.

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

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

States a specific verb and resource ('Update fields of an existing schedule') and scopes it 'by id', so the agent knows it targets an existing schedule rather than creating one. It does not explicitly name/contrast the sibling operations (schedule_create, schedule_delete), so it falls just short of a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no routing to alternatives such as shelly_schedule_create or shelly_schedule_delete. The agent must infer that this is the mutation path for an existing schedule purely 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?

With only idempotentHint in the annotations, the description carries most of the burden and does add real behavioral context: the call is 'Audit-logged', it returns an 'id', and the subsequent code-attachment step is confirm-gated. It does not mention permissions or what happens on a name collision, but the audit/confirm disclosures are genuinely beyond the structured fields.

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

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

Two short sentences, front-loaded with the action and its result, then the essential next step. Nothing is padding; 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?

The workflow context (create then put code) and the return value are covered, and an output schema exists so return details needn't be expanded. However, for a tool whose schema has 0% description coverage, leaving the required 'device' parameter entirely unaddressed is a meaningful completeness 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 0%, so the description must compensate, but it only explains one of the two parameters ('optionally named' maps to 'name'). The required 'device' parameter — the one that determines which device the script lands on — is never mentioned, leaving the most important argument undocumented in both the schema and the description.

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

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

States a specific verb and resource ('Create an empty script') and clarifies the scope ('optionally named'), which cleanly separates it from siblings like shelly_script_put_code and shelly_script_list. An agent can identify what this produces (an empty script with an id) without opening the schema.

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

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

Explicitly routes the agent to the follow-up step: 'Use shelly_script_put_code to give it code', and flags that step as confirm-gated, which is useful planning context. It does not state when *not* to use this tool (e.g., if a script already exists) or any prerequisites for the required 'device' argument.

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

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

Annotations only carry destructiveHint=true; the description adds two pieces of genuinely new context: a confirmation gate (confirm:true) and that the action is audit-logged. That is useful disclosure of irreversibility safeguards and accountability beyond the annotation, though permission requirements and side effects on running scripts are unstated.

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

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

Three short sentences, zero filler, with the action and target front-loaded and the confirmation requirement immediately after. Every sentence contributes.

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 destructive nature plus confirm gate and audit logging are covered. The main omission is any mention of the required device parameter and any prerequisite state (running/stopped) for deletion.

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 0%, so the description must compensate. It explains id as the target and clarifies that confirm must be set to true despite the schema defaulting it to false, but the required 'device' parameter is never mentioned or explained anywhere, leaving a real 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 verb (Delete) and resource (a script) plus the keying parameter (id), which clearly separates it from siblings like shelly_script_get_code, shelly_script_put_code, and shelly_script_stop. It stops short of explicitly contrasting itself with those operations, so it is clear but not fully differentiating.

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

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

It states the confirm:true prerequisite, which is real usage guidance, but never says when to delete versus other lifecycle operations (e.g. stop/eval) or whether the script must be stopped first. Usage is implied rather than explained.

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

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

Despite destructiveHint=true being annotated, the description adds meaningful context: the confirmation gate for arbitrary code, the 'stringified result' return shape, and that the operation is audit-logged. These go beyond the annotation and inform the agent about safety and side-effect visibility.

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

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

Two tight sentences with the core action and the confirm-gating rule front-loaded; nothing is wasted and the critical safety note is prominent.

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 elaborated, and the description covers the confirmation gate and logging. But with 0% parameter documentation and an undescribed device/id targeting scheme, the definition is not fully complete for a destructive 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 0% across 4 parameters, so the description carries the burden. It only clarifies the `confirm` flag (and implicitly `code` as an expression); the `device` and `id` parameters are left completely unexplained in both description and schema.

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

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

The description states a specific verb and resource ('Evaluate an expression inside a running script'), which distinguishes it from siblings like shelly_script_put_code or shelly_script_get_code. It is clear what the tool does, though it does not explicitly name the alternatives it is not.

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

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

It provides one actionable rule — arbitrary code requires ``confirm:true`` — which is genuinely useful. However, it gives no guidance on when to prefer this over shelly_rpc/shelly_rpc_write or other siblings, leaving selection context implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it transparently discloses that the device returns source in pages and this tool reassembles them into full source. It does not cover failure modes (invalid id, unreachable device), keeping 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?

A single tight sentence with the key mechanism front-loaded and no filler; every word 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?

Output schema exists, so return values needn't be explained, and the pagination note helps. However, with two entirely undocumented parameters, an agent still lacks enough to call the tool confidently (e.g., how to identify the device).

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 both required parameters. The description says nothing about what `device` (name? IP? ID?) or `id` (script slot number?) mean, so it fails to compensate for the undocumented schema.

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

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

States a specific verb (get), resource (a script's full source), and even the internal mechanism (reassembling the device's paginated GetCode). This clearly distinguishes it from sibling shelly_script_put_code (write) and shelly_script_list (enumeration).

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

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

The name and description imply the use case (fetching source of an existing script), but there is no explicit statement of when to choose this over shelly_script_list or shelly_script_eval, nor any prerequisite such as the script existing or needing auth.

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 readOnlyHint annotation already establishes this is a safe, non-mutating read. The description adds a genuine behavioral constraint with "Local-only" (no cloud/remote access), but says nothing about pagination, ordering, or failure modes when a device is unreachable or has no scripts. That is adequate but thin for the annotation coverage provided.

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 compact sentence plus a two-word constraint, fully front-loaded with the action, resource, and scope. Every fragment 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 the field list in the description is redundant but harmless, and return values are otherwise covered. The remaining gap is the undocumented "device" parameter and the lack of any note on how to identify a device, which matters given 0% schema coverage.

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

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

The single parameter "device" has 0% schema description coverage and is not described at all in the description, leaving the agent to guess whether it expects an IP, hostname, or device id. The listed return fields do not compensate for this gap in input semantics.

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

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

States a specific verb and resource ("List scripts on a device") and even enumerates the returned fields, which cleanly separates it from script siblings like shelly_script_get_code, shelly_script_create, and shelly_script_eval. It does not explicitly name which sibling to use instead, so it stops short of a 5.

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

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

There is no when-to-use or when-not-to-use guidance and no named alternative. "Local-only" is the only contextual hint, implying the device must be reachable on the local network, but this is a constraint rather than usage direction.

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

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

With only destructiveHint:true in annotations, the description carries the burden and delivers real behavioral context: confirm-gating for arbitrary code, append=false replacing the body, automatic ≤1 KB chunking, and audit logging. This tells the agent the operation is destructive, how it is chunked, and that it is recorded.

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

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

Front-loads the core action and the confirm warning, then covers append, chunking, and audit in minimal, zero-waste sentences. 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?

An output schema exists so return values need no explanation, and the destructive/confirm/chunking behavior is well covered for a mutation tool. The only shortfall is the unexplained id/device parameters, which is minor but not fully closed.

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%, so the description must compensate, and it explains append (false replaces, true appends) and confirm (needed for arbitrary code) meaningfully. But id, device, and code — including the required ones — are never clarified, leaving a real gap against 5 undocumented parameters.

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 ('Upload code into a script') with a distinct scope note ('chunked') that separates it from shelly_script_get_code and shelly_script_eval. An agent can identify it as the write counterpart to the read/eval script tools without opening the schema.

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

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

Gives a clear conditional: arbitrary code requires confirm:true, and append selects replace vs append behavior. However, it never names an alternative sibling (e.g. shelly_script_eval or shelly_script_create) or states when this tool is preferred over them, so routing guidance is context but not exhaustive.

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

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

With no annotations, the description carries the full burden, and it does disclose two useful traits: it returns ``was_running`` and the call is audit-logged. However, it omits whether starting an already-running script errors, permission requirements, and reversibility, leaving notable behavioral gaps for a mutation tool.

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

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

Three terse sentences, front-loaded with the action, then the return value, then the audit note. Every clause carries information; 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 exists, so return values need not be spelled out. Still, with 0% schema coverage the unexplained `device` parameter and the absence of error/idempotency behavior leave the definition only minimally adequate for a mutating 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 0% across two parameters. The phrase "by ``id``" hints that id identifies the target script, but the required `device` parameter is never explained, and there is no format or constraint detail for either param, so the description only partially compensates.

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 ("Start") and resource ("a script"), identified by id, so the action is unambiguous. It is implicitly distinct from shelly_script_stop, but it never names that sibling or any alternative, so it falls 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?

The description gives no when-to-use context, no prerequisites, and no routing to alternatives such as shelly_script_run vs shelly_script_eval. The agent must infer usage 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?

With no annotations, the description carries the full burden; it does disclose two useful traits (returns 'was_running', and the call is audit-logged). However it says nothing about authentication/permission requirements, idempotency, or what happens when the script is already stopped, which matters for a mutation tool.

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

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

Three terse sentences, front-loaded with the action and parameter, with no filler. The doubled backticks around identifiers are minor markup noise rather than wasted content.

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

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

An output schema exists, so explaining the return value is not strictly required, and the audit-log note is a genuine addition. Still, with zero annotation coverage and an undocumented required 'device' parameter, an agent lacks enough to invoke this confidently in a multi-device environment.

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 two required parameters, so the description must compensate. It explains 'id' only and leaves the equally required 'device' parameter completely undefined — no format, identifier scheme, or example.

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 ('Stop a script') and names the key parameter ('id'), which cleanly distinguishes it from the sibling shelly_script_start. It does not explicitly reference siblings, but the verb alone makes the role 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?

No when-to-use or when-not-to-use guidance, no mention of alternatives (e.g., shelly_script_delete for removal, shelly_script_start for the inverse), and no prerequisite such as whether the script must currently be running. Usage is only implied by 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?

Beyond the single idempotentHint annotation, the description discloses two useful traits: the post-action ChannelState is returned and the action is audit-logged. It does not state what happens on an unknown device/channel or error behavior, but the added context is real and consistent with idempotentHint=true.

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

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

Three short sentences, front-loaded with the core action and followed by return and audit facts. No padding or repetition; every sentence earns its place.

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

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

An output schema exists, so return values need not be spelled out. However, with 0% schema coverage and no annotations covering permissions or failure modes, the description leaves device identification, channel defaults, and error behavior undocumented.

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%, so the description must compensate. It maps meaning onto all four parameters semantically ('on or off' -> on, 'channel', 'after N seconds' -> toggle_after_s, 'a switch' -> device), but gives no syntax, defaults (channel default 0), or device-identifier format.

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: 'Turn a switch/relay channel on or off', and adds the auto-revert option. It is clear what the tool does, though it never explicitly contrasts itself with the very similarly named sibling shelly_switch_toggle.

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 guidance, no prerequisites, and no mention of alternatives such as shelly_switch_toggle (toggle) versus this tool's explicit set-to-state semantics. The agent must infer the distinction from the name alone.

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

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

With no annotations, the description carries the full behavioral burden and does add two useful facts: it returns the post-action ChannelState and the action is audit-logged. However, it omits auth/permission requirements, whether toggling is idempotent, and what happens if the device is unreachable — real gaps for a mutation tool.

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

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

Three short, front-loaded sentences with no filler; the action leads and the supplementary facts follow. Appropriately sized for a simple toggle operation.

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

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

An output schema exists, so return-value detail is largely redundant, and the audit-log note is welcome context. But with zero annotation coverage and zero schema description coverage, the missing parameter semantics and alternative guidance leave the definition thin for a 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 0%, so the description must explain both parameters. It only hints at the channel concept via 'switch/relay channel' and says nothing about the required 'device' parameter or the channel default of 0, leaving the required param undocumented.

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 (toggle) and resource (switch/relay channel), so the action is unambiguous. It does not explicitly contrast with the shelly_switch_set sibling, but the toggle-vs-set distinction is clear enough for an agent to pick correctly.

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 guidance and no mention of the obvious alternative shelly_switch_set. The agent must infer that 'toggle' means flip-current-state rather than set an explicit state, which is the key selection decision here.

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, so safety intent is covered. The description adds useful context beyond annotations: the confirm:true gate and that the action is audit-logged, which tells the agent about irreversibility and traceability.

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, front-loaded sentences with no filler; the action leads and the requirement follows. Every sentence earns its place, though it could pack slightly more into the same space.

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

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

An output schema exists, so return values need not be explained. However, with 0% parameter coverage and an opaque device/delay_ms, the description leaves meaningful gaps for a destructive 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 coverage is 0%, so the description must carry parameter meaning, but it only clarifies 'confirm'. It leaves 'device' (identifier format) and 'delay_ms' (delay before reboot) unexplained in both schema and description.

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

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

States a specific verb and resource ('Reboot a device'), making the action unambiguous and clearly distinct from the sibling read/write/config tools. It does not name siblings or scope, but no sibling performs a reboot, so differentiation is inherent.

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 and no named alternatives among the many system siblings. It states a prerequisite (confirm:true) but not the context that should drive 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 only carry destructiveHint=true, but the description adds material behavior the annotation does not: the password is write-only, never returned, redacted in the audit log, and must be at least 12 characters. These are exactly the operational facts an agent needs before mutating credentials.

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 lines with zero filler; the operation and its confirm gate are front-loaded, and the write-only caveat follows. Every sentence earns its place.

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

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

An output schema exists, so return values need no explanation, and the destructive annotation plus the write-only/redaction notes cover the safety picture. Minor gaps remain: no explanation of the 'device' identifier or of any side effects such as dropped sessions after rotation.

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%, so the description carries the full burden. It compensates well for two parameters (password ≥12 chars, confirm:true required) but says nothing about the required 'device' parameter's accepted form or identifier semantics, leaving a 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?

The description states a specific verb pair and resource ('Enable/rotate the device login password'), which is unambiguous and clearly distinct from sibling tools like shelly_rpc_write or shelly_system_reboot. 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?

It states a hard prerequisite ('Requires confirm:true'), which is useful gating information. However, it gives no guidance on when to prefer this over the generic shelly_rpc_write or shelly_rpc path, nor any warning about when not to rotate a password.

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 destructiveHint=true annotation already signals a risky operation, and the description usefully adds the safety gate ('Requires confirm:true') plus the channel enumeration. It still omits the practical consequences of a firmware flash — device reboot, downtime, irreversibility, or interruption risk — which is the context an agent most needs before invoking a destructive tool.

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

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

Two short front-loaded clauses with no filler; the mutation and its enum values appear first, followed by the safety precondition.

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 the confirm/channel semantics are covered. What is missing for a destructive firmware operation is the operational impact (reboot/downtime) and the meaning of the required device parameter.

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%, so the description must carry the load. It documents the channel enum values (stable|beta) and the confirm gate, which is genuinely useful, but the required `device` parameter is never explained (identifier format, multiple devices, etc.), leaving a 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 verb+resource ('Trigger a firmware update'), which is unambiguous and clearly distinct from read-oriented siblings like shelly_get_info or shelly_system_reboot. It does not, however, explicitly contrast itself with the nearby system-mutation siblings such as shelly_system_reboot or shelly_rpc_write.

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 guidance is given beyond the mechanical requirement of confirm:true; there is no statement about when to prefer this over shelly_rpc / shelly_rpc_write or the reboot tool, nor about prerequisites such as connectivity or device state.

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?

No annotations exist, so the description carries the behavioral burden, but this is a zero-parameter read-only version lookup with nothing destructive or stateful to disclose, and the presence of an output schema covers return values. The 'health check' note adds a small amount of context about intent.

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 short sentence, purpose front-loaded with the scope qualifier appended. No filler or restated information.

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

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

For a parameterless health-check tool with an output schema that already describes the returned version payload, the description supplies everything an agent needs to decide and call correctly.

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

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

The tool takes no parameters, so the baseline of 4 applies. Nothing to document beyond what the empty schema already shows.

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

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

States a specific verb (Return) and resource (shelly-mcp server version) with a parenthetical clarifying intent (health check). Among many get/list siblings, 'server version' is unambiguous and cannot be confused with shelly_get_info (device info) or shelly_get_status (device status).

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 '(health check)' label implies the scenario for calling it, but there is no explicit when-to-use or when-not guidance, nor any alternative tool named. For a trivial diagnostic tool this is adequate but not instructive.

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

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

Annotations only supply idempotentHint=true, so the description carries most of the behavioral burden. It does disclose two useful traits beyond the schema: the operation is audit-logged, and it returns the new component id. It does not explain what happens on an id collision, whether the component persists across reboots, or what config keys imply.

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 terse sentences with zero filler; the core action and its type values are front-loaded, and the return value and audit-logging notes are appropriately placed at the end.

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 details need not be spelled out, though the description helpfully mentions the returned id. For a mutating, audit-logged tool on a required 'device' target, the description still leaves the device argument and config semantics unaddressed relative to the 0% schema coverage.

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

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

Schema description coverage is 0%, so the description must compensate. It fully documents the 'type' values and gives a range for 'id', but 'config' is only named without any key-level meaning and 'device' — a required parameter — is never explained at all, leaving a notable 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 verb and resource ('Add a virtual component') and enumerates the valid component types (boolean/number/text/enum/button/group), which goes well beyond restating the name. It does not explicitly distinguish itself from siblings like shelly_virtual_delete or shelly_virtual_list, but the verb makes the direction of the operation unambiguous.

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

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

Usage is implied by the verb 'Add' and by the listed type values, and the 200-299 id range hints at how components should be numbered. However, there is no statement of when to use this versus shelly_virtual_list/shelly_virtual_delete, no note on device scoping, and no prerequisite guidance.

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

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

Annotations already declare destructiveHint=true, so the destructiveness is known. The description adds the meaningful safety gate (requires confirm:true), but doesn't say what cascades from deletion (dependent references, whether the key must exist) or describe the response, leaving gaps on a destructive mutation.

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 zero filler, front-loading the action and key format before the confirm requirement.

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, but for a destructive mutation with 0% schema coverage the description should also address the required ``device`` param and deletion effects. Adequate but incomplete.

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 0%, so the description must compensate. It documents the ``key`` format and the ``confirm`` requirement, but the required ``device`` parameter goes unexplained in both schema and description, so compensation is partial.

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

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

States a specific verb (delete) and resource (virtual component) and disambiguates the key format as ``<type>:<cid>``, which separates it from scene_delete/script_delete/kvs_delete siblings. It doesn't explicitly name which sibling to use instead, but the resource is precise enough to select it.

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 requirement ``confirm:true`` is a useful precondition for invocation, but there is no explicit when-to-use vs alternatives guidance (e.g., prefer disable over delete, or how it relates to shelly_virtual_add/list). Usage is implied rather than spelled out.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating call, so the description's main addition is naming the underlying RPC method (Shelly.GetComponents). It says nothing about return shape, pagination, or whether the device must be online, so value beyond annotations 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 tight, front-loaded sentence with no filler; the verb and scope lead. Slightly under-specified rather than bloated, which is the right side of the tradeoff.

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 read-only annotation covers safety. The unresolved gap is the device parameter's semantics and the lack of differentiation from shelly_list_components, which leaves the definition only minimally adequate.

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

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

The single 'device' parameter has 0% schema description coverage and the description does not explain its format, whether it is an ID or address, or how to obtain it. With 1 undocumented parameter, the description fails to compensate for the schema 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 verb (List) and resource (virtual/dynamic components), which implicitly separates it from the sibling shelly_list_components. However, it never explicitly says how it differs from that generic lister, leaving the distinction 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?

The description gives no when-to-use guidance, no indication of when to prefer shelly_list_components, and no prerequisites or context about what qualifies as a virtual component. The agent has to guess the routing.

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

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

Only idempotentHint is annotated, so the description carries most of the burden. It usefully discloses that the action is audit-logged and clarifies repeat_period semantics (seconds; 0=always, negative=once), which is real behavioral context. It still omits permissions requirements and what happens on duplicate creation.

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

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

Front-loaded with the core action, then terse parameter notes; no filler sentences. Compact and readable, though the inline backtick notation and trailing 'Audit-logged' fragment are slightly clipped.

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, which is handled correctly. However, for an 8-parameter tool with zero schema coverage, leaving device, name, and enable entirely undocumented (including the required device) is 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?

With 0% schema coverage, the description must compensate and does so for five of eight params: event (with an example), cid, urls (1-5 bound), condition (JS expression), and repeat_period (unit and special values). It adds genuine semantics the schema lacks, though device, name, and enable are left undocumented.

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

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

Opens with a specific verb+resource ('Create a webhook'), which clearly distinguishes it from the other webhook siblings (list/update/delete). It does not explicitly name alternatives, but the operation is unambiguous from the leading clause alone.

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

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

There is no explicit guidance on when to use this tool versus e.g. shelly_webhook_update or shelly_rpc_write, and no stated prerequisites. The closest thing to guidance is the parameter explanation, which is not usage scoping.

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

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

Annotations only declare destructiveHint=true; the description adds two behavioral facts beyond them: a mandatory confirmation gate (``confirm:true``) and that the action is audit-logged. It does not state whether deletion is reversible or what happens on confirm=false, but the added context 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?

Three short sentences, zero filler, with the action, the confirmation requirement, and the audit side effect all front-loaded. 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?

An output schema exists, so return values need not be described, and annotations already carry the destructive profile. Together with the confirm gate and audit-logging disclosure this is nearly complete, but the unexplained required ``device`` parameter and unstated reversibility keep it from being 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?

Schema description coverage is 0%, so the description must carry parameter meaning and only partially does: it explains ``id`` (the target webhook) and the ``confirm`` gate (must be true). The required ``device`` parameter is left entirely unexplained in both schema and description, which is a real gap for a 3-param tool.

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 (Delete) and resource (webhook) plus the addressing key (``id``), so an agent can immediately distinguish it from shelly_webhook_list/create/update. It does not explicitly name a sibling or scope constraint, but the verb+resource pair 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 states a concrete invocation prerequisite — ``confirm:true`` must be supplied — which tells the agent the call will not proceed without it. There is no explicit when-not guidance or mention of an alternative path (e.g., webhook_list to find an id), but the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds a real constraint not present in the schema or annotations — that the call is local-only (no cloud path) — which is valuable execution context, but it stops short of saying what happens if the device is unreachable or what the response contains.

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 core action stated first and the constraint appended. Nothing could be removed without losing content.

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

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

An output schema exists, so return values need no explanation, and the tool is simple (one param, read-only). However, the identifier format for `device` and the practical meaning of "local-only" (LAN reachability, failure mode) are left unstated for an otherwise trivial 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 0% for the single required `device` parameter, and the description does not clarify whether it expects a device ID, name, or IP. The phrase "on a device" does little more than restate the parameter name, leaving the main invocation detail ambiguous.

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?

A specific verb+resource ("List webhooks configured on a device") that clearly contrasts with the create/update/delete webhook siblings without naming them. The distinguishing read-vs-write intent is obvious from the verb, though no sibling is explicitly named.

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?

"Local-only" implicitly tells the agent this only works when running against a device on the local network, but there is no explicit when-to-use guidance or mention of alternatives like querying config. Usage 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?

Only idempotentHint is annotated, so the description carries most of the behavioral burden; it usefully discloses that updates are audit-logged and that only supplied fields change ('update fields'). It omits permission requirements, whether omitted fields remain untouched (partial vs full replace), and any rate limits or side effects.

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 operation and identifier, with no filler. 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 described. Still, for a 7-parameter mutation with 0% schema coverage and minimal annotations, the description should say more about how the optional fields behave; the added 'audit-logged' note partially compensates.

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 7 parameters, yet the description names only 'id' and the abstract notion of 'fields'. The meanings of name, urls, device, enable, condition, and repeat_period are left entirely to the reader, which is a significant gap for a mutation tool.

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 ('Update fields of an existing webhook by id'), so the operation is unambiguous. However, it does not distinguish itself from the sibling tools shelly_webhook_create and shelly_webhook_delete, leaving the agent to infer the boundary from names alone.

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 guidance on when to choose this over shelly_webhook_create, shelly_webhook_delete, or shelly_rpc_write, nor any note about prerequisites or when not to use it. The 'by id' phrase implies the webhook must already exist, but that is the only inferred constraint.

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