deConz MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.2.1
Disambiguation4/5
Tools are mostly organized by resource and action, so purposes are generally clear. A few overlaps exist: set_group_action can recall a scene via its scene parameter, duplicating recall_scene, and create_scene versus store_scene both capture current group state.
Naming Consistency4/5
The naming mostly follows a predictable list_/get_/create_/set_/rename_/delete_ pattern across resource types. Minor deviations like modify_group, store_scene, and recall_scene break the strict verb_noun convention but remain readable.
Tool Count2/5
39 tools is a large surface and exceeds the 25+ threshold. The set could be consolidated into generic state/action endpoints or grouped more tightly without losing capability, though the organization by resource does provide some structure.
Completeness4/5
The set covers most lifecycle operations for lights, groups, sensors, scenes, rules, schedules, and touchlink discovery. Obvious gaps are limited to gateway configuration updates and some sensor/device creation paths, but common workflows can be completed.
Average 3.8/5 across 39 of 39 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 5 commits in the last 12 weeks
- Last stable release on September 3, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of explaining behavior, but it only says 'Rename a scene.' and provides basic arg hints. It does not disclose whether the rename is persistent, whether it affects group references, what side effects occur, or what kind of response should be expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the operation, followed by a compact, readable Args block. There is no fluff or redundant prose, and the format is easy for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple rename operation with an output schema available, the description is minimally sufficient to identify the operation and the required parameters. However, it lacks usage guidance, behavioral context, and any differentiation from sibling rename tools, so it is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions, so the Args block is the only semantic source. It does add some value: 'Numeric group ID' and 'New display name' clarify two parameters, though 'Scene ID to rename' is largely a repetition of the parameter name. The 'Numeric group ID' phrasing also sits awkwardly with the schema's string type for group_id, which the agent must reconcile.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Rename a scene.', which is essentially a direct restatement of the tool name and carries no additional explanatory value. It does not describe the role of the group or scene, and it does not distinguish this from sibling tools like rename_light or rename_sensor beyond the resource name itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool, what conditions or prerequisites apply, or which alternatives might be more appropriate. The sibling list includes several other rename and scene-related tools, but the description does not reference them or exclude any cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does state the core effect—capturing current group light states—but omits side effects, whether an existing scene is overwritten, persistence behavior, permission requirements, or error handling. For a mutating creation operation, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: one clear purpose sentence followed by a compact argument list. There is no filler or redundant content; every sentence contributes to understanding the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and has an output schema, but the description still leaves key gaps: no clarity on when to use create_scene versus store_scene, no side-effect disclosure, and a contradictory parameter type. These gaps make it hard for an agent to select and invoke the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does add some meaning: name is a display name and group_id is described as numeric. However, the claim that group_id is numeric conflicts with the schema type string, creating ambiguity. No format, examples, or range details are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Create') and resource ('scene'), and it adds meaningful scope: the scene captures the current state of all lights in the group. It is distinguishable from most siblings, though it does not explicitly differentiate from store_scene, which may serve a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the tool is for snapshotting current light states into a new scene, but it provides no explicit guidance about when to choose this over store_scene, rename_scene, or recall_scene. No exclusions, prerequisites, or alternative routing are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only states the action and arguments; it does not mention whether deletion is permanent or reversible, whether related rules or schedules are affected, or what the response contains. For a destructive tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the action. The Args block is terse and free of filler. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists, the description still lacks usage guidance and behavioral context. For a destructive two-parameter tool, it does not explain permanence, side effects, error conditions, or how the operation relates to groups and other scene tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the Args block is the only semantic source. It names both required parameters and adds 'Numeric' to group_id, but the descriptions are thin and largely reuse obvious identifier names without explaining formats, sources, or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action and resource: 'Delete a scene.' It is unambiguous and distinguishable from sibling tools like recall_scene or create_scene. However, it does not elaborate on what deleting a scene entails or how it relates to groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use delete_scene versus alternatives, no prerequisites, and no exclusions. An agent gets no decision support beyond the obvious implication that it should be used when a scene needs to be deleted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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, but it only restates the action. It does not mention irreversibility, side effects on active schedules, or any confirmation/error behavior. The destructive nature is inferred from the verb rather than explicitly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with no filler, and the parameter is documented in a standard Args block. It earns a high score for brevity, though the terseness contributes to missing behavioral context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter delete operation with an output schema present, the description is minimally adequate: it names the resource and the required identifier. It is not fully complete because it omits behavioral consequences, where to obtain the ID, and any guidance on alternative related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds one semantic detail: schedule_id is a 'Numeric schedule ID to delete,' which is useful given the schema only provides the title 'Schedule Id.' However, it is terse and slightly ambiguous because the schema types the parameter as a string while the description says 'Numeric.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Delete a schedule.' It distinguishes itself from sibling schedule tools through the resource name, though it closely mirrors the tool name and adds no scope or uniqueness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like set_schedule_status or delete_light, nor any mention of prerequisites such as retrieving the schedule ID via list_schedules. Usage context is only implied by the verb 'Delete.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for disclosing behavior. It only says 'enable or disable' and does not mention side effects, persistence, permissions, idempotency, or what happens to an already enabled/disabled schedule.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a front-loaded purpose sentence followed by a minimal Args block. Every sentence earns its place and there is no redundant or promotional language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of an output schema covers return-value expectations, but for a mutating tool with no annotations the description omits behavioral context such as side effects or requirements. The schedule_id type mismatch also leaves a correctness gap, making the definition adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions, so the text must compensate. It usefully enumerates status values 'enabled' or 'disabled', but then describes schedule_id as 'Numeric' while the schema types it as a string, leaving ambiguity about whether the agent should pass an integer or a numeric string.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Enable or disable a schedule.' This clearly conveys the operation and distinguishes it from schedule creation, deletion, or retrieval sibling tools, though it does not explicitly contrast it with set_rule_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: an agent should call this when it needs to enable or disable a schedule. However, the description does not state when to prefer this over create_schedule, delete_schedule, or set_rule_status, so guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden of behavioral disclosure. It only says 'Get details', implying read-only behavior, but never explicitly states that the operation has no side effects, what happens for missing IDs, or any permissions/rate-limit constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise and front-loaded with the purpose. The Args section is structured and every line adds information; there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema covers the return type, so not describing return values is acceptable, and the two required parameters are both documented. However, the description omits usage context and behavioral caveats, and it does not mention how group_id should be discovered (only scene_id), leaving minor gaps for an agent to fill.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides bare string parameters with 0% description coverage, so the Args block adds real value: 'Numeric group ID' clarifies the expected format, and 'use list_scenes to discover IDs' gives the agent a concrete discovery path for scene_id. This compensates for the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Get details of a specific scene.' It distinguishes this read operation from scene mutation/listing siblings like create_scene, recall_scene, and list_scenes, though it does not name any alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to choose this tool over alternatives. The only workflow hint is 'use list_scenes to discover IDs', which addresses acquiring the scene_id but does not explain when get_scene is appropriate or when another sibling should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing side effects. 'Rename a sensor' implies a write operation, but it does not state that the change is persistent, whether the original sensor ID remains stable, or any permission/ownership requirements. The Args add limited semantic detail but no broader behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: a clear one-line purpose followed by two concise parameter explanations. Every line earns its place, and there is no redundant filler or unnecessary abstraction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation with an output schema present, the description covers the core action and parameter semantics. However, it leaves out context such as whether the rename affects resource references, how errors are reported, and whether the operation is idempotent. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for the bare schema, and it does. It clarifies that sensor_id is 'Numeric sensor ID' even though the JSON schema types it as a string, and that name is the 'New display name.' This adds meaning beyond the parameter names and types, though it omits constraints like maximum length or uniqueness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action, 'Rename a sensor,' identifying the verb and resource class. The Args list further clarifies that the tool takes a sensor ID and a new display name. It doesn't explicitly distinguish from sibling rename tools, but the resource 'sensor' is enough to differentiate from rename_light and rename_scene.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like set_sensor_config or delete_sensor. The imperative 'Rename' implies the obvious use case, but there are no prerequisites, exclusions, or mention of what to do if the sensor already has a name or is referenced elsewhere.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only says the light is removed, but does not state whether removal is permanent, whether it unpairs the physical device, whether associated groups/scenes are affected, or what happens if the light_id does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core purpose, and contains no filler. The single argument is documented in a compact, readable format, which is appropriate for a one-parameter delete operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core operation and the only parameter are covered, and an output schema exists, so return-value documentation is not necessary. However, for a destructive mutation tool with no annotations, the absence of side-effect or irreversibility information leaves the description minimally viable rather than fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds some meaning beyond the bare schema by saying the parameter is a 'Numeric light ID to remove,' which compensates for the 0% schema description coverage. However, the schema declares light_id as a string, creating a potential mismatch with 'Numeric,' and the description does not explain where the ID comes from or its expected format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Remove a light') and a specific resource ('from the gateway'), making the tool's purpose immediately obvious. It is distinct from siblings like get_light, set_light_state, and rename_light, and the resource 'light' differentiates it from delete_group or delete_sensor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It does not mention, for example, that this should not be used if only unpairing a sensor, or that the light must first be obtained via list_lights.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It usefully discloses that light_ids is a 'Complete new list', signaling replacement semantics. However, it does not clarify how null values behave (e.g., whether null means 'leave unchanged' or 'clear'), nor does it mention permissions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the purpose, and the Args block is compact with no filler. Every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and all parameters, and an output schema exists to document returns. However, it lacks null-value semantics and usage guidance relative to sibling tools, so it is not fully self-sufficient for an agent deciding between modify_group and set_group_action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates by documenting all three parameters in the Args block. The 'Complete new list of light IDs' detail adds important semantics beyond the bare schema, though null behavior is still underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's actions: 'Rename a group or change its member lights.' This identifies the resource (group) and distinguishes it from lifecycle tools like create_group/delete_group, though it does not explicitly differentiate it from set_group_action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when renaming or changing group membership) but provides no explicit when/when-not guidance or alternatives. It does not mention prerequisites or how this differs from set_group_action or create_group.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only restates the action implied by the tool name. It does not disclose permanence, side effects on automation functionality, or what happens when the rule is deleted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately short and front-loaded: one clear purpose sentence followed by a focused parameter note. There is no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter delete operation with an output schema, the description covers the basic action and parameter. However, it omits usage guidance and does not disclose destructive implications or alternatives like set_rule_status, leaving some gaps for an agent deciding how to fulfill a request.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema itself provides no parameter description, so this description compensates by calling rule_id a 'Numeric rule ID to delete.' This adds meaning beyond the bare schema type of string, though the 'numeric' wording may slightly conflict with the string type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Delete an automation rule.' This distinguishes it from siblings like get_rule, create_rule, and set_rule_status, and from other delete tools by specifying the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given for when to delete a rule versus disabling it with set_rule_status or modifying it with modify_group/set_group_action. The description implies only that this tool is for deleting automation rules, but it does not explain preconditions, exclusions, or alternative use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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. 'Remove' implies a destructive action, but the description does not state whether the action is reversible, whether it affects associated rules or schedules, or whether confirmation is needed, leaving the agent with limited understanding of consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely compact: one clear introductory sentence and an Args list with a single parameter. Every word earns its place, and the core purpose is front-loaded before the parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter deletion tool, the description provides the minimal viable information: what action is performed and which parameter is required. However, with no annotations and no mention of side effects, irreversibility, or prerequisites, it stops short of being fully complete for an agent deciding whether deletion is safe and appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 does so by identifying the parameter ('sensor_id') and clarifying that it is a numeric ID, which is useful though the schema declares it as a string. The explanation is concise and directly tied to the parameter, though it could have explained how to discover valid IDs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'Remove' and the resource 'sensor', and adds the scope 'from the gateway'. This distinguishes it from other delete operations (delete_light, delete_group, delete_scene, etc.) and from non-destructive sensor tools like list_sensors, get_sensor, and rename_sensor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as rename_sensor, set_sensor_config, or even delete_light. There is no mention of contexts where deletion is appropriate, prerequisites, or what happens to related sensor data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burde of behavioral disclosure. It does clearly say that the effect is transitioning all lights in the group to the saved state. However, it does not mention whether this is a mutating/irreversible action, whether it is idempotent, what happens if the scene or group does not exist, or whether any response is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured. The main action and effect are front-loaded, followed by a clean Args section. No sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter action, the core purpose and parameter roles are present, and an output schema exists so return-value detail is not required. However, with no annotations and no usage guidance, the description leaves gaps around side effects, error conditions, and how to obtain valid scene IDs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does define both params: group_id as a 'Numeric group ID' and scene_id as 'Scene ID to activate.' This adds some meaning, but 'Numeric group ID' is ambiguous because the schema declares group_id as a string, and 'Scene ID to activate' is near-tautological.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Activate (recall)') and resource ('scene'), and explains the resulting behavior: 'all lights in the group transition to the saved state.' This clearly distinguishes it from sibling tools like list_scenes, get_scene, or create_scene, which are about scene management rather than activation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives such as set_group_action or get_scene. It does not mention any prerequisites, such as looking up the scene_id via list_scenes, or situations where this tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral disclosure burden. It only states the mutation and parameter constraints but does not mention potential side effects, failure behavior, idempotency, or whether the light must exist before renaming.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded with the core action in the first sentence. The parameter list is direct and each line delivers useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter rename tool, the core information is present, and an output schema exists so return values need not be explained. However, the lack of annotation coverage and absence of any guidance about prerequisites, side effects, or failure modes leaves the description minimally viable but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no per-property descriptions, so the description's 'Args' section is the sole source of parameter meaning. It correctly identifies light_id as a numeric ID and name as the display name with a 32-character maximum, adding real value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource, 'Rename a light,' which clearly identifies the tool's function and distinguishes it from sibling rename tools like rename_sensor and rename_scene. The additional parameter documentation reinforces the purpose without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. The usage context is only implied by the tool name and simplistic description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does add useful context such as 'admin override' for reachable and battery, the CLIP sensor limitation for battery, and 'where supported' for sensitivity. However, it does not explain side effects of enabling/disabling a sensor, permission requirements, or whether the operation is idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: a one-sentence summary followed by a clean Args list. Every line adds value, and there is no filler or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the parameters well and an output schema exists, so return values do not need explanation. Still, it omits usage context, admin/permission guidance, and what happens when optional parameters are left null or unsupported. It is adequate but not fully self-sufficient for an agent deciding when and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
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 thoroughly. It explains all five parameters in plain terms: sensor_id as numeric ID, on as enable/disable, reachable as admin override, battery with a 0–100 range and CLIP-sensor caveat, and sensitivity as motion sensitivity. This adds meaningful domain semantics beyond the raw schema types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly opens with 'Update a sensor's configuration,' identifying the action and resource. The Args list details which aspects of configuration can be changed, distinguishing it from read/rename/delete sensor siblings. However, it does not explicitly differentiate itself from sibling tools by name, 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives like get_sensor, rename_sensor, or delete_sensor. There are no stated prerequisites, exclusions, or admin authorization requirements, even though some parameters are labeled as admin overrides. Usage is only implied by the verb 'Update' rather than explicitly instructed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. 'Get full details' implies a read-only operation, and no side effects or mutations are mentioned. This is adequate for a simple getter, though error cases, authentication needs, or response shape details are not disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The main purpose is front-loaded, and the parameter note follows directly without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read operation with an output schema, the description covers the argument, how to discover it, and what kind of data will be returned. The only notable gap is the lack of explicit guidance distinguishing it from list_schedules, but the tool is still fully invocable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides zero description coverage, but the description compensates by explaining schedule_id as a 'Numeric schedule ID' and pointing to list_schedules for discovery. This gives meaningful guidance beyond the schema's bare string type, though exact format or constraints are not specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get'), the resource ('schedule'), and the kind of content returned ('full details ... command and timing'). It does not explicitly differentiate from sibling getters like get_rule, but the resource and content are unambiguous enough for an agent 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives one useful prerequisite: 'use list_schedules to discover IDs.' However, it does not explicitly state when to prefer get_schedule over list_schedules or other sibling tools, leaving the usage decision largely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only indicates a read operation and does not address side effects, prerequisites, or behavior when no scan results are available, such as returning an empty list or error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. Every word contributes to the core function, making the description extremely concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema likely covers return-value structure, so that burden is reduced. However, the description omits important contextual details: that a Touchlink scan must have been run previously and what happens if none has. For a zero-parameter, annotation-free tool, this is a clear but non-fatal gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is trivially 100% covered. Per the zero-parameter baseline, the description does not need to add parameter semantics, and none are expected.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return') and resource ('results from the last Touchlink scan'). It clearly distinguishes the tool from siblings like touchlink_scan by focusing on retrieval of existing results rather than initiating a scan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'from the last Touchlink scan' implies the tool should be used after a scan has been performed, but it does not explicitly say 'call touchlink_scan first' or describe what happens before any scan exists. No alternatives or exclusions are mentioned, so usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral transparency burden. It does add some behavioral detail, such as 'brightness only when on=true', the default transition time of 0.4s, and the exact behavior of alert modes. However, it omits broader behavioral context like state persistence, what happens if the light is unreachable, or how conflicting color parameters 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description opens with a concise one-sentence purpose and then uses an organized Args list to pack in the necessary parameter detail. There is no fluff, and the structure makes it easy to scan and extract exactly what each parameter needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 10 parameters and an output schema that already covers return values, the description is mostly complete. It spells out ranges, defaults, and units for all parameters, but it lacks information about interactions between parameters (e.g., precedence when multiple color modes are provided) and whether color/effect settings apply when on=false. This prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by documenting every parameter with ranges, units, defaults, and allowed values: brightness 1-254, hue 0-65535, saturation 0-254, color_temp mireds 153-500 with cooler/lower relation, xy coordinates, transition_time in tenths of a second, and alert/effect enums. The only minor ambiguity is calling light_id 'Numeric' while the schema types it as a string, but the intent remains clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Control' and names the resource ('a light's power, brightness, colour, or effect'), making the tool's purpose clear. It is easy to tell apart from 'get_light' and group-level tools, though it does not explicitly name any alternative or contrast itself with 'set_group_action', 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as 'set_group_action' or 'get_light'. The description provides parameter documentation but no context about when this is the right choice, when it should not be used, or what preconditions apply.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does make the mutating nature clear and specifies the allowed status values, but it does not disclose whether enabling an already-enabled rule is idempotent, what happens if the rule does not exist, any permissions required, or how the change affects rule evaluation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: the purpose is front-loaded, and the argument list adds only necessary details with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation, the core invocation details are present and an output schema exists, so return-value documentation is unnecessary. However, the lack of annotations, usage guidance, and behavioral caveats leaves the agent with only the bare mechanics and no broader operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no parameter descriptions and no enums, so the description compensates by identifying rule_id as numeric and listing the exact accepted status values 'enabled' or 'disabled'. This is essential and useful, though case sensitivity or ID format details are not included.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Enable or disable an automation rule,' which is a specific verb, resource, and effect. It clearly distinguishes this from sibling tools like create_rule, delete_rule, and get_rule by focusing on status mutation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to toggle an existing rule's status, but gives no explicit when-to-use or when-not-to-use guidance and names no alternatives. An agent can infer the use case, but nothing is stated directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry behavioral disclosure. It does state the observable effect (the device blinks), but it does not mention whether the command is safe, whether the device must be in physical proximity, what failures may occur, or what the output represents beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one clear sentence explains the tool's action, followed by a minimal parameter note. Every word earns its place with no repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has a single required parameter, and has an output schema, so the description does not need to explain return values. The missing guidance about when to use touchlink_identify versus touchlink_reset or scan is a minor gap, but overall the description is adequate for a focused tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% parameter description coverage, but the description compensates by explaining that touchlink_id is the 'Device ID from get_touchlink_results.' This gives useful provenance for the parameter even though it does not describe the exact format or constraints of the ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Make a Touchlink device blink to identify itself.' This distinguishes it from the other touchlink sibling tools (scan, reset, get_results) by its observable outcome, though it does not explicitly contrast itself with those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying that touchlink_id should come from get_touchlink_results, indicating this runs after a scan/results step. However, it does not explicitly say when to use this tool versus the other touchlink operations or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 states that lights are controlled simultaneously, but it does not disclose side effects, prerequisites such as the group existing, whether unspecified parameters are left unchanged, permission requirements, or how invalid combinations of color parameters behave.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description opens with a one-sentence purpose and then provides a tight, well-organized Args list. All 11 parameters are covered without redundant prose or filler, and the structure makes the parameter semantics easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The parameter documentation is thorough and an output schema exists, so return values do not need explanation. However, the description omits important operational context: it does not state that at least one state parameter is typically needed beyond group_id, nor does it explain mutual exclusivity or fallback behavior when combining color fields, transition details, or scene recall.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage and no enums, but the description fully compensates: every parameter is explained with ranges, units, types, or allowed values. Examples include brightness 1–254, hue 0–65535, color_temp in mireds 153–500, transition_time in tenths of a second, and alert/effect enum values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: "Control all lights in a group simultaneously." This clearly distinguishes the tool from siblings like set_light_state, which targets individual lights, and from group-management tools like create_group or modify_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase "all lights in a group simultaneously" implies the intended use case, but the description never explicitly states when to prefer this over set_light_state or other sibling tools. There are no exclusions or alternative routing cues, so usage guidance is only implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral transparency burden. It only states that a new group is created and describes arguments; it does not disclose side effects, whether the operation is destructive, permission requirements, or behavior on name conflicts. For a mutation tool, this is a meaningful gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core action, and uses a clean Args block. Every sentence adds value with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with only two parameters, the description covers the essential purpose and argument semantics completely. An output schema is present, so return value details are not the description's responsibility. Minor gaps are the lack of usage alternatives and behavioral caveats, but the tool is still callable correctly from the given information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only source of parameter meaning. It clearly explains 'name' as the display name and 'light_ids' as an optional initial list with a concrete example (["1", "3", "5"]), fully compensating for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Create a new light group.' This unambiguously distinguishes it from sibling tools like modify_group, delete_group, and list_groups, and leaves no doubt about the operation performed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the verb 'Create' and the resource 'light group,' but the description does not explicitly state when to choose this tool over alternatives such as modify_group or set_group_action. There is no mention of prerequisites, limitations, or what to do if a group already exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'List all automation rules with their status and trigger conditions' conveys that this is a read-only enumeration and indicates the returned content, but it does not disclose potential pagination, ordering, permission requirements, or whether disabled rules are included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundant wording. It front-loads the action and resource, and the extra detail about status and trigger conditions is directly useful for selecting the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only list operation, the description covers the core purpose and the expected key fields. An output schema is present, so return format details do not need to be in the description. Slightly more context about edge cases like empty results or permissions would push it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so parameter documentation is unnecessary. The description still adds useful context by indicating what the returned data will contain, so the baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('all automation rules'), and clarifies the scope with 'all', distinguishing it from single-rule operations like get_rule. It also names the key fields returned (status, trigger conditions), making the tool's 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is for enumerating all automation rules, but it does not explicitly state when to prefer it over alternatives or mention when not to use it. Sibling tools like get_rule and list_schedules exist, but no routing guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior on its own. 'Overwrite' clearly indicates a destructive write, and the source of the stored state is specified. It does not, however, mention error cases (e.g., nonexistent scene) or whether the change is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: one imperative sentence states the core behavior, followed by a minimal two-item Args block. Every phrase earns its place, and the behavior is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation with an output schema present, the description supplies the essential semantics and side effect. It lacks only explicit edge-case or prerequisite notes, which are minor for this straightforward store operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the inline Args block must compensate. It adds meaning by calling group_id 'Numeric group ID' and defining scene_id as 'Scene ID to overwrite,' which is more than the bare schema property titles provide. The numeric wording is slightly ambiguous next to the string type, but it is still a useful semantic clue.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('overwrite') and resource ('scene'), and identifies exactly what is captured ('current state of all lights in the group'). This distinguishes it from scene creation, recall, and deletion without needing to compare names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: save a live group state into an existing scene. However, there is no explicit when-to-use or when-not-to-use guidance, and no alternative among the many scene siblings (e.g., create_scene) is mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 meaningful behavioral detail, such as valid condition operators and the expected shape of conditions and actions. It does not mention side effects, immediate activation, duplicate-name behavior, persistence guarantees, or permissions, so the behavioral picture is incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description opens with a one-sentence purpose, then provides only high-value operational detail: argument meanings, one example per complex parameter, and the operator list. There is no filler or redundant restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the parameter shapes are opaque in the schema, the examples and operator list are enough for an agent to construct a valid rule payload. The main remaining gap is behavioral context such as whether the rule becomes active immediately and what happens if a rule with the same name already exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by explaining all four arguments: name, conditions, actions, and status. It provides concrete JSON examples for conditions and actions and enumerates the allowed condition operators, which are essential because the schema only declares opaque arrays of objects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence 'Create an automation rule triggered by sensor conditions' names a specific verb and resource, and the 'triggered by sensor conditions' qualifier clearly distinguishes it from generic rule utilities. The Args section reinforces that this is a creation tool, not a read/delete/status tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: whenever a new automation rule must be created. However, it does not explicitly contrast create_rule with sibling alternatives such as set_rule_status, list_rules, or create_schedule, nor does it explain when rule automation is preferable to schedule automation. The usage guidance is clear but left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the behavioral disclosure burden. It explains the core mechanism—sending a command to the gateway on a schedule—and gives meaningful detail on time semantics, recurring timers, and autodelete one-shot behavior. It does not cover permissions, errors, or gateway connectivity requirements, but the main behavioral contract is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A one-sentence summary is followed by a tight argument list where each entry earns its place. The detailed time examples and command payload examples are justified by the complete lack of schema descriptions. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 8-parameter tool with no schema descriptions and no annotations, the description covers all parameters and key behavioral nuances such as weekly, timer, and recurring-timer expressions. It falls slightly short on operational context like error behavior, permission requirements, or what happens when the gateway is unreachable, but it is sufficient for invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates. Every parameter is explained with type, meaning, and usually a concrete example. The time parameter is especially well documented with multiple ISO 8601 formats, command_method is constrained to PUT/POST/DELETE, and command_body is shown with a JSON example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Create a timed schedule that sends a command to the gateway.' This clearly identifies what the tool does and distinguishes it from schedule read/delete/status siblings like get_schedule, delete_schedule, and set_schedule_status. It also separates it from create_rule, which would imply event-driven rule logic rather than timed commands.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as create_rule or set_schedule_status. It explains the arguments well but never states the intended use context, prerequisites, or cases where a different sibling tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It clarifies the output fields but does not state that the operation is read-only, requires no permissions, or note any ordering or pagination behavior. Listing inherently suggests no side effects, so it is minimally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the action and resource and includes the key output fields. Every word contributes meaning with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless list operation with an output schema, the description is complete: it names the resource and the fields returned. There is no missing information an agent needs to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully covers parameter needs. The description adds nothing about parameters because none exist, which is appropriate for this tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('all timed schedules') and states the returned information (next trigger time and status). It is distinct from siblings like get_schedule because it covers all schedules rather than a single one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: call this when you need an overview of all schedules. However, it does not explicitly contrast with get_schedule for retrieving a single schedule or mention any exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden. It does reveal that the tool returns the 'current state' of sensors and 'List' strongly implies a read-only operation, but it does not explicitly state that no state is modified, whether values are cached, or whether any side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that names the action, the scope, examples of sensor types, and the key output characteristic. Every word earns its place, with no padding or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless listing tool with an output schema available, the description provides enough context to invoke it correctly. It names what is returned ('current state') and the broad category of items, and the output schema covers the return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there are no parameter semantics to clarify. The description correctly contains no parameter-specific guidance, and the baseline for a parameterless tool is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a clear resource ('all sensors'), and the output scope ('temperature, humidity, presence, switches, etc.'). The word 'all' distinguishes it from the sibling 'get_sensor', which targets a single sensor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving a broad overview of all sensors, but it does not explicitly say when to prefer it over 'get_sensor' or other list tools. Usage context is implied rather than stated with clear alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does state the destructive scope ('only the group is removed') and the non-destructive side effect ('lights remain'). However, it does not mention irreversibility, failure behavior, or any consequences for scenes/rules referencing the group. Basic but acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core operation and its most important caveat are front-loaded in a single sentence, with a short args line. Every sentence earns its place and there is no redundant or vague filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter delete tool with an output schema, this description is nearly complete. Missing contextual details like what happens if the group ID does not exist or whether deletion is irreversible are not critical, but mentioning them would make it fully robust.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 explains that group_id is the numeric group ID to delete, adding meaningful semantics beyond the raw schema type string. The word 'Numeric' could be slightly ambiguous against the schema type, but it still communicates the intended value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and object: 'Delete a light group', and immediately disambiguates the resource by adding '(lights remain, only the group is removed)'. This clearly distinguishes it from sibling tools like delete_light and delete_sensor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical clearly communicates what this tool will and will not do: it removes only the group, never the lights. This gives useful context, though it does not explicitly name alternatives or state 'use this instead of delete_light'. The intended use is clear enough for a single-purpose delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral transparency burden. The verb 'Return' conveys a read-only operation and the listed fields indicate what information is exposed, but it does not mention authentication requirements, error behavior, or explicitly state that no changes are made.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that names the action, the resource, and representative data categories without wasting words. It is appropriately concise for a no-argument read tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read-only tool with an output schema, the description covers the essential purpose and content. It could be slightly more explicit about when to use it or what kind of response to expect, but the output schema and the absence of parameters reduce the need for additional detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds useful context by naming the kinds of configuration values returned, even though there are no parameters to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Return the deCONZ gateway configuration', and enumerates concrete content such as firmware, network, and Zigbee channel. This clearly distinguishes it from sibling tools that operate on lights, groups, sensors, rules, or scenes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates the tool is for retrieving overall gateway configuration, which is distinct from the other listed tools. It does not explicitly mention alternatives or exclusions, but no sibling tool appears to serve the same purpose, so the intended usage is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It discloses the main behavior — returning full group details including member lights and scenes — but does not mention possible error behavior, whether the operation is read-only, or any side effects. For a simple getter this is acceptable but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. The first sentence states the tool's purpose and expected output, and the Args section provides the only necessary parameter guidance without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity, single-parameter getter, the description is mostly complete: it states what is returned and how to find the ID. An output schema exists to cover return-value details. It could add explicit error or invalid-ID behavior, but that is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only the type 'string', so the description adds meaningful parameter context by explaining that group_id is a numeric group ID and that list_groups should be used to discover IDs. It does not specify exact format or constraints, but for a single parameter this is strong added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Get full details of a light group including member lights and scenes.' It clearly identifies what the tool returns and distinguishes it from list_groups and get_light, which operate at a different scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this tool to fetch full details for a specific light group, and use list_groups to discover valid IDs. It does not explicitly state when not to use it or name alternatives for the same task, but the purpose and sibling relationship make the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the behavioral burden. 'Get' signals a read-only retrieval, and 'including conditions and actions' tells the agent what content to expect. It does not discuss error handling or permissions, but those are less critical for a simple get-by-id read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with the purpose front-loaded and an efficient Args line. Every sentence earns its place, with no filler or redundant explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 the description's job. The description covers the essential call purpose and ID discovery for a single-parameter tool. The rule_id type ambiguity is the main gap keeping this from a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining rule_id as a 'Numeric rule ID' and pointing to list_rules for discovery. However, the schema declares rule_id as type string, so 'Numeric' is ambiguous and could mislead an agent into supplying an integer rather than a string.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Get full details of an automation rule including conditions and actions' – a specific retrieval action with a clear resource and content scope. The phrase 'full details' and the mention of conditions/actions clearly differentiate it from list_rules and other get_* siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides actionable usage context in the Args section: 'use list_rules to discover IDs,' telling the agent how to obtain a valid rule_id before calling. It does not explicitly enumerate alternatives or exclusions beyond list_rules, so it stops short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. 'Get' implies read-only retrieval and the 'including state, config, and capabilities' clause clarifies the return scope. However, it does not mention behavior for invalid IDs, permission requirements, or any side-effect guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one clear purpose sentence immediately followed by a concise Args note. No filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple single-parameter getter with an output schema present, and the description covers purpose, return scope, and parameter discovery. It does not cover error cases or explicitly state read-only behavior, but nothing essential for invoking it correctly appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 sensor_id, and it does: it identifies the parameter as a numeric sensor ID and points to list_sensors for discovery. There is a minor mismatch, though: the schema types sensor_id as a string while the description calls it numeric.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Get full details') on a specific resource ('a specific sensor') and lists the returned content categories (state, config, capabilities). This clearly distinguishes it from list_sensors and other per-resource getters like get_light or get_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using list_sensors to discover IDs, providing useful guidance for when the ID is unknown. It does not explicitly name exclusions or alternative getters, but the usage context for a single-sensor retrieval tool is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose the kinds of information returned (state, attributes, capabilities). However, it does not mention error behavior, side effects (none expected), or any access requirements; for a simple read operation this is adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The main purpose is front-loaded, and the argument guidance is compactly appended.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with an output schema, the description is complete: it identifies what the tool returns and how to resolve the one argument. There is no missing information that would prevent an agent from calling it successfully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates fully for the single parameter: it specifies that light_id is a numeric ID and explicitly points to list_lights for discovery. This adds real semantic value beyond the bare schema definition (type string, title 'Light Id').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a specific resource ('a specific light'), and the scope of the response ('full details including state, attributes, and capabilities'). This clearly distinguishes it from list_lights (collection) and mutation siblings like set_light_state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent how to obtain the required light_id via list_lights, which is practical guidance for using this tool correctly. It does not explicitly state when not to use this tool, but for a single-item read operation the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden; 'List' signals a read-only operation and 'current action state' tells the agent what additional data is returned. For a zero-parameter, non-destructive tool, this is adequate transparency, though it does not discuss potential staleness or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One tight sentence with the verb and scope front-loaded and only one qualifying detail ('current action state'). No filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-argument list call with an output schema present, the description is complete enough. It states exactly what will be returned and implies a non-mutating operation; an agent can invoke it with confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema is empty, so there is no parameter meaning for the description to add. Baseline for 0-parameter tools is 4; nothing is missing here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource ('all light groups') and adds the distinguishing detail 'with their current action state.' This separates it from list_lights (individual lights) and get_group (single group) without needing to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'all light groups' gives clear context that this is the enumeration tool, not a single-group lookup. It does not explicitly name alternatives like get_group, so it stops short of a 5, but the scope is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of indicating behavior. 'List... with their current state' conveys a read-only enumeration operation and identifies what the agent can expect. It does not mention pagination or error behavior, but for a simple no-parameter list tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes meaning: 'List', 'all lights', 'known to the deCONZ gateway', and 'current state' are all necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, collection-level list tool with an output schema available, the description fully covers what the tool does and what scope it operates on. No additional context about return values is needed because the output schema handles that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so there is nothing for the description to add about parameters. The baseline of 4 applies because no parameter documentation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb ('List'), the resource ('all lights'), and the scope ('known to the deCONZ gateway') plus what is returned ('current state'). This strongly distinguishes it from sibling tools like get_light (single light) and set_light_state (mutating a light).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'all lights' makes clear this is the enumeration tool, implying use when the agent needs a full collection rather than a single light. It does not explicitly name alternatives or exclusion conditions, but the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. The verb 'List' makes the read-only, non-destructive nature apparent, and 'all scenes defined for a group' accurately describes what the call returns. It does not add caveats like pagination or ordering, but none are strongly implied for this simple operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The first states the operation, and the second explains the parameter and how to source it. Information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a single-parameter list tool with an output schema provided, so the description does not need to explain return values. It states what the tool does and how to obtain the required group_id. Nothing critical is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It does: 'Numeric group ID' clarifies the expected value and 'use list_groups to discover IDs' gives the agent a concrete discovery path. Slight tension exists between 'Numeric' and the schema's string type, but the intent is still understandable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List all scenes defined for a group.' This clearly distinguishes the tool from siblings like get_scene (single scene), create_scene, recall_scene, and delete_scene. The group scope is explicit and easy to act on.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear, actionable context by explaining that group_id is numeric and by pointing to list_groups to discover valid IDs. It does not explicitly mention when to prefer this over get_scene or other scene tools, but the 'list all scenes for a group' framing provides sufficient situational clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral disclosure burden. It usefully reveals that the scan takes about 10 seconds and that results are not returned directly but must be fetched via a follow-up call. It does not discuss side effects or failure behavior, but the key operational traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It front-loads the action, includes the only timing detail that matters, and ends with the required next step.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a param-free tool with no annotations, the description is complete: it explains what the tool does, how long it takes, and what to do next. Since an output schema exists, not detailing the return value is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no properties and parameter count is 0, so there is nothing for the description to add about parameters. The zero-parameter baseline of 4 applies, and the description correctly focuses on behavior instead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Start a Touchlink scan'), a target resource ('nearby Zigbee devices'), and clearly differentiates it from get_touchlink_results by positioning this as the initiation step and the other as retrieval. This makes the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by telling the agent to call get_touchlink_results after scanning to see discovered devices. It does not explicitly say when not to use this tool or contrast it with touchlink_identify/touchlink_reset, but the intended workflow is obvious for a zero-parameter scan action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining side effects. It does so by stating that the network is opened for joining and by describing duration semantics, including 0 to close immediately and a default of 60 seconds. It could go further by noting whether the network closes automatically when the duration expires, but the wording 'Seconds to allow joining' strongly implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it leads with the purpose, then provides the parameter details in a scannable format. There is no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter operation with no required arguments, an output schema present, and a clear purpose, the description is complete enough for an agent to select and invoke the tool correctly. It explains what the tool does, when to use it, and how to use the only parameter correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully document the parameter. It does: duration is in seconds, has a 0–255 range, 0 means close immediately, and the default is 60. This is complete semantic guidance for the only input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action, 'Open the Zigbee network', with a clear outcome, 'so new devices can join'. This is distinct from the sibling tools, which manage lights, groups, scenes, rules, etc., so an agent can identify this as the network-joining tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'so new devices can join' provides clear context for when to call: when the user wants to allow devices to pair with the Zigbee network. It does not name alternatives or explicit exclusions, but no sibling tool appears to cover permit-join, so the absence of a when-not is not a serious gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it clearly discloses the destructive consequences: factory defaults and removal from the gateway, highlighted with a 'Warning'. It also identifies the required input's source, giving an agent the prerequisite knowledge needed before calling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, purposeful sections: action, argument source, and warning. Nothing is redundant, and the destructive warning is clearly front-loaded before the parameter detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive tool with an output schema, the description covers the action, the source of the required ID, and the principal side effects. No additional return-value documentation is necessary because an output schema is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain touchlink_id. It does meaningfully by specifying it is the Device ID from get_touchlink_results, which links the reset tool to the discovery workflow. It does not give format or length, but the source is sufficient for a single string parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action and resource: factory-reset a Touchlink device and remove it from its current network. This is immediately distinguishable from touchlink_scan, touchlink_identify, and get_touchlink_results, which concern discovery and identification rather than reset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for use: it is the reset action on a device found via a touchlink scan, and it tells the agent where the touchlink_id comes from (get_touchlink_results). It does not name explicit alternatives or exclusions, but no sibling performs a reset, so the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![deConz-mcp MCP server](https://glama.ai/mcp/servers/marcinn2/deConz-mcp/badges/card.svg)](https://glama.ai/mcp/servers/marcinn2/deConz-mcp)

Score Badge

Copy to your README.md:

[![deConz-mcp MCP server](https://glama.ai/mcp/servers/marcinn2/deConz-mcp/badges/score.svg)](https://glama.ai/mcp/servers/marcinn2/deConz-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/marcinn2/deConz-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server