Build and edit graphs and blocks.

Use the tools currently listed by your Kaitoi server. Decide first whether you are editing the headless working graph or an explicitly attached Studio tab; see Connect an AI client and Live Studio sessions.

#Review the connection before and after an edit

The example adds a connection between two existing nodes while leaving other graph content alone. Inspect node schemas and actual pin identifiers before connecting them. Submit the change against the observed revision, validate and reread the result. On a conflict, inspect the new state instead of blindly replaying the old mutation. Editing the graph does not execute it.

The source image and empty Resize Image result area remain unchanged when the wire appears. The wire joins the named image output to inputImage; the downstream result stays absent because connecting is not execution.

#Discover types, then identify instances

Use search_nodes with a focused query and small max_results. Request fields:["title","inputs","outputs"] when you need pins. This searches Kaitoi's catalog, not the web. Do not substitute a guessed type or display title for the returned operation identifier.

Read get_graph_state for placed nodes and connections. Follow page.nextCursor and preserve returned paging versions/snapshot context. get_node_info(node_id, fields:["inputs","outputs"]) inspects an actual instance's pins. An instance ID, node type, label and script path are different identities.

#Make a narrow graph change

add_node takes node_type and optional title, position and inputs. update_node changes the identified instance's input values. connect_nodes uses exact from_node, from_output, to_node, to_input; the corresponding disconnect and delete tools are distinct mutations. Read the current schema before depending on a write.

Attached mutations also need the explicit studio_session and current expected_revision. After each accepted change, inspect its receipt and refresh relevant state. validate_graph is a structural check, not execution or proof of useful media. Save and run are separate operations.

#Work with blocks or containers

get_studio_blocks reads blocks or stripes in the attached editor. Use the grouped studio_blocks_action tool with command:{action,arguments} for add_existing_node_as_block, move_block, or reorder_blocks. Adding an existing node as a block does not create or execute another node. Keep the original revision while paging.

Canvas containers and supported panel operations use studio_canvas_action with its closed command schema. Do not call an action string as if it were a standalone public MCP tool. A container is visual organization, not an execution shortcut.

#Choose the next operation explicitly

Discover: read exact types, instance IDs and pins, including bounded-page continuations. Edit: mutate the intended graph; attached changes use the current handle and editor revision. Next: validate, save, and execute are distinct operations. Grouped block/canvas action names are not standalone tools. Omitted values have dedicated readers instead of requiring a rerun.

#Read omitted values without repeating work

For omitted graph values, use get_graph_value with node_id, the returned expected_version, path and offsets. Follow nextOffset and nested omission paths; a short summary is not proof the underlying value is empty.

Use Project tools to persist work and Execution tools to run with the appropriate quote, consent and idempotency binding. Ask the agent to report edits, validation, save, execution and output inspection as separate outcomes.