get_scene | Return the full scene graph. | — | { nodes, rootNodeIds, collections } |
get_node | Fetch a node by id, whole, with what the scene decides for it beside its stored fields (a wall's or ceiling's resolvedHeight and heightIsExplicit, a wall's resolvedThickness, a door's or window's resolvedOpening, a level's or floor plate's displayName), its ancestors parent first, and the scene materials its finishes use; a node its schema rejects comes back as stored, nothing derived. | { id } | { node, ancestorIds, missingChildIds?, materials? }, or refusal node_not_found |
find_by_type | Find everything of one type: nodes of a kind (any core or plugin kind), items of a category, lights, and typed parts inside authored objects, windows and doors; narrowed by level, parent, zone (on its level, by plan point, holes left out) or import source id (provenance.refs[].id or legacy metadata.sourceIds, exact or prefix); without a type, every node the filters match. Each result is the node's id, name, kind, level and parent, with its metadata and provenance (one over 1 KB named in omitted). | { type?, levelId?, parentId?, zoneId?, sourceId?, sourceIdPrefix?, limit? } | { type?, count, nodes, parts, results[], truncated?, hint? }, at most limit (200) results listed; refusals unknown_type, level_not_found, node_not_found, zone_not_found, not_a_zone |
list_levels | List every building's levels in floor order with their role (storey, roof-only, support), their standing against the ground line (gradeStanding, isGroundLevel) and, per building, the level at grade. | — | { activeSceneId, activeLevelId, levelCount, occupiedStoryCount, supportLevelCount, roofLevelIds, groundLevels[], levels[] } |
get_level_summary | Compact summary of one level: role, counts, walls with openings, zones with areas, slabs, ceilings, items, stairs, roofs, and everything else by type. Omit levelId for the lowest storey. | { levelId?, level? } | { levelId, role, counts, walls, zones, slabs, ceilings, items, stairs, roofs, other } |
get_walls | Walls on a level with length, stored and resolved height, and child doors/windows. Each wall reports type { id, label } or null; wallTypes lists available preset and project types. wallType reads standard (when absent), railing or curtain. | { levelId?, level? } | { levelId, walls[] } |
get_zones | Room/zone polygons with holes, areas (holes taken out), bounds and floor choices. Reports roomType (room/porch/deck/patio), floor.drop in metres, porchFraming (auto, postSize, postSpacing in metres, beamSize, postCount, beamCount; null with no intent), and decking (boardSize, gap in metres, direction), matching set_zone_intent. | { levelId?, level? } | { levelId, zones[] } |
get_site | The site a building stands on, in its level coordinates (a lot with no building yet, in site coordinates): the lot and its area with the footprint a house usually covers (30 to 45%), the buildable area inside the setbacks with its centre, area, each edge's frontage and depth and its front edge, the street side with the lot's frontage and depth, north, the ground (sloped, read flat or not read), address, parcel and zoning, whether the lot is the new-project placeholder, and the footprint's fit and yards. | { building?, site? } | { siteId, buildingId, pose, lot, placeholder, buildable, street, ground, northDeg, address, parcel, zone, footprint, others, summary }; refusals no_site, building_required, site_not_found, not_a_site, building_not_on_site |
place_building | Stand a building on its site by moving the building node only (walls keep their level coordinates): its footprint, the outline about to be drawn or the walls standing, centred in the buildable area or at the yards given; a house standing keeps its rotation unless rotationDeg is given, one with no walls yet is squared to the street. | { building?, outline?, yards?: { front?, rear?, left?, right? }, rotationDeg? } | { buildingId, position, rotationDeg, moved, footprint, yards, fit, overhang, movedWithIt?, message }; refusals no_site, needs_footprint, other_building_on_site, no_street, yards_conflict, yards_infeasible, building_required |
measure | Distance between two nodes' world-space reference points (hosted doors, windows and items resolved through their host; every node kind); area when applicable. | { fromId, toId } | { distanceMeters, fromPoint?, toPoint?, areaSqMeters?, units: 'meters' } |
view_scene | Look at the finished building, every storey and the roof, from a viewpoint the agent picks (a compass side, a side as seen from the house's street, a street-height eye, a photo's camera, square-on, from above), in the scene's own light or a photo's, and get the picture back, with the photo's crop beside it when a region is given. interior: { zoneId } stands inside a room at eye height (1.6 m by default), a step in from a corner and looking across it; interior: { levelId } looks inside one floor: the other floors and its roofs and ceilings left out, everything on it (walls, openings, furniture) cut at 0.65 of the storey's height, for the picture only. Pictures are 1920 × 1200 unless maxPx (64 to 1920) asks for a smaller longest side. The server has no renderer: the host's sceneViews renders it, through an editor tab open on the project or a renderer of the host's own. Read-only. | { target?, interior?, from?, elevation?, eyeHeight?, position?, fov?, projection?, camera?, lighting?, maxPx?, photo? } | image content plus { status, camera, size, tab, capturedAt }; refusals view_unavailable, no_project, which_building (a street side, no target, buildings on several sites), no_current_camera (camera: 'current': the server has no view of the person's), camera_and_viewpoint (a camera with a viewpoint of the agent's own), photo_crop_unavailable, interior_level_invalid, interior_hidden, interior_transform_unsupported, interior_target_elsewhere; on the hosted server editor_tab_required, editor_tab_hidden, editor_tab_busy (a tab open but busy or still loading, no link: wait a few seconds and call again, do not ask the user), editor_tab_timeout (a tab claimed the view and then stopped answering); what the refusal says about opening the editor follows the person's "Agents may open the editor for me" setting (ask first, allow, never) |
search_assets | Search the host's item library (the built-in list on a standalone server), several queries in one call; a query matches name, id, category or tags. Each query lists its best matches first, at most limit (24 by default, up to 60); a cut query says how to narrow it, one that finds nothing gets a hint to build the item with add_object. The text result carries each item's id, name and placement facts; the structured result adds its category. | { queries: [{ query, category? }], limit? } | { groups: [{ query, total, truncated, results[] }], total, hint? }; refusal no_catalog |
design_brief | The request read as a brief, once: axes (the request read axis by axis: action, size, form, facade, pieces, openings, style, materials, dressing, each bounded — the person's own words as quote, the reading in a short line, pieces as a minimum or exact — or open with a design statement of at least three words; an absent axis is refused axis_missing, except form and facade, which are optional, a quote not in the person's message in the chat axis_quote_not_in_request, an open axis without its design axis_open_without_design; an open form states its massing, an open facade its treatment, an open form owes rooms; over MCP an axis quote is required and not compared), the tenth axis source (open, catalog, brand with its brand, existing), a vision for what is open, the dressing of the rooms layer by layer (beyond: textiles, light, windows, walls, floor, plants, objects, small furniture, each pieces or { none: why }; an open dressing axis owes 6 of the 8, beyond_too_thin, a bounded one owes none, and the named pieces read as a minimum do not bound it, dressing_bounded_by_minimum; handed back as dressing), the person's words that set a source other than open (sourceQuote, required, naming the brand, the catalog or what is already there; not compared here) and, with an open source, technical equipment and plants placed from the catalog by its tags (furniture is made). Furnishing follows a brief: place_items, furnish_room, place_in_room (the catalog's) and add_object, place_design (made), inside run_batch too, are refused before one with design_brief_required.search_assets and view_assets stay open too. Source open opens the made pieces, places technical equipment and plants from the catalog and keeps furnish_room closed (brief_source_open); catalog, brand and existing open the catalog's tools, and creation for what it lacks. A batch checks each call under its own onRefusal policy. The brief is the session's: a scene load or clear starts another, and the next design_brief replaces it. Changes nothing in the scene. | | |
view_assets | Pictures of 1 to 6 catalog items by id, each labelled with its size, category and the names of its paintable surfaces (its model's slot_<id> materials; paint takes one as role), returned as image content. The picture and surfaces are read before the call (a hosted server fetches and resizes the thumbnail to at most 512 px; a standalone server's built-in list has no host to fetch from, so it answers sizes and says it has no picture). Opt-in: nothing changes when it is not called. | { ids: string[] (1 to 6) } | { items: [{ id, name, category, dimensions, surfaces, picture, unavailable? }], shown, note? } plus one labelled image per item shown; refusals unknown_asset, no_catalog |
search_materials | Search or browse the material library, several queries in one call: words match as the library writes them (timber is wood, render is stucco), shades and surfaces; a query without words lists a kind, a surface or the whole library by name. A search lists 12 at a time and a browse 150, a long one saying how many more (more) and the offset that lists them (next). Reads Pascal's library and the materials the host registered (the editor registers its library; this server registers none). Read-only. | { queries: [{ query?, kind?, surface?, offset? }] } | { groups: [{ query?, kind?, surface?, offset?, results: [{ ref, label, kind, surfaces, color? }], missing?, more?, next? }] } |
paint | Give walls, slabs, ceilings, roofs and every other part with surfaces (columns, fences, doors, windows, stairs, blocks, cabinets, shelves…) a finish in one call, as the editor's Paint does: a colour (the nearest library colour), a library: or scene: ref, a native material kept as a scene material (reused when an equal one exists), or erase. role picks the surface (a wall's exterior/interior faces, by its rooms or else its stored sides, refused when rooms stand on only part of a face, a slot by name, a roof's top/edge/wall, or its fascia, the fascia and rake boards, held by every segment; a glazed roof's glazing-frame, glazing-glass or glazing-solid, and without a role its frame and solid panels, the glass kept); a roof shows one finish per surface, so a segment's finish goes on its roof and a roof's clears its segments' own; a wall face is painted whole, over its room's wall finish, its painted parts keeping theirs (named in note). | { targets[], role?, color?, material?, materialName?, erase? } (one finish) | { ok, painted[], finish, materialId?, material?, createdMaterial?, note?, achieved }; refusals target_not_found, unknown_role, side_unknown, unknown_material, materials_unavailable, not_paintable |
create_story_shell | Create one level-owned story shell from a footprint: the perimeter walls. The floor plate and ceiling are derived from the enclosed rooms; createSlab / createCeiling / slabElevation are recorded as room intent. Use once per story. | { levelId, footprint, wallHeight?, wallThickness?, createSlab?, createCeiling? } | { wallIds, zoneIds, slabId, ceilingId, createdIds } |
create_stair | Create a straight, L or U stair as the editor's stair tool does: from a level to the next one above (made when there is none), owning the floor openings it cuts, or to no level (toLevelId: null).(x, z) is the middle of the bottom riser, rotation in degrees (0 climbs toward +Z). | { x, z, levelId?, toLevelId?, rotation?, layout?, turn?, lowerSteps?, width?, length?, height?, steps?, railingMode?, railingStyle?, railingMaterial? } | { stairId, segmentIds, upperLevelId, createdUpperLevel, layout, stepCount, rise, length, footprint, arrival, slabHoleCut, openingIds? }; refusals roof_level, not_above, level_not_found, slab_not_found / ceiling_not_found, slab_not_on_level / ceiling_not_on_level, stair_layout, stair_layout_required, no_level_above |
measure_stair | Read actual risers, going at the walking line, slope, uniformity, arrival, headroom against floors/ceilings/stair bodies, and design-target diagnostics. | { stairId, available?: { width, length } } | { measurements, layouts } |
fit_stair | Fit uniform risers or replace the chain with a straight/L/U preset with width-sized landings or quarter-turn winders in one undoable edit. | { stairId, fitRun?, targets?, layout?, turn?, width?, landingDepth?, turningStrategy?, innerGap?, walkingLineOffset?, division? } | { stairId, measurements } |
create_roof | Cap the top storey with a roof over its footprint (its walls' outline, else its floor plates, else its rooms), one segment per rectangle, or over a rectangle of your own (width, depth, center). The roof goes on the building's roof level above the storey (reused, the empty level directly above when it is the only one, else made and named Roof) and stands on the storey's wall tops; the hand roof tool follows the same rule. roofType: "barrel" arches each segment (depth is the span, barrelRise at most half of it, barrelSegments facets from 4 to 32); roofSystem: "glazed" builds a gable, straight shed or barrel roof as panes and framing, set by glazing (see glazed roofs). | { levelId? (or level), roofType?, roofSystem? ('standard' | 'glazed'), glazing?, barrelRise?, barrelSegments?, pitch? (degrees, or rise over run: "6:12"), overhang? (the eaves' reach past the walls in plan), wallHeight?, wallThickness?, width?, depth?, center?, materialPreset?, fasciaHeight?, fasciaMaterialPreset?, name? } | { roofId, roofLevelId, createdRoofLevelId, coveredLevelId, segmentIds, roofType, achieved }; refusals storey_above, roof_exists, building_required (several buildings, no level named), storey_without_building, conflicting_level, no_levels, no_rooms, rectangle_incomplete, unknown_material (the roof's or the fascia's finish) |
move_roofs_to_roof_level | Move the roofs a storey holds on its own walls to the level the roof rule gives them (the building's roof level over the top storey, made when there is none; the storey above a lower one), as a roof's panel does by hand. Each roof stands where it stood, segments, finishes and id kept. For projects built before the roof level, when verify_scene reports roof_mixed_in_storey. | { levelId } | { roofIds, roofLevelId, createdRoofLevelId, achieved }; refusals level_not_found, no_roof_on_walls |
create_room | Create a room from a polygon: one wall per edge (an edge a wall already runs along reuses it) and the room zone; its doors and windows can be declared in the same call by edge (wallIndex) and t, each placed with add_door's and add_window's rules or listed in skippedOpenings. The floor plate and ceiling are derived, never authored. outdoor: true makes a terrace: separators (the editor's Separator: a room boundary with no wall) where no wall runs, no walls of its own, no ceiling. Where every edge of the polygon already runs along a wall (nothing to build) and the polygon fits the room those walls make, the call names that room instead of stacking a second zone on it, and zoneId is that room's. If that room has a name of its own (not a number the editor gave it: any name but the editor's "Room N", whoever gave it) the call is refused (room_named_by_person, worded with the room's name): pass rename: true only when the person asked for the rename; otherwise ask them. A room is never renamed unasked, and the same name over it says there is nothing to create. A terrace (outdoor: true) drawn over a fully walled courtyard names it outdoor. The refusal is agent-only: the editor's own room tool behaves as before (a person sees and names rooms directly). | { name, polygon, levelId?, color?, wallHeight?, wallThickness?, outdoor?, rename?, doors?, windows? } | { zoneId, slabId, ceilingId, wallIds, reusedWalls, areaSqMeters, doorIds, windowIds, skippedOpenings? }; refusals cannot_enclose, outdoor_room_overlap, room_named_by_person |
add_door | Add a door to a straight wall at t (0..1 along it) with the editor's placement rules, or a passage with no leaf (openingKind: "opening"); it slides to stay on the wall and reports clamped.doorType, style and the outline (openingShape) match a reference, code builds what they cannot, nodeId rebuilds a scripted door, and the rare sillHeight lifts it off the floor or, negative, lowers it to a floor sunk beside the wall (down to the wall's bottom). | `{ wallId, t?, | |