zwave_add_association

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.