nvr_move_channel

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

With no annotations, the description carries the full burden and does well: it discloses that credentials/settings survive the move, that occupied targets are refused rather than overwritten, and that before/after rows are returned. The 'same gates as nvr_remove_channel' cross-reference is a weak spot since the agent must look up that other tool to learn the actual gating conditions.

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 tight sentences: purpose first, then the failure mode, then gating and return shape. No filler, no repetition of the schema, and the most decision-relevant fact (occupancy refusal) 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?

For an unannotated mutation tool this covers the essentials: preservation semantics, refusal behavior, shared gating, and return shape, and an output schema exists so return detail is not required. The gaps are the unexplained expected_uuid and the external reference for the actual gate conditions.

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 only 25%, with only confirm_write documented. The description conveys old_id/new_id roles contextually (source binding, target slot) and the occupancy constraint on new_id, but says nothing about the required expected_uuid, leaving an unexplained required parameter in both schema and description.

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

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

States a specific verb and resource ('Move a binding to another channel slot') and even names the underlying firmware call (chm_mod_dev_chn), so the agent knows exactly what operation this performs. It also implicitly separates itself from destructive siblings like nvr_remove_channel by noting credentials and settings are preserved.

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

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

It gives a concrete precondition ('Refuses if new_id is occupied') and defers to a sibling's prerequisites ('Same gates as nvr_remove_channel'), which is useful routing context. However, it never states when to prefer this over a remove-then-add sequence or any other sibling, so usage is only implied rather than prescribed.

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