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

With no annotations, the description must fully disclose behavioral traits. It explains the action and a specific error but omits key details: side effects on the network, undoability (e.g., using zwave_remove_association), permissions, hardware interaction, and return values. This lack of transparency could lead to misuse for a mutating tool.

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

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

The description is concise and front-loaded with the main action. The Args section is clear but could be slightly more compact. Overall, every sentence is informative without redundancy.

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

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

The description completely covers parameters and references a sibling tool for group selection. However, it lacks information about the return value or success/failure indicators, and does not mention how to verify the association after addition. For a 5-parameter tool with no output schema, more completeness is warranted.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains all five parameters: node_id, group, target_node_id, source_endpoint (with default), and target_endpoint (with default). This adds critical meaning beyond the schema's type-only definitions.

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

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

The description clearly states it adds an association, specifies source node group and target node, and distinguishes from sibling tools like zwave_remove_association or zwave_association_groups. The example of a switch driving a light clarifies the concept.

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

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

The description advises using zwave_association_groups to pick a valid group, which provides usage context. It also notes that an unknown source node raises ValueError. However, it does not mention when to avoid using this tool or provide alternatives like zwave_associations for viewing existing associations.

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

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

Describes return shape (mapping of group id to properties) and error condition (ValueError). No annotations provided, so the description carries the burden. However, it doesn't explicitly state that it's a read-only operation or discuss side effects, so it's 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.

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

Very concise: short paragraph with clear structure. Main purpose upfront, followed by return details, usage hint, error info, and parameter descriptions. No unnecessary words.

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

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

Without annotations or output schema, the description covers all essential aspects: purpose, input parameters with defaults, output shape, error conditions, and usage context (links to another tool). Complete for a list tool.

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

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

With 0% schema description coverage, the description fully explains both parameters: 'node_id' as source Z-Wave node id with example, and 'endpoint' as optional index defaulting to root device. This adds significant meaning beyond the schema's bare titles.

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

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

The description clearly states the verb 'List' and the resource 'node's association groups and their capabilities'. It distinguishes itself from siblings like 'zwave_add_association' and 'zwave_associations' by specifying it lists groups, not associations.

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

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

Explicitly states to use this tool to find the group to pass to 'zwave_add_association', providing clear context. Also mentions error handling for unknown node ids. Could be improved by noting when not to use it, but still strong.

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

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

No annotations provided, so description carries full burden. It describes the read behavior and error case but does not explicitly state it is read-only, rate limits, or auth requirements. Adequate but not thorough.

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

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

Description is concise with a clear structure: purpose, return format, error, then args in bullet list. No wasted words, but could be slightly more compact.

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

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

No output schema, so description explains return value (keyed by group id, list of targets). Error handling covered. Parameter explanation sufficient. Lacks when-to-use guidance, but otherwise complete for a list tool.

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

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

Schema coverage is 0%, but description adds meaning for both parameters: node_id with example and endpoint with default behavior. This compensates for schema lack, though could be more detailed about endpoint's effect.

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

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

The description clearly states 'List a node's current associations, keyed by group id.' It specifies the verb (List), resource (node's associations), and return format. Distinguishes from sibling tools like zwave_add_association and zwave_remove_association.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., zwave_association_groups, zwave_add_association). Only mentions error handling (ValueError) but lacks context for selection.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals that the tool returns immediately upon entering exclusion mode and requires the device to be put into exclusion/unpair mode to complete removal. This is valuable context beyond the empty schema.

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

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

The description is two sentences long, front-loaded with the main action, and contains no redundant information. Every sentence adds value.

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

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

Given the lack of output schema and annotations, the description sufficiently explains the tool's purpose, non-blocking behavior, and next steps. It could mention prerequisites or state requirements but is adequate for a simple tool.

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

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

The tool has zero parameters and schema description coverage is 100%, so the description need not add parameter details. The baseline of 4 is appropriate since there is nothing more to convey.

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

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

The description clearly states the tool puts the controller into exclusion mode to remove a node, using a specific verb and resource. It distinguishes itself from siblings like zwave_begin_inclusion and zwave_stop_exclusion.

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

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

The description explains when to use the tool (to remove a node) and how to complete the process, including canceling with zwave_stop_exclusion. However, it lacks explicit when-not-to-use guidance or prerequisites like controller idle state.

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

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

