ComfyUI version, OS, VRAM, queue length, and render-relocation readiness of the connected instance. Call first. The relocation block reports whether COMFYUI_MOUNT_DIR is set and writable - if it isn't, renders can't be handed to the user automatically, so surface that to them before spending a render.

One-shot setup diagnostic for a fresh install or a sandboxed client (Cowork/ Desktop/Code): can I reach ComfyUI, can I hand finished renders back to the user (COMFYUI_MOUNT_DIR), is the partner-node key present. Unlike get_instance_info it never raises - a down instance is a failed check, not an error - so run it first when a render can't be delivered or the instance seems unreachable. Returns {ok, checks:[{name, ok, detail}], hint?}; ok gates on ComfyUI being reachable, relocation is a soft check surfaced via hint.

Search node classes installed on the instance (name/display-name/description).

Use category to narrow (e.g. 'loaders', 'conditioning', 'sampling', 'ImpactPack'). Set detail=True to fold each hit's full input/output schema in-line (use a specific query + small limit) so you can skip the follow-up get_node_info.

Full input/output schema for node classes: slot names, types, widget defaults/ranges, combo choices, tooltips.

BATCH your lookups: pass class_types=["A", "B", "C"] to fetch many in ONE call (returns {class_type: schema}) instead of one call per node. A single class_type=... still returns that one node's schema directly.

Long combo lists (fonts, model files...) are capped at 24 choices by default; to browse the rest, pass choices_filter='substring' (case-insensitive, applies to every combo of the node) and/or max_choices=N to raise the cap.

Model files installed on the instance. folder picks the model type: checkpoints, loras, vae, diffusion_models, text_encoders, upscale_models, controlnet, embeddings, ... (unknown folder -> the full available list). search filters filenames (case-insensitive substring). metadata_for (a .safetensors filename from this folder) returns its embedded training metadata instead - base model + top trigger tags, key for using a LoRA.

ComfyUI's bundled workflow templates - the best starting points for current models (they ship with every release). Seed one via create_workflow(template=...). Narrow with search= (matched against title/description/models); the catalog is ~450 templates, far more than one response should carry.

Start a workflow: blank, or seeded from a bundled template (recommended for current model families - see list_templates). Returns workflow_id + node summary.

Workflows already saved in ComfyUI's workflow browser (userdata). Use a returned name with import_workflow(name=...) to load one WITHOUT pasting its JSON. search filters names (case-insensitive substring).

Find saved workflows that already DO what you're about to build, so reuse beats rebuilding from scratch. Describe the goal in words - model, subject, resolution, extras - e.g. "flux portrait at 1024 with a face detailer", and get back a few RANKED, compact matches: family, base model, resolution, feature tags (detailer / upscale / lora / controlnet / inpaint / img2img), and why each matched. Profiles are extracted from the saved JSON, so hand-built workflows are covered too. Returns summaries only, never full graphs - load the one you want with import_workflow(name=...). Prefer this over importing+inspecting each result of list_workflows.

Import an existing workflow into the session. EITHER paste JSON as workflow_json (UI format with nodes/links, or API format {id: {class_type, inputs}}), OR pass name to load one straight from ComfyUI's workflow browser (see list_workflows) - preferred for large files, no pasting needed. Use for beautifying/diagnosing/porting outside work.

Compact view of a session workflow: nodes (id/class/title/widgets), links, groups - plus full inner node/wiring detail for any subgraph definitions (newer bundled templates package their graph as a subgraph).

Apply batched edits. Each op is a dict with 'op' plus:

• {"op": "add_node", "class_type": str, "title"?: str, "widgets"?: {name: value}}

• {"op": "remove_node", "node_id": int}

• {"op": "connect", "from_node": int, "from_output": str|int, "to_node": int, "to_input": str}

• {"op": "set_widget", "node_id": int, "input": str, "value": any}

• {"op": "set_title", "node_id": int, "title": str}

• {"op": "set_mode", "node_id": int, "mode": int} # 0 normal, 2 mute, 4 bypass

