Execute build123d Python code in the persistent session. Errors include automatic fix hints — read them before retrying. Use show(shape, name) to register named objects (name defaults to 'shape'); show() immediately prints volume and face count confirming the shape is non-empty. After any boolean operation (-, +, &) call measure() to confirm it succeeded (check topology.faces). named_face(shape, name) is a built-in helper: named_face(box, 'top') returns the highest-Z face, 'bottom'/'front'/'back'/'left'/'right' work similarly.

Render model. Auto-detects 3D vs 2D inputs: solids go through the VTK tessellation path; 2D shapes (Sketches, Compounds of edges, dimensioned drawings composed via build123d.drafting) go through the ezdxf+matplotlib raster path. Use this to review your dimensioned drawings the same way you review 3D parts. format: 'png' (raster, default), 'svg' (HLR line drawing — works without a display, no shading but precise edges), 'dxf' (HLR line drawing as DXF — the standard 2D CAD interchange format; use when you need projected polylines as parseable geometry rather than as a raster, e.g. to draw an annotated overlay on top of an accurate base layer instead of redrawing the shape by hand), or 'both' (returns the PNG and SVG together — useful when you want shaded depth cues plus crisp edge geometry). If the raster path fails (typically headless host with no display backend) and format='png', the server falls back to SVG automatically. Renders confirm appearance, not geometry — verify boolean operations with measure() before rendering. direction: top, front, side, iso. objects: comma-separated names or name:color pairs e.g. 'u_frame:blue,roller:red' (default: all, auto-coloured). quality: standard, high. clip_plane: x, y, z to slice; clip_at: absolute world coordinate along that axis (default: each mesh's midpoint). azimuth/elevation: camera rotation in degrees applied after the direction preset. save_to: optional file path; for format='both' the PNG and SVG are written as <save_to>.png and <save_to>.svg. mode: render-pipeline selector. 'auto' (default) detects 2D vs 3D from shape content (no solids + flat in Z = 2D). '2d' forces the 2D pipeline (errors if any shape is 3D). '3d' forces the 3D pipeline (errors if every shape is flat 2D). Useful when the auto-detection picks wrong (e.g. a Compound with both a 2D Sketch and a 3D solid silently routes to 3D). The actual path used is reported in the response as 'Rendered via pipeline.' colors: optional dict mapping object names (e.g. 'bracket') and special layer keys (_dims, _labels) to colour names like 'red'/'blue' or '#aabbcc'. Overrides the per-object name:color syntax and the default blue dimension colour. Use this when you need fine-grained colour control for presentation diagrams (different parts in different hues, distinct dimension colour, etc.). Only affects PNG/SVG output for 2D drawings; ignored for 3D solids and DXF. label_objects: when true, each named object from show() is labelled at its centroid in the PNG. highlights: optional list of specific entities to label, e.g. [{"object": "bracket", "type": "edge", "index": 5, "label": "hinge_edge"}]; type is 'face', 'edge', or 'vertex' and index matches shape.faces()/edges()/vertices() position. The referenced object must already be registered with show() and included in the rendered set. Labels are PNG-only; SVG output is unlabelled.

Measure a shape and return a complete geometric summary: volume (mm³), surface area (mm²), topology (face/edge/vertex counts), bounding box with per-axis size and center, volumetric center of mass, 6-component inertia tensor (Ixx/Iyy/Izz/Ixy/Ixz/Iyz), and a face-type inventory classifying every face as Plane/Cylinder/Cone/Sphere/Torus/BSpline with area and type-specific params (e.g. cylinder diameter and axis). Prefer measure over render_view for verifying geometry — numbers are unambiguous. topology is the fastest confirmation that a boolean operation succeeded: a failed cut leaves face/edge/vertex counts unchanged. object_name: named object from show() (default: current shape).

Spatial relationship between two named shapes. Returns JSON with clearance (mm), status (one of: apart, touching, containing, interpenetrating), containment (a_in_b, b_in_a, or neither), and intersection_volume / a_volume_outside_b / b_volume_outside_a for overlap quantification. Reads clearance differently per status: apart=gap, containing=wall thickness from inner surface to outer hull (use this to verify a pocket fits inside a plate), touching=0, interpenetrating=0 (check intersection_volume + a_volume_outside_b for the wall-piercing case). Single call replaces the older clearance + interference combination. object_a, object_b: names from show().

Compute cross-sectional areas at evenly spaced planes along an axis. Returns a list of {position, area} pairs. axis: X, Y, or Z (default Z). num_slices: number of planes (default 10, minimum 2). Useful for detecting internal voids, wall-thickness variation, or verifying that a shape's cross-section profile matches a reference. object_name: named object from show() (default: current shape).

Export model. format: step, stl, dxf, svg, or comma-separated list e.g. 'step,stl' or 'dxf,svg'. 3D shapes (solids) export to step/stl; 2D shapes (Sketches and dimensioned drawings composed via build123d.drafting) export to dxf/svg. Mixing 2D and 3D formats for the same shape errors with a clear message. object_name: named object from show(), '' to export all named shapes as a combined assembly (default: current shape). STEP exports carry the session names as labels — single-object exports use the object_name, '' exports produce a Compound labelled 'assembly' with each child labelled by its show() name. Downstream CAD tools (FreeCAD, Fusion) will see the structured assembly with named bodies. Use dxf for engineering-drawing handoff to other CAD tools; svg for embedding in docs/wikis.

Check whether two named objects (from show()) intersect. Returns interferes (bool), volume (mm³ of overlap), and bounds of the interference region.

Search the part library. query: keywords matched against name, description, tags, category (empty returns all). Returns name, category, description, tags, and full parameter specs including types, defaults, and descriptions.

Load a named part from the library into the session. name: part name from search_library. params: optional JSON object of parameter overrides e.g. '{"od": 8.0, "length": 20.0}' — unspecified params use their defaults. The part is registered as a named object and becomes current_shape.

Save a named checkpoint of the current geometric state (current_shape and the show() object registry). The Python variable namespace is NOT saved — only geometry. Call this before risky experiments so you can restore known-good geometry without re-running all prior execute() calls.

Restore geometric state from a previously saved snapshot (current_shape and the show() registry). The Python variable namespace is NOT restored — execute() calls made after the snapshot are still in scope, but current_shape and all show() objects revert to what they were at snapshot time. Raises an error if the snapshot name does not exist.

Compare two snapshots by geometry metrics (volume, topology, bounding box). snapshot_b defaults to current session state if omitted. format: 'text' (default, human-readable) or 'json' (structured, for programmatic consumption).

Return a structured JSON snapshot of the current session: current_shape metrics, all named objects (replaces list_objects) with geometry stats, snapshot names, and a variables summary of the Python namespace (type + volume for shapes, type + length for collections, type + value for scalars). Use this to orient after a reset, restore, or multi-step build to confirm what geometry and variables are active.

Verify that render and export dependencies are working. Tests PNG render (VTK), SVG render (build123d HLR), STEP export, and STL export with a trivial shape. Returns JSON with ok/error per capability. Run at session start if you suspect a missing dependency.

Clear the current session back to empty state, including all snapshots.

Compare two named shapes (from show()) by geometry metrics: volume delta, bbox delta, topology delta (faces/edges/vertices), and center offset. Useful when you have an intended design and a reference/test shape and want to verify they match — or to quantify how a modification changed the geometry.

Import a STEP (.step/.stp) or STL (.stl) file as a named object in the session. path: absolute or relative path to the file. name: name to register the shape under (defaults to the filename stem). The shape becomes both the named object and the current_shape. Returns volume, topology, and bounding box of the imported shape. After importing, use render_view() to visualise the shape, measure() for geometry queries, or shape_compare() to diff against a show() object. Note: STL imports produce a shell (volume=0) rather than a solid — render_view and measure still work, but interference() and boolean operations require a solid. If you have both the original built shape and an imported copy in session.objects, render the imported one by name (e.g. objects='mypart') to avoid Z-fighting artifacts from two co-located shapes.

Given an error message from execute(), return targeted fix suggestions for common build123d mistakes: wrong Location syntax, missing .part, CadQuery idioms, blocked imports, degenerate boolean results, fillet edge selection, and more. Pass the full error string from execute() or last_error().

Return details of the last failed execute() call: exception type, message, and (for runtime and syntax errors) line number and a 5-line excerpt around the failing line. Security errors include a message but no line/excerpt. Returns {"error": null} if the last execute() succeeded or no execute() has failed yet. Call this immediately after an execute() error to get the exact failing line — much faster than re-reading the submitted code.

Return the build123d-mcp server version.

Return guidance on how to use these tools effectively. Call this at the start of a session or whenever unsure which tool to reach for.