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

With no annotations, the description carries the full behavioral burden. 'Activate' implies a state-mutating operation affecting lights, but the description never states the side effects, whether it overrides current settings, permission requirements, or reversibility. The useful behavioral context (fade timing, sunset dimming) lives in the schema, not the description.

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

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

A single front-loaded sentence with zero filler. It is efficient, though its brevity reflects under-specification rather than disciplined concision.

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 state-mutating tool with no annotations and no stated side effects, one sentence is insufficient. An output schema exists so return values need not be explained, but the description omits essential behavioral context an agent needs (what activation changes, interaction with current light state).

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 75%, so three of four parameters are already documented in the schema (room disambiguation, dynamic color cycling, transition_seconds fading). The description adds nothing beyond the generic 'saved scene', so the baseline of 3 applies.

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

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

The description states a clear verb ('Activate') and resource ('saved scene'), which implicitly distinguishes it from the sibling create_scene (the scene must already exist). However, it does not explicitly name alternatives or contrast with set_lights/set_effect, 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?

There is no explicit guidance on when to use this tool versus create_scene, set_effect, or set_lights. The word 'saved' weakly implies the scene must already exist, but no conditions, prerequisites, or alternatives 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether cancellation is immediate, whether it is idempotent, what happens if the timer already fired or the ID is invalid, or what the response contains. For a state-mutating tool, this is a notable gap.

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 short sentence with zero filler, and the action is front-loaded. It is efficient, though the brevity leans toward under-specification rather than disciplined conciseness.

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

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

An output schema exists, so return values need not be described, but with no annotations and an undocumented required parameter, the definition should disclose mutation semantics and failure behavior. As written it leaves the agent without enough context 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?

There is a single parameter with 0% schema description coverage, so the description must compensate. It partially does by indicating the timer_id originates from list_timers, but adds no format or type detail beyond the schema's string type.

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 (cancel) and resource (timer), and implicitly separates itself from the read-oriented list_timers and the create/modify-oriented set_timer in the sibling set. It does not explicitly name an alternative to use instead, but the action 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?

"from list_timers" implies the prerequisite that the timer_id must first be obtained via list_timers, which is useful implied guidance. However, there is no explicit statement of when to cancel versus modify a timer with set_timer, nor any error/exclusion conditions.

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 are provided, so the description carries the full behavioral burden. It does disclose that the current look is captured, but says nothing about whether an existing scene with the same name is overwritten, what permissions are required, or whether creating a scene affects the live lights. For a mutation tool with zero annotation coverage this is a real gap.

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

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

A single front-loaded sentence with no filler; the verb and the resulting resource are the first things the reader sees.

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 two-parameter surface is small. However, for a write/create tool with no annotations, the description omits conflict/overwrite behavior and permissions, leaving the agent short of what it needs to call it safely.

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

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

Schema description coverage is 50%: 'room' is documented in the schema, while 'name' has only type/length constraints. The description adds marginal meaning by clarifying that the room/zone's lights are the source and that the result is a new scene, but adds no format or constraint detail beyond the schema.

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

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