All six have a definition-scoped twin taking an extra "definition_id", for editing inside a subgraph definition: add_node_to_definition, remove_node_from_definition, and connect/set_widget/set_title/ set_mode_in_definition. A malformed op reports its own required keys.

Layout/group ops (no definition twin): set_pos {node_id, pos:[x,y], size?:[w,h]}; add_group {title, node_ids:[int,...], color?}; set_group {group_id, title?, node_ids?, color?}; remove_group {group_id}. Groups are addressed by member node_ids - bounding comes from their own extents. organize_workflow re-lays out and re-groups everything, so run these AFTER it, not before.

Slot/widget names come from get_node_info. Virtual classes: Note/MarkdownNote take one widget 'text'; Reroute/PrimitiveNode take none at add - connect a PrimitiveNode to a widget input to mirror its type, then set_widget 'value' (+ 'control_after_generate' for number/combo, to advance each run).

Ops apply in order; a failing op stops the batch (graph unchanged past that point). Widget values and link types are checked live - "force": true on set_widget/add_node/connect overrides; on connect it also lets a frontend-only input (no /object_info entry - rgthree switches, dynamic collectors) be wired by creating the socket.

Result is a compact delta (applied ops + changed nodes); pass summary=true or call inspect_workflow for the full graph.

THE finishing step: auto-layout into pipeline stage bands, colored groups, human titles, green highlights on user-editable knobs, and markdown guidance notes (model-family aware, two registers: 'touch this' vs 'leave alone'). Run after wiring is done and before save_workflow. Idempotent.

MUTATES the session workflow in place - the applied block in the result summarizes the layout/group/note changes; inspect_workflow or export_workflow_json shows the full reorganized graph.

Readability/wiring lint: unlabeled prompts, missing groups/notes, orphan nodes, unconnected required inputs, overlapping nodes, misaligned resolution (when a family with a known alignment requirement is detected). Empty list = clean.

Validate against the LIVE instance: node classes installed, widget values in range, combo/model-file values actually present (with closest-match suggestions), required inputs connected. Fix errors before run_workflow.

Deep-check an old/broken workflow and propose fixes: everything from validate_workflow PLUS Comfy Registry resolution for missing custom-node classes (which pack provides them, how to install). Apply fixes via edit_workflow, or port_workflow for model-family moves.

CROSS-FAMILY MODEL PORT ONLY (e.g. 'sdxl' -> 'flux'): swaps loader topology when needed, retunes CFG/steps/sampler/scheduler and technique nodes (FaceDetailer etc.) from family knowledge, swaps latent node class, picks installed model files. NOT for fixing missing/uninstalled nodes - that's diagnose_workflow + resolve_missing_nodes. Returns changes + flags for anything that needs your judgment. Families: get_model_guidance / get_instance_info.

Queue the workflow and (by default) wait for completion. Returns status, node errors on failure, output file refs, any non-file return values (data_outputs: generated text, paths a save node wrote), and an inline preview thumbnail so you can SEE the result (view_output fetches full size). wait=False returns {status: queued, prompt_id} - poll get_run_status. Prove a workflow works before saving/delivering.

Text-only caller (no image input)? Pass return_preview=False - the result then carries a file path instead of a thumbnail if save_dir/COMFYUI_MOUNT_DIR is set.

roll_seeds=True (default) mirrors the browser: every seed/PrimitiveNode set to randomize/increment/decrement is re-rolled and persisted before submit - the raw /prompt API never does, so headless runs repeat forever. False re-runs the stored values.

allow_invalid=True submits despite local validation errors (ComfyUI is the final judge; use it if a valid graph is wrongly blocked). save_dir (or the configured COMFYUI_MOUNT_DIR) relocates every finished output file - images, video, audio alike - into a folder the caller can reach, returning saved_paths. Needs finished files (wait=True); a background run relocates later via save_output(prompt_id=...).

front: None (default) refuses to queue when >=2 prompts are already pending and returns {status: queue_busy} so the USER can choose; True runs next (pending jobs untouched); False waits at the back of the line.

