Prefer semantic operations
For construction, prefer tools such as create_story_shell, create_room, add_door, add_window, create_roof, furnish_room, and place_item. Use apply_patch only when no semantic tool expresses the requested edit and you have inspected the relevant node schema or an existing node of the same type.
For stairs, call measure_stair before changing proportions: it reports actual risers, walking-line going, arrival, uniformity, headroom and layout alternatives without editing the scene. Use fit_stair only for an explicit sizing or layout change; it applies uniform risers in one reversible edit. fitRun: true also fits flight runs or arc sweep. A straight, l or u layout replaces the flight chain; turningStrategy: "winder" uses quarter-turn winders with configurable walking-line offset and division. Measure again after fitting.
Stair targets are design preferences in meters (maxRiserHeight, minimumGoing, targetGoing, minimumHeadroom), not a building-code certification. Defaults are 0.18, 0.25, 0.28 and 2 respectively. Headroom checks cover modeled floors, ceilings and stair bodies; missing or unsupported obstacles can still require inspection. Inspect the connected server's contracts before calling these tools.
When those tools and the catalog cannot reproduce something faithfully (custom columns, a porch, lanterns, a garage door, a vaulted or tray ceiling), build it with add_object: a plain three.js module, with the naming conventions its description lists for paint slots, parts, lights, cutouts and clips. Edit it by passing its nodeId. Servers without a script host answer scripts_unavailable. The hosted server builds scripts in the user's open Pascal editor tab; when no tab has the project open it answers editor_tab_required with an editorUrl: give the user that link, wait until they say it is open, then repeat the same call. To count or locate things by what they are, including typed parts inside authored objects, use find_by_type. To group elements of any kind into a named set the editor lists (all the lights, the windows, the kitchen cabinetry), use edit_collection, starting from a template when one fits; list_collections reads them back.
Pascal uses meters. X and Z are floor-plan axes; Y is vertical. Tool fields that accept measurements may also accept strings such as "6 ft" or "180cm", but report final spatial values in meters and retain the user's original units when useful.
Preserve unrelated nodes. Before a bounded edit, identify the target IDs with find_nodes, get_node, get_level_summary, get_walls, or get_zones. After the edit, identify the actual changed IDs from tool output or a before/after read.
Validate and persist
After a meaningful edit:
- Call
validate_scene for schema validity.
- Call
verify_scene for practical scene issues.
- Resolve relevant reported issues or state them plainly.
- Call
save_scene with saveMode: "draft" for working progress. Use saveMode: "checkpoint" only for a meaningful milestone or when the user requests a durable version.
- Call
get_project_status after the save and use its returned editorUrl, version, node count, and graph hash as the handoff evidence.
An HTTP success, a tool response with isError: false, or a non-empty scene ID does not by itself prove the requested result. For example, export_glb currently returns a structured not_implemented status in the open-source headless MCP server. Report that as unsupported; do not claim a file exists.
Final response
Give the user a compact result with:
- status: succeeded, partial, failed, or pending;
- project and scene identity available from tool output;
- requested result and changed node IDs, if any;
- checks run and unresolved issues;
- persistence evidence: save mode, version, graph hash, and node count when returned;
- the exact
editorUrl returned by Pascal;
- unsupported or unverified deliverables;
- one supported recovery or next action when incomplete.
For tool selection and failure recovery, read references/tool-workflows.md. The examples are synthetic and contain no production credentials or private project data.