tvh_plan_channel_merge

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

Annotations already cover readOnly/idempotent/destructive, yet the description adds substantive behavior: sources are disabled rather than deleted, certain source types block the plan, name/region mismatches require explicit verification, and the plan_id expires in 15 minutes. That is exactly the extra context annotations cannot express.

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 and scope, and each subsequent sentence carries distinct information (side effects, blockers, verification, TTL, no mutation). Minor redundancy between the leading 'Preview' framing and the trailing 'does not change configuration' restatement.

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 planning tool with rich annotations and an output schema, the description covers side effects, blockers, follow-up usage, and result lifetime. An agent has everything needed to decide whether to call it and how to act on its return.

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% and the description never names target_uuid, source_uuids, or allow_name_mismatch directly. It does implicitly convey merge semantics (target retained, sources unioned) and that mismatch handling requires explicit opt-in, which partially compensates but leaves the parameter-to-argument mapping to inference.

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 ('Preview an explicit channel merge') plus the exact semantics of the merge: target name/number retained, mappings unioned. It also distinguishes itself from the mutating sibling by naming apply_maintenance_plan as the consumer of its output, so an agent can tell plan-vs-apply apart without opening a schema.

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?

Gives clear context for use: this is the dry-run step whose 15-minute plan_id feeds apply_maintenance_plan, and it explicitly does not change configuration. It also states conditions that block a plan (DVR references, bouquet-managed sources). No explicit pointer to an alternative merge/consolidation tool, so it stops short of full when/when-not routing.

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