confirm_spend: partner/API nodes charge the user's account per submit, so a graph containing one is gated - pass True only after they have agreed.

LONG RENDERS: a timeout cancels the caller's wait, not the ComfyUI job. Submit wait=False, front=False, then poll get_run_status(prompt_id) until success/error/partial and call save_output. prompt_id survives in manage_queue(status).draftsman_submitted if your session dies mid-poll.

Fetch a rendered image so you (and the user) can SEE it - refs come from run_workflow/get_run_status outputs. Downscaled to max_dim px to keep the conversation light; max_dim=None for full resolution.

Copy a finished render out of ComfyUI's output tree into a folder the caller (e.g. a Claude Desktop / Cowork sandbox) can reach. ComfyUI's save nodes only write inside its own output/ dir and reject absolute paths, so a render must be relocated before it can be presented or edited.

Pass prompt_id (relocates every output FILE of that finished job - images, video, audio) OR an explicit filename (+subfolder/type, as reported in a run's outputs). dest_dir defaults to COMFYUI_MOUNT_DIR; dest_filename renames a single file. Returns {saved_paths, dest_dir}.

Polling tool for runs queued with run_workflow(wait=False). For long/paid renders, see run_workflow's long-render pattern. Status of a run queued with run_workflow(wait=False): queue position, live step progress while sampling, and outputs (+ error details) once finished.

Upload a source image into ComfyUI's input folder so LoadImage can use it (img2img / inpaint / ControlNet). Exactly one of image_path (local file) or image_base64. mask_for={filename, subfolder?, type?} uploads this as a MASK for that already-uploaded image instead.

Inspect or manage the instance's run queue: status (queued prompt ids; draftsman_submitted maps the ones THIS session queued to their workflow_id - the rest are someone else's job), interrupt (stop the running prompt), clear (drop ALL pending), delete (drop given pending prompt_ids), free (release cached VRAM/RAM; unload_models=True also unloads models). clear/delete/ interrupt are gated when they'd discard prompts this session didn't queue; confirm=True once the user agrees.

Save the workflow (UI format, with layout/groups/notes) into ComfyUI's workflow browser + the session dir. Run organize_workflow first - this is the deliverable. REFUSES to save with validation errors unless allow_invalid=True. Never overwrites by default: a taken name saves as ' (draftsman)' (result.renamed_from says so); overwrite=True replaces deliberately.

The workflow as JSON: 'ui' (shareable, opens in the editor, keeps layout & notes) or 'api' (for POST /prompt automation).

Find which installable node packs provide these node class names (official Comfy Registry). THIS is the tool for missing/uninstalled nodes (port_workflow is for model-family moves, not missing nodes). Returns pack ids, repos, and install hints. Installing custom nodes runs third-party code - surface the choice to the user.

Search the Comfy Registry for node packs by capability (e.g. 'face detailer', 'wildcards', 'video interpolation').

Tuned settings for a model family: sampling (CFG/steps/samplers), native resolutions, technique blocks (face_detailer, hires_fix...), prompt style notes. Variant-aware: pass model_filename so turbo/lightning/distill overrides apply. Includes any learned overlay from past research plus a research directive - for brand-new models, verify online and record_learning what you find. A fit block appears only when this GPU can't comfortably hold the model.

Persist researched settings so FUTURE sessions start smarter. updates uses the guidance shape, e.g. {"sampling": {"cfg": {"default": 3.5}}} or {"techniques": {"face_detailer": {"denoise": 0.4}}}. source = URL/model page. Any family name works; for a NEW family also include a "detect" block so it's auto-recognized next session: {"detect": {"checkpoint_patterns": ["mymodel"]}, "loader": "unet_clip_vae"}.

A "sources" list teaches organize_workflow's Models note where to download each file - it never invents a URL, so this is the only way one appears: {"sources": [{"match": ["mymodel_v1.safetensors"], "what": "checkpoint", "url": "https://..."}]}. Verify the URL resolves before recording it.