Swap an operator's type in place

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

The description goes far beyond the destructiveHint annotation by detailing the internal procedure: snapshots wires+params, deletes old node, creates new node, re-applies params, rewires connectors. It also discloses fail-forward behavior and return fields, providing a rich behavioral model not covered by annotations.

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 dense but well-structured: core action, procedure, failure handling, and return value are each given a sentence. Every sentence contributes essential information for a complex destructive operation.

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 complex and has no output schema, but the description explains the full lifecycle and return structure including failed_inputs/outputs and warnings. This is sufficient for an agent to understand what will happen and interpret results.

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?

All 3 parameters have schema descriptions (100% coverage), so the baseline is 3. The description reinforces preserve_parameters behavior but adds no new syntactic details beyond the schema; it mentions parameter preservation and dropped_parameters in the return context.

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 opens with a specific verb+resource: 'Change an operator's TYPE while preserving its name, position, incoming + outgoing wires, and any parameters that exist on the new type.' This clearly distinguishes it from sibling create/delete/update tools by emphasizing in-place type swap with preservation.

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 the use case—when you need to change an operator's type without losing connections—but does not explicitly name alternatives or state when not to use it. It lacks comparative guidance like 'use this instead of delete+create'.

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