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

With annotations marking the tool as destructive (destructiveHint: true) and not read-only, the description adds significant behavioral context: it emphasizes that all operations in one call are applied atomically (all or nothing), which is a key behavioral trait not in the annotations. It also mentions that delete_node cascades to connections and that connect requires disconnecting existing wires, which are important side effects. This goes beyond what annotations provide, warranting a 4.

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 appropriately sized for a complex toolcase. It is front-loaded with the core purpose ('Change the STRUCTURE of an existing flow'), followed by operational details. Each sentence earns its place—no filler, and it uses clear structuring with bullet-like examples for operations. The length is justified by the tool's complexity.

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?

Given the tool's complexity (5 operation types, multiple parameters), the description is remarkably complete. It covers prerequisites (get_flow, get_model), batch semantics, port constraints, model swapping behavior, and contrasts with the sibling tool. The schema itself provides the operation syntax, so the description adds the necessary context for an agent to call the tool correctly without additional research.

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?

The schema has 100% coverage, so baseline is 3. The description adds substantial value by explaining the semantic meaning of each operation type, the structure of the operations array, and the nuances like port indices being model-specific and that input ports take exactly one source. It also clarifies that new node IDs are server-assigned and reported back, which is not in the schema. This exceeds baseline, justifying a 4.

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 explicitly states 'Change the STRUCTURE of an existing flow in place' and enumerates the exact operations (add/remove nodes, swap models, connect/disconnect ports). It clearly distinguishes itself from update_flow, which only changes name, tags, and node parameters. This leaves no ambiguity about the tool's purpose.

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 explicit guidance on when to use this tool versus creating a new flow and names update_flow as the alternative for non-structural changes. It also instructs to read the flow with get_flow first to get node IDs and to use get_model for port layouts before wiring, which is critical for correct usage.

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