port_workflow

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

Annotations are minimal but the description goes beyond them by explaining that the tool swaps, rewrites, repicks, and retunes a workflow, and that it returns changes plus flags for human judgment. This gives the agent a realistic picture of the mutation behavior, though it stops short of spelling out every side effect (e.g., whether original workflow files are modified in place).

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 every sentence/segment pulls its weight: scope, concrete behavior, exclusion, alternatives, and output summary. There is no filler and the crucial 'CROSS-FAMILY ONLY' constraint 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 a tool with two parameters, no schema descriptions, and no enums, the description supplies most of what an agent needs: purpose, scope, help resources, and what the return value indicates. The main missing piece is a precise mapping/example of the two arguments, which the succinct schema alone does not provide, but the overall behavior is well-covered.

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 description coverage is 0%, so the description carries the burden for parameter meaning. It communicates that `target_family` is a model family (via the sdxl->flux example) and `workflow_id` is implicitly the workflow being ported, but it does not explicitly name either parameter or list valid families. It partially compensates but leaves the exact value-space and workflow_id semantics to the agent.

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 begins with a very specific scope, 'CROSS-FAMILY MODEL PORT ONLY', and gives a concrete example ('sdxl' -> 'flux'). It then enumerates exactly what the tool does: swaps loader topology, retunes CFG/steps/sampler/scheduler, swaps latent node class, and picks model files. This clearly distinguishes it from generic editing or diagnostic tools.

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 explicitly states when NOT to use it ('NOT for fixing missing/uninstalled nodes') and names the exact alternative tools to use instead ('diagnose_workflow + resolve_missing_nodes'). It also points to supporting tools for family knowledge ('get_model_guidance / get_instance_info'), leaving minimal inference for the agent.

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