Discloses that the tool returns immediately upon entering inclusion mode, not after node addition, and that device pairing is required separately. Warns about the stateless server limitation for S2. No annotations exist, so the description carries the burden and does so well, though it could mention potential side effects like timeout behavior.

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

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

Concise and well-structured: a primary statement, followed by a note on behavior, a crucial limitation, a reference to a sibling tool, and the args explanation. Every sentence adds value without redundancy.

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

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

Covers the main behavioral aspects: return behavior, required device action, and security limitation. No output schema exists, but the description does not need to specify return values. It does not mention error handling or edge cases (e.g., already in inclusion mode), but given the tool's simplicity, it is fairly complete.

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

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

The schema has 0% description coverage, so the description provides essential meaning for the 'strategy' parameter by listing the four possible values and explaining the security context. It adds value beyond the schema's type and default, though it could elaborate on when each strategy is appropriate.

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

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

The description clearly states the tool's purpose: putting the controller into inclusion mode to add a new node. It distinguishes from exclusion and other operations by mentioning zwave_stop_inclusion and the sibling tool zwave_begin_exclusion. The verb 'put' and resource 'controller' are specific.

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

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

Provides clear context for when to use (to add a node) and a crucial note about the limitation of S2 security bootstrap, directing to the Z-Wave JS UI for that case. Also mentions cancellation via zwave_stop_inclusion. Lacks explicit wording on when not to use, but the limitations effectively guide the agent.

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

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

Discloses that the operation runs in background and returns immediately, which is sufficient for a simple start action. No annotations so responsibility on description; minor missing detail on potential impact but still good.

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

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

Two concise sentences with no redundancy. Front-loaded purpose, efficient.

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

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

Sufficient for a parameterless tool with no output schema. Links to stop tool. Could mention typical duration but not required.

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

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

No parameters exist; schema coverage is 100%. Following guidelines, zero parameters baseline is 4. Description adds no unnecessary param info.

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

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

Clearly states it starts a network-wide route rebuild (network heal). Effectively distinguishes from sibling tools like zwave_rebuild_node_routes and zwave_stop_rebuilding_routes.

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

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

Explicitly explains the non-blocking nature ('returns once started, proceeds in background') and names the cancelling sibling tool, providing clear when-to-use and alternative.

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

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

No annotations are provided, so the description carries full burden. It describes the read-only nature by saying 'Get' and 'Returns', but does not explicitly state no side effects or permissions required. The behavior is implied but not fully disclosed.

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

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

Three sentences, front-loaded with purpose, no wasted words. Every sentence adds value: purpose, return fields, usage recommendation, and specific output detail.

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

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

For a simple, parameterless info tool, the description is complete. It lists all major return fields, explains a complex output field (controller_type), and gives usage guidance. No output schema exists, so this adequately covers expected behavior.

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

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

The input schema has zero parameters with 100% coverage trivially. The description adds no parameter info, which is fine. It compensates by detailing the output structure, including the controller_type format, providing value beyond the empty schema.

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

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

The description clearly states 'Get Z-Wave controller and network summary' and lists specific return fields. It distinguishes from siblings by advising 'Use this first for a quick health snapshot', implying a high-level overview role.

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

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

The description explicitly recommends 'Use this first for a quick health snapshot of the mesh', providing clear context for when to use. However, it does not mention when not to use or list alternatives for deeper diagnostics.

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

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

No annotations provided, so description carries full burden. It discloses that the tool only reports status and that triggering updates is unsupported. However, it does not explicitly state that it is a read-only, non-destructive operation, though it is implied.

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

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

Two concise sentences, no wasted words. Front-loads the core purpose and includes a useful note about unsupported features. Excellent structure.

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

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

For a simple status-check tool with no parameters and no output schema, the description provides the return format and a caveat. It is complete enough to use correctly, though it could hint at being a safe read operation.

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

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

There are zero parameters, and schema coverage is 100% trivially. The baseline is 3 per guidelines. The description adds no parameter-specific meaning since none exist, but that is acceptable.

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

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

The description clearly states the tool reports on OTA firmware update status, using specific verb 'report' and resource 'firmware update'. It distinguishes itself from all sibling tools, which cover associations, inclusion, routes, node config, etc.

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

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

The description implies usage for checking update progress but lacks explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, though none exist among siblings. Adequate but minimal.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It describes the output fields in detail, implying a read-only operation. However, it does not mention important behavioral traits such as whether the operation has side effects, requires authentication, or has performance implications. The description is adequate but not comprehensive.

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

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