The description states a specific verb+resource ('Save ... as a new scene') and clarifies scope ('a room or zone's lights'). It implicitly distinguishes itself from the sibling activate_scene (which applies an existing scene rather than creating one), but never names or contrasts with that sibling explicitly.

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

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

There is no when-to-use guidance, no mention of alternatives like activate_scene, and no stated prerequisites. The agent must infer that this is the creation counterpart to activation from the wording alone.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds useful context about the breadth of the read (whole-home structure plus current light state and scenes), but says nothing about freshness, size, or performance implications of an unfiltered call.

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

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

A single tight sentence with no padding, and the resource scope is front-loaded. It loses a point only because the sentence fragment omits an explicit verb, which would have made the action unmistakable.

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

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

For a zero-required-argument read tool with a full output schema, the description need not explain return values, and it still summarizes what is included in the payload. It is sufficient to call the tool correctly, with the only real gap being absent usage 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 100% and the single optional 'room' parameter is documented in the schema as 'Only this room or zone.' The description's phrase 'Rooms and zones' loosely echoes that scoping but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description is a noun phrase rather than a verb+resource statement, but it clearly enumerates what is retrieved: rooms and zones together with their lights' current state and their scenes. It stands apart from the sibling set (set_lights, set_power, activate_scene, etc.), which are all actions, though it never explicitly says it is a read/retrieval.

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. The description does not state whether it should be called to bootstrap state before issuing set_* commands, nor does it name any alternative (there is no sibling read tool, but the agent is left to infer that).

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, covering the safety profile. The description contributes the meaningful constraint that only unfired timers are returned, but says nothing about ordering, count limits, or timing semantics – useful but modest added context.

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

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

A single, tightly scoped sentence with no waste. The scoping qualifier ('haven't fired yet') is front-loaded and does real work, though it is clipped to the point of omitting an explicit verb.

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 no-parameter signature keeps the surface small. For such a simple read tool with annotation coverage, the description is adequate, missing only explicit routing guidance.

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 the schema carries no semantic burden the description needs to compensate for. Baseline 4 applies with no parameter gaps.

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 identifies the resource (timers) and narrows it precisely: those created by set_timer that are still pending. It implicitly conveys the list/read operation and distinguishes itself from cancel_timer or a general timer view, though the verb itself must be inferred from the name.

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 implies the context of checking pending timers, but gives no explicit when-to-use guidance and names no alternative (e.g., cancel_timer or get_home). The agent must infer usage from the scope statement 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 burden and does meaningful work: it discloses that ten effects loop until stopped, that sunrise/sunset ramp over duration_minutes, and that unsupported lights are silently skipped. It still omits whether effects persist across restarts or require specific permissions, but the operational behavior is well covered.

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 and stop condition, then the effect taxonomy. The run-on list of looping effects is a bit dense but every clause conveys non-obvious behavior; no filler sentences.

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. For a 5-parameter tool with no annotations, the description covers effect behavior, stopping, and unsupported-light handling adequately; only permissions and persistence are unaddressed.

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

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

Schema coverage is 80% and already documents speed's range and duration_minutes' requirement, so the baseline would be 3. The description adds genuine meaning beyond the schema by classifying which enum values loop (candle, fire, ... enchant) versus ramp (sunrise, sunset) and by giving the semantic meaning of "none" as the stop command.

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: start a light effect, or stop effects with "none". It enumerates the effect vocabulary and distinguishes the two behavior families (looping vs. gradual), so an agent can tell it apart from set_lights, set_power, and activate_scene 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 description implies when to use it via the effect list and the parenthetical use cases ("wake-up light, falling asleep"), and it clarifies that "none" is the stop mechanism. However, it never says when to prefer this over set_lights, set_power, or activate_scene, nor any prerequisites, so 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?

With no annotations, the description carries the full burden. It does disclose one important behavioral trait beyond the schema: supplying brightness/color/white tone implicitly turns the lights on. It omits other relevant behavior such as what happens with conflicting color parameters, partial failure across a multi-light target, or permission requirements.

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 waste, with the core capability front-loaded and the non-obvious implicit-on behavior placed second. Nothing is padded or repeated.

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

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

An output schema exists, so return values need not be explained, and the schema covers most parameters. For an 8-parameter mutation tool with no annotations, however, the description leaves real gaps: no guidance on argument combinations, multi-target semantics, or error behavior.

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

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

Schema description coverage is 88%, so the schema already documents target, brightness range, color hex conversion and transition limits. The description only restates the implicit-on rule for brightness/color, adding little semantics beyond what the structured fields already provide; baseline 3 applies.

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

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

Specific verb+resource: it turns lights on/off and changes brightness, color or white tone, which distinguishes it from scene/timer/effect siblings. It does not, however, differentiate itself from the sibling set_power, which plausibly overlaps with the on/off portion of this 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?

The description never says when to prefer set_lights over set_power, set_effect or activate_scene, nor does it state prerequisites (e.g. target must exist). The second sentence describes a side effect rather than selection guidance, so usage must be inferred 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 present, the description carries the full burden, and it does disclose genuine behavioral traits: every light in the target is set to the same brightness and existing colors/white tones are preserved. It still omits permissions, error/rejection behavior, and whether the value is a hard cap or merely approximate ("about this many watts" stays vague).

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?

Short and front-loaded, with the watts example leading and the side-effect note following. The phrasing "about this many watts" and the two-line break add minor slack but nothing is wasted.

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

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

An output schema exists, so return values need no explanation, and the description covers the key side effects. For a 4-parameter mutation tool with no annotations, more on permissions and on how this differs from brightness-setting siblings would complete it.

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

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

Schema description coverage is 100%, so the schema already documents watts, target, target_type, and transition_seconds. The description restates watts as a total for the target and adds that uniformity applies across the target's lights, but contributes no syntax, range, or format detail beyond the schema.

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

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

States a specific verb and resource: set a target's total power draw in watts, with a concrete example. It is clearly distinguishable from a brightness-oriented sibling like set_lights, but it never names an alternative, 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 phrase "e.g. use 20 watts" implies when this tool applies (you want to cap/express a target's draw in watts), but there is no explicit when-to-use vs when-not, and no routing to set_lights, set_effect, or activate_scene. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full burden and does disclose a genuinely important behavioral trait: the timer runs on the bridge and fires even after the conversation ends. It stops short of stating that the timer fires once, or how it relates to cancel_timer, which would complete the picture.

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 a concrete example followed by the persistence caveat. No filler, though the second sentence could be tightened slightly.

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

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

An output schema exists so return values need no explanation, and the description covers the key non-obvious behavior of bridge-side persistence. It leaves gaps on interaction with cancel_timer/list_timers and whether the timer is one-shot, but is largely sufficient for correct invocation.

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

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

Schema coverage is 75%: target, action, and target_type are documented in the schema, and minutes carries explicit bounds. The description only echoes 'bedroom' and 'off' through its example, adding no format or syntax detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description conveys the core function through a concrete example ('turn the bedroom off in 30 minutes') — scheduling a device action after a delay. It is clear but never names the operation type or distinguishes itself from timer siblings like list_timers and cancel_timer.

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 through the example; there is no explicit when-to-use guidance or mention of alternatives such as cancel_timer or list_timers for managing the created timer. The agent must infer from the example when this tool applies.

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