z2m_manage_group

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

Annotations indicate mutability (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds valuable behavioral context: removing a group does not affect devices, removal fails if a member is unreachable unless force is set, and with force the device retains membership internally. This goes beyond annotation basics, though it doesn't cover every action's 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?

The description is three sentences, front-loaded with the primary actions. Each sentence adds value: the group benefit, the removal caveat, and the workflow. No wasted words, and the structure guides the agent from understanding to action.

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 has multiple actions and no output schema, but the description provides the core purpose, the critical force-removal edge case, and workflow tips. It omits details like 'new_name is required for rename' and 'device is needed for member actions', but the schema covers those. Given the complexity, the description is sufficiently complete for safe 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 high (83%), with descriptions for most parameters. The description adds context for 'force' (removal behavior) and implies the need for 'new_name' (rename) and 'device' (member actions). However, it doesn't systematically explain each parameter, so it meets the baseline but doesn't greatly exceed it.

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 function: 'Create or remove groups, rename them, and add or remove device members.' It uses specific verbs and identifies the resource (Zigbee groups), distinguishing it from sibling tools like z2m_list_groups and z2m_set_state by explicitly referencing them.

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 provides direct guidance on when to use this tool versus alternatives: 'Use z2m_list_groups to inspect groups first, and z2m_set_state to control a group once created.' It also explains the benefit of groups (multicast responsiveness), which helps the agent decide when group management is appropriate.

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