The description is concise and front-loaded: the first sentence states the action and resource, followed by a bullet-like list of output fields. Every sentence provides useful information with no redundancy or fluff.

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

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

Given the tool's simplicity (no parameters, standard list operation) and the presence of an output schema, the description provides sufficient detail about the output fields and directs users to zwave_node_info for more detail. It does not cover edge cases like an empty node list, but this is a minor omission for a straightforward listing tool.

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

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

The tool has no parameters, and schema coverage is trivially 100%. As per guidelines, baseline for 0 parameters is 4. The description does not need to add parameter information, and it correctly describes the output without mentioning parameters.

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

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

The description clearly states the tool lists all Z-Wave nodes with a one-line summary, listing the specific fields included. It also distinguishes itself from the sibling zwave_node_info, which provides full detail on a single node. The verb 'list' and resource 'all Z-Wave nodes' are specific and unambiguous.

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

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

The description explicitly tells when to use zwave_node_info instead ('Use zwave_node_info for full detail on a single node'), providing clear guidance on context. It does not, however, mention other sibling tools like zwave_controller_info or zwave_node_config, which could offer alternative functionality. This is a minor gap, but the key alternative is covered.

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

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

With no annotations provided, the description carries full burden. It describes the return content (parameter details like default, range, unit) and error behavior (ValueError for unknown node ID). Example parameter types (LED behavior, motion sensitivity) further clarify expected output.

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

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

The description is well-structured with a brief first sentence stating purpose, followed by detail on return values and usage guidance. It is not overly verbose, though the param example could be more integrated.

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

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

Given the existence of an output schema (providing return structure) and a single simple parameter, the description covers all necessary aspects: purpose, return values, related tool, error handling. It is sufficient for an agent to correctly select and invoke the tool.

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

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

Schema description coverage is 0%, requiring the description to compensate. It explains node_id as 'The Z-Wave node id, e.g. 5,' providing a concrete example. For a single integer parameter, this adds sufficient meaning beyond the schema's type definition.

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

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

The description clearly states the tool 'list[s] a node's configuration parameters and their current values,' specifying the verb 'list' and the resource 'configuration parameters.' It distinguishes from sibling tools like zwave_set_config_parameter (which sets parameters) and zwave_node_info (general node info).

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

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

The description explicitly tells the agent to use zwave_set_config_parameter for setting a parameter, providing a clear alternative. It also notes that a ValueError is raised for unknown node IDs, guiding appropriate usage. However, it does not list other context-specific exclusions.

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

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

With no annotations, description carries full burden. Discloses error handling (ValueError) and the special structure of protocol_version. Could mention more about return format but sufficient.

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

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

Front-loaded with purpose, includes docstring. Slightly verbose with protocol_version detail but not excessive. Well-structured.

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

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

No output schema, but description enumerates returned fields (device class, command classes, etc.) and highlights protocol_version shape. Covers key aspects for a single-node detail tool.

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

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

Schema coverage is 0%, but description adds parameter name, type, and example (node_id: integer, e.g., 5). Adds meaning beyond bare schema.

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

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

Clearly states 'Get full detail for a single Z-Wave node,' specifying verb and resource. Distinguishes from sibling tools like zwave_list_nodes (list) and zwave_node_config (config).

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

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

No explicit guidance on when to use vs alternatives, though the purpose implies single-node detail. Mentions ValueError for unknown node_id, which is helpful but not a usage guideline.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns multiple fields (id, command class, endpoint, property, reading, metadata) and raises ValueError for unknown node ids. It does not mention destructive actions, which is appropriate as the tool is read-only.

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

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

The description is concise with two short sentences and a clear structure: purpose, return value summary, error note, and argument. Every sentence adds value, and the most important information (purpose, exclusion) is front-loaded.

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

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

The tool is simple with one required parameter and an output schema exists. The description fully covers the purpose, return fields, error condition, and parameter meaning, making it complete for an agent to use correctly.

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

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

Schema coverage is 0% for node_id, but the description adds meaning by stating 'The Z-Wave node id, e.g. 5', providing a clear example and explanation. This compensates partially for the lack of schema descriptions.

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

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

The description clearly states the tool lists a node's current values excluding configuration parameters, distinguishing it from the sibling tool zwave_node_config. It specifies the resource (node) and verb (list), and explicitly excludes configuration parameters.

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

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

