Set a Homey device capability

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

Goes far beyond the annotations (readOnlyHint:false, destructiveHint:true, idempotentHint:true) by disclosing the percentage vs. fraction trap for specific capabilities, the clamping behavior with reporting, and the physical impact of the operation. This enriches the agent's understanding of side effects well beyond what structured fields convey.

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

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

Approximately 100 words arranged in front-loaded fashion, leading with the core purpose and following with important caveats. Each sentence carries distinct weight — physical impact, unit warnings, clamping, and preconditions — though the collection of caveats could arguably be tightened.

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?

Comprehensively covers purpose, safety, input semantics, and preconditions for a mutating tool without an output schema. It addresses a complex real-world domain (Homey device capabilities) well, though it leaves the exact return value on success implied rather than explicit.

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

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

Schema coverage is 100%, meeting the baseline of 3. The description meaningfully elevates this by documenting the crucial value-format gotcha (dim takes 0.6 not 60) that the schema's generic 'number/boolean/string' type union cannot express. Though it misses a complete return-value contract, it adds significant value for the trickiest parameter.

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

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

The description uses a precise verb+resource structure: 'Changes one capability of one device', providing concrete examples (onoff, dim, target_temperature). This unambiguously distinguishes the tool from siblings like homey_device_get (read) and homey_variable_set (variables), making its purpose immediately clear.

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

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

Explicitly names an alternative tool and the condition for its use: 'Call homey_device_get first when unsure of a range or of which capabilities can be set.' It also warns about physical consequences, implicitly covering when-not-to-use by advising caution. This is exemplary usage guidance.

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