The description explains when to use this tool (to list current values) and notes that configuration parameters are handled separately by zwave_node_config, providing a clear alternative. It also mentions ValueError for unknown node ids, but lacks explicit guidance on when not to use.

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

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

No annotations present. Description mentions return type and ValueError, but lacks side effects (e.g., network disruption, node must be awake, blocking nature). Minimal disclosure for a modifying operation.

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

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

Two sentences plus code block for return. No wasted words; front-loaded with action and result.

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

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

Tool performs a critical network operation but lacks context on triggers, prerequisites, and potential impacts. No output schema, though return documented. Incomplete for safe usage.

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

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

Schema coverage is 0%, description adds example 'e.g. 5' and clarifies it's a Z-Wave node id. Adds some meaning beyond schema's type, but still sparse.

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

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

Description clearly states verb 'Rebuild' and resource 'mesh network routes for a single node'. Distinguishes from siblings like zwave_begin_rebuilding_routes (all nodes) and zwave_rebuild_routes_status.

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

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

No guidance on when to use this tool vs alternatives, e.g., when a node has connectivity issues. No prerequisites or context provided.

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

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

No annotations provided, so description carries the full burden. It discloses that the tool returns {'is_rebuilding': bool | null} from controller state, which is a read-only query. No side effects or additional behaviors are expected, but it does not explicitly state it is non-destructive.

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

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

Two concise sentences that front-load the purpose and then provide return value and usage. No wasted words.

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

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

With 0 parameters and no output schema, the description is complete: it explains the return type and usage pattern. No additional information needed for selection or invocation.

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

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

No parameters exist in the input schema, so baseline of 4 is appropriate. Description does not need to add parameter meaning beyond schema.

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

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

Description clearly states it 'Report whether a network-wide route rebuild (heal) is in progress.' It specifies the resource ('network-wide route rebuild') and the action ('report status'). This distinguishes it from sibling tools like 'zwave_begin_rebuilding_routes' and 'zwave_stop_rebuilding_routes'.

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

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

Explicitly says 'Poll this after zwave_begin_rebuilding_routes to track a heal to completion.' Provides clear context for when to use the tool. Does not mention when not to use or alternatives, but the purpose is self-explanatory for monitoring.

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

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

No annotations are provided, but the description discloses async nature, potential delays, and error behavior. It does not explicitly state if the operation is destructive or read-only, but the context suggests it modifies state; overall transparency is good.

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

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

The description is two short paragraphs: first line states purpose, second adds behavioral details. Every sentence is informative, no fluff.

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

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

While the description explains the process and errors, it does not mention the return value (likely nothing or a confirmation). Since there is no output schema, this omission reduces completeness for a fire-and-forget tool.

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

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

The description adds meaning to the sole parameter node_id by providing an example ('e.g. 5') and clarifying it's a Z-Wave node id. This adds value beyond the input schema, which has 0% coverage.

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

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

The description clearly states the tool re-runs a node's interview to refresh capabilities and values, using a specific verb and resource that distinguishes it from siblings like zwave_node_info or zwave_rebuild_node_routes.

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

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

Describes fire-and-forget behavior, background execution, delay for battery devices, and ValueError for unknown nodes. While it doesn't explicitly contrast with siblings, the guidance is clear and practical.

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

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

No annotations provided; the description only mentions one behavioral trait ('Raises ValueError for an unknown source node id'). It does not disclose other effects like mutation, prerequisites, or result format.

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

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

Description is short and front-loaded with the main action. No unnecessary words. Parameter list is clear but could be more structured.

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

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

With 5 parameters, no output schema, and no annotations, the description lacks usage guidelines, return values, and effects of removal. Users are left uncertain about what happens after the operation.

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

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

Schema coverage is 0% (no parameter descriptions). The description adds some semantics with examples ('e.g. 5') and defaults ('defaults to the root device'), but does not fully explain each parameter beyond names.

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

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

The description clearly states the action ('Remove') and the resource ('association from a source node's group to a target node'). It distinguishes from sibling tools like zwave_add_association and zwave_associations.

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

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

No guidance on when to use this tool vs alternatives (e.g., when to remove vs add or list associations). The description only lists parameters without usage context.

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

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

With no annotations, the description fully explains the behavioral scope: removal of a failed node, error handling for unknown IDs. It directly states the requirement for the node to be marked failed, which is the key behavioral constraint. However, it does not mention permanence or side effects (e.g., irreversible removal), which is minor given the simplicity.

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

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

The description is extremely concise: a one-sentence purpose, two brief preconditions/errors, and a one-line Args section. No redundant or unnecessary information. The most important detail (what the tool does) comes first.

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

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

For a simple tool with one parameter and no output schema, the description covers the essential aspects: purpose, precondition, error case. It could mention return value (likely void/success) but this is not critical. Overall, it provides sufficient context for correct usage.

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

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

The input schema only provides a type and title for node_id. The description adds a concrete example ('e.g. 5') and clarifies the meaning ('The Z-Wave node id'), which compensates for the 0% schema description coverage. This makes the parameter's purpose immediately clear.

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

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

The description clearly states the action ('Remove a node'), the target ('that the controller has marked failed'), and the context ('from the network'). This distinguishes it from sibling tools like zwave_list_nodes or zwave_reinterview_node by focusing specifically on failed node removal.

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

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

The description gives clear conditions: 'Only works on nodes the controller considers failed (dead/unreachable)' and 'Raises ValueError for an unknown node id'. While it does not explicitly contrast with alternative tools for other node states, the precondition is well-defined, providing actionable guidance.

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

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

No annotations provided, so description must disclose behavior. It states the tool writes a configuration parameter, returns ACCEPTED/QUEUED status, raises ValueError for unknown node, and mentions partial writes via bitmask. However, it does not mention potential side effects like node re-interview or reboot requirements.

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

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

The description is well-structured with a short introductory line, example, and numbered Args list. It is front-loaded with the core action. Minor redundancy in explaining bitmask twice (first in prose, then in Args) but overall efficient.

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

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

Given no output schema, the description covers return value (ACCEPTED/QUEUED) and error case. It hints at the prerequisite of using zwave_node_config to find parameter numbers. Among many sibling tools, it clearly targets manufacturer configuration parameters. Could mention that the node must be included in the network.

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

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

Schema coverage is 0%, but the description thoroughly explains each parameter: node_id is the Z-Wave node id, parameter is the parameter number (from zwave_node_config's property), value is the new integer value, and bitmask is the optional partial-parameter bit mask (property_key). This adds significant meaning beyond the schema's type-only information.

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

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

The description clearly states it sets a node's manufacturer configuration parameter, specifying the parameter number from zwave_node_config, optional bitmask for partial writes, and return status. This distinguishes it from sibling tools like zwave_set_value and zwave_node_config.

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

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

The description implies usage by referencing zwave_node_config for parameter numbers, but does not explicitly state when to use this tool over alternatives like zwave_set_value or how to handle prerequisites. No exclusions or contrast with siblings.

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

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

The description discloses that it raises ValueError for an unknown node id, which is a behavioral detail. However, with no annotations provided, it does not mention other traits like destructiveness, permissions, or reversibility, so transparency is moderate.

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

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

The description is concise and well-structured: a one-line purpose, error behavior, then parameter definitions. Every sentence is necessary, no redundancy.

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

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

For a simple setter tool, the description covers purpose, parameters, and error handling. However, it lacks information about success behavior (e.g., return value) and side effects, which slightly reduces completeness.

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

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

Schema coverage is 0%, but the description adds meaningful semantics by explaining each parameter: node_id as 'The Z-Wave node id, e.g. 5' and location as 'The new location for the node'. This compensates for the lack of schema descriptions.

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

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

The description clearly states 'Set a node's location label.', specifying the verb (Set) and resource (node's location label). It distinguishes this tool from siblings like zwave_set_node_name and zwave_set_config_parameter by focusing specifically on location.

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

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

No guidance is provided on when to use this tool versus alternatives. The description simply states its function without context on exclusions or comparisons with sibling tools, leaving usage implied.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It reveals that the tool raises ValueError for unknown node IDs, a key behavioral detail. However, it does not describe side effects (e.g., events triggered, persistence guarantees) or confirm idempotency, leaving minor gaps.

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

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

The description is extremely concise with no wasted words. It uses a clear structure: purpose statement, error condition note, then parameters. Every sentence adds value.

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

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

For a simple setter with two parameters and no output schema, the description covers essential aspects: purpose, error behavior, and parameter meanings. Minor missing details (e.g., name constraints, return behavior) are not critical given the tool's simplicity.

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

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

The input schema has 0% description coverage, but the description compensates by explaining each parameter: node_id is 'The Z-Wave node id, e.g. 5' and name is 'The new name for the node'. This adds meaning beyond the schema's type-only definitions. An example for node_id further aids understanding.

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

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

The description clearly states the verb ('Set') and the resource ('a node's friendly name'), unambiguously identifying the tool's action. It differentiates from siblings like zwave_set_config_parameter and zwave_set_node_location by specifying the attribute being modified.

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

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

The description includes a condition for when the tool raises a ValueError (unknown node id), which helps with error handling. However, it lacks explicit guidance on when to use this tool versus alternatives like zwave_set_node_location or zwave_set_config_parameter, and does not mention prerequisites or context.

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

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

Discloses return status types, error condition (ValueError for unknown node), value type requirements, and example format. No annotations exist, so description carries full burden; missing details on invalid value type handling or side effects.

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

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

Concise paragraph with bulleted args, front-loaded purpose, no wasted words. Every sentence adds value: outcome, error, prerequisites, example.

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

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

Adequately covers behavior, return, error, and constraints for a simple set-value tool. Explains value_id source, status types, and queuing for sleeping nodes, despite no output schema.

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

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

With 0% schema description coverage, the description provides meaningful context for all three parameters: explains node_id, value_id format, and value type constraints (number, bool, string). Fills in gaps beyond the schema's bare type definitions.

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

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

The description clearly states the tool sets a Z-Wave value and reports the outcome, with specific example value_id and return status. It distinguishes from sibling tools that handle associations, config parameters, or node info.

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

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

Implied usage for setting Z-Wave values, but no explicit guidance on when to use vs alternatives like zwave_set_config_parameter or when not to use. Prerequisites mentioned but no exclusions.

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

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

The description indicates a state change (exiting exclusion mode) but does not disclose side effects, prerequisites, or safety implications. With no annotations provided, the description carries the full burden; it is minimally adequate but lacks detail on what 'taking out' entails.

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

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

The description is a single, concise sentence with no excess words. Every part earns its place.

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

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

Given zero parameters, no output schema, and a simple action, the description is complete enough. It fully explains the tool's purpose without missing necessary context.

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

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

There are no parameters, and schema coverage is 100%. Per the rubric, 0 parameters yields a baseline of 4. No additional parameter meaning is needed.

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

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

The description clearly states the action: taking the controller out of exclusion mode. It uses a specific verb ('take') and resource ('controller out of exclusion mode'), which distinguishes it from sibling tools like zwave_begin_exclusion (which enters mode) and zwave_stop_inclusion (which stops a different mode).

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

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

The description implies usage context: when the controller is in exclusion mode and needs to exit. Although no explicit alternatives or when-not-to-use are stated, the purpose is clear enough for an agent to infer appropriate usage.

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

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

No annotations are provided, so the description carries full burden. It accurately states the behavior but does not disclose potential side effects, failure modes (e.g., if not in inclusion mode), or whether it is a safe operation.

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

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

The description is a single sentence that is front-loaded and contains no extraneous information. Every word is necessary and contributes to understanding.

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

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

For a simple zero-parameter tool with no output schema, the description is complete enough. It could mention that it only affects inclusion mode and not exclusion, but the name and context make that clear.

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

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

The tool has zero parameters and schema coverage is 100%, so the schema already fully documents the inputs. The description adds no additional parameter information, which is acceptable given no parameters. Baseline score 3 applies.

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

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

The description clearly states the specific action of taking the controller out of inclusion mode, with a clear verb and resource. It effectively distinguishes from sibling tools like zwave_begin_inclusion and zwave_stop_exclusion.

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

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

The description implies usage context by being the inverse of zwave_begin_inclusion, but it does not explicitly state when to use it, such as after adding devices or to cancel inclusion. No guidance on prerequisites or alternatives.

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

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

No annotations provided, so description carries full burden. It states the primary effect (stops rebuild) but does not disclose potential side effects, permissions needed, or safety profile.

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

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

Single sentence, no wasted words, front-loaded with action and target.

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

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

For a simple stop action with no parameters and no output schema, the description is complete and sufficient.

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

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

No parameters exist, schema coverage is 100%. Baseline for 0 parameters is 4, and description does not need to add more.

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

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

Description clearly states the action (stop) and the resource (in-progress network-wide route rebuild). Differentiates from sibling tools like zwave_begin_rebuilding_routes and zwave_rebuild_routes_status.

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

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

The description implies when to use (when a rebuild is in progress) but does not explicitly state when not to use or mention alternatives. However, context is clear.

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