| create_documentA | Create a new document in FreeCAD. Args:
name: The name of the document to create.
with_screenshot: Attach a screenshot of the result (default: no screenshot).
Returns:
A message indicating the success or failure of the document creation.
Examples:
If you want to create a document named "MyDocument", you can use the following data.
```json
{
"name": "MyDocument"
}
```
|
| cadA | Perform a CAD modeling operation (unified mutation tool). When a modeling session is active (session_start), successful operations
on the session's document are recorded as steps and can be rolled back
with session_rollback.
Feature ops take obj_name as the BASE object (for sketch/variables/
datum_plane/hull it names the NEW object) and params via obj_properties.
Every mutation runs in one FreeCAD transaction and is auto-audited for
connectivity. Call operation_help("<operation>") for the full parameter
reference of any operation — e.g. operation_help("sketch").
Args:
operation: The operation to perform.
doc_name: The document to operate on.
obj_type: Object type for create_object (e.g. "Part::Box").
obj_name: Base object name (new-object name for sketch/variables/
datum_plane/hull).
obj_properties: Properties/params for the operation.
ops: Operation dicts for batch.
stop_on_error: batch — stop at the first failed op.
description: Note recorded into the session step log.
with_screenshot: Attach a screenshot (default: none; use get_view).
Returns:
Result message (batch: JSON with per-op results), step number when a
session is active, and a screenshot only when requested.
|
| execute_code_asyncA | Execute Python code in FreeCAD without waiting for completion. Background thread, NOT the GUI thread: the code must NOT touch FreeCADGui,
the active view/selection, document objects, recompute, or save — for any
of that use execute_code instead (the safe default). Only for long pure
OCCT/CPU computations on already-fetched shapes. Use task_print(...) for
output (print() is not captured); poll with get_task_result(task_id).
Args:
code: Background-safe Python code to execute.
Returns:
A message with the task_id for polling via get_task_result.
|
| get_task_resultA | Get the status and captured output of a background task started by execute_code_async. Args:
task_id: The task ID returned by execute_code_async.
Returns:
A JSON object with status ("running" | "done" | "error"), output captured
via task_print(...), and the error traceback if the task failed.
|
| execute_codeA | Execute arbitrary Python code in FreeCAD. The code runs on FreeCAD's GUI thread with the full FreeCAD Python API
available (FreeCAD, FreeCADGui already imported; import Part/Draft/etc.
as needed). print() output is captured and returned.
Args:
code: The Python code to execute.
with_screenshot: Attach a screenshot after successful execution
(default: no screenshot).
Returns:
A message indicating the success or failure of the code execution, the
output of the code execution, and a screenshot only when requested.
|
| get_viewA | Get a screenshot of the active view. Args:
view_name: Camera view ("Isometric", "Front", "Top", ...).
width/height: Pixels; defaults to the viewport size.
focus_object: Object to focus on; default fits all objects.
Returns:
A screenshot of the active view.
|
| get_objectsA | Get all objects in a document. Args:
doc_name: The name of the document to get the objects from.
with_screenshot: Attach a screenshot of the document (default: no screenshot).
Returns:
A list of objects in the document, and a screenshot only when requested.
|
| get_objectB | Get an object from a document. Args:
doc_name: The name of the document to get the object from.
obj_name: The name of the object to get.
with_screenshot: Attach a screenshot of the object (default: no screenshot).
Returns:
The object properties, and a screenshot only when requested.
|
| list_documentsA | Get the list of open documents in FreeCAD. Returns:
A list of document names.
|
| session_startA | Start a modeling session bound to a document. While a session is active, every successful cad() mutation on the session's
document is recorded as a step backed by a FreeCAD transaction, enabling
session_rollback for trial-and-error modeling. execute_code steps are
recorded as non-atomic (rollback past them is blocked unless forced).
Args:
name: Optional human-readable session name.
create_document: Create the document first if it does not exist.
Returns:
Session info including session_id.
|
| session_statusA | Show the active session: step count, document state, next-step
suggestions, and risks (e.g. state drift from GUI edits, non-atomic steps). Returns:
JSON summary with a human-readable display_text.
|
| session_get_stepsA | Return all recorded steps and notes of the active session. Returns:
JSON list of steps (step_number, operation, description, params,
objects_after fingerprint, atomic flag, timestamp).
|
| session_rollbackA | Roll back the model to a previous step. Undoes the corresponding document transactions in FreeCAD and truncates
the step log. Removed steps go to a redo buffer (session_redo) until a new
cad() operation discards them.
Args:
to_step: Keep steps 1..to_step; undo everything after (0 = undo all).
force: Roll back even across non-atomic execute_code steps (risky:
undo may revert the wrong change).
Returns:
JSON with undone count, removed step numbers, post-rollback object
list, and a fingerprint consistency check.
|
| session_redoA | Redo n previously rolled-back steps (valid until a new cad() operation). Args:
n: Number of steps to restore (default 1).
Returns:
JSON with restored step numbers.
|
| session_add_noteA | Attach a human/LLM insight to the session log (not an operation step). Args:
note: The note content.
note_type: "observation" | "assumption" | "limitation" | "correction".
Returns:
The recorded note entry.
|
| session_pauseA | Pause the active session (persisted to disk; resume later). Returns:
Confirmation with the session_id.
|
| session_resumeA | Resume a paused/completed session from disk. Args:
session_id: The session to resume (see session_list).
Returns:
Session state; warns if the bound document is no longer open.
|
| session_listA | List all persisted sessions (most recently updated first). Returns:
JSON list with session_id, name, doc_name, status, step_count.
|
| session_completeA | Complete the active session: store the whole workflow as a reusable
pattern in the pattern store (recall later with recall_patterns), and
optionally save the document to disk. Args:
save: Save the FreeCAD document (.FCStd).
save_path: Target file path (saveAs); omit to save in place.
description: What this workflow builds (stored with the pattern).
tags: Retrieval tags for the pattern.
Returns:
JSON with pattern_id and save result.
|
| save_patternA | Store a reusable modeling pattern (code snippet or workflow) into the
pattern memory. Call this after a non-trivial approach worked. Knowledge hierarchy: ① your own knowledge first → ② recall_patterns when
unsure → ③ inspect_freecad for API details. Successful new approaches
should be stored back here.
Args:
name: Short pattern name (e.g. "flanged pipe via loft").
description: What it does and when to use it.
code: Optional Python snippet that implements it.
tags: Retrieval tags.
Returns:
The stored pattern_id.
|
| recall_patternsA | Search the pattern memory for workflows/code similar to your task. Use when your own knowledge is insufficient, before falling back to
trial-and-error. Patterns come from save_pattern and completed sessions.
Args:
query: Keywords describing the task (e.g. "boolean cut holes cylinder").
limit: Max results (default 3).
Returns:
JSON list of matching patterns with code/steps.
|
| operation_helpA | Full parameter reference for a cad() operation or assembly_session. Detailed docs live here (not in docstrings) to keep the tool list small
in context. Call with an operation name (e.g. "sketch", "hull",
"assembly_session") or none for the topic list.
|
| inspect_freecadA | Runtime introspection of the FreeCAD Python API (last-resort reference
when both your knowledge and recall_patterns are insufficient). Two modes:
- Object mode: pass doc_name + obj_name → the object's TypeId, settable
properties (with types), public methods, and docstring.
- API mode: pass dotted_name (e.g. "Part.makeLoft") → its docstring, or
the member list of a module/class.
Returns:
JSON with properties/members/docstring (compact, capped).
|
| measure_geometryA | Measure an object's Shape: volume, area, bounding box, center of mass,
element counts (solids/faces/edges/vertices), and validity (is_valid). Use after modeling steps to verify design targets quantitatively.
Args:
doc_name: Document name.
obj_name: Object name (must have a Shape).
Returns:
JSON with volume_mm3, area_mm2, bbox, center_of_mass, counts,
is_valid, shape_type.
|
| get_topologyA | List an object's faces or edges with semantic info for selection. Faces sorted by area, edges by length, vertices by distance from origin
(largest/longest/farthest first). Use the index/name (Face1, Edge3, ...)
in follow-up operations such as fillet, boolean, or sketching on a face.
Args:
element: "faces", "edges", or "vertices".
limit: Max entries returned (1-200, default 50).
offset: Skip this many entries (pagination).
Returns:
JSON with total, returned, and a faces/edges list (index, name,
type, area/length, center, normal for planar faces).
|
| check_interferenceA | Check the spatial relationship between two objects: distance and
intersection (common volume). Use to verify clearance or detect
collisions in multi-body configurations. Args:
doc_name: Document name.
obj_a: First object name.
obj_b: Second object name.
Returns:
JSON with distance_mm, intersects, common_volume_mm3.
|
| get_positioning_infoA | Get detailed global-coordinate spatial info for a specific face, edge, or vertex. Returns center, normal, axis, radius, start/end points etc. in GLOBAL
coordinates (already transformed by the object's Placement). Use this
instead of get_topology when you need precise positioning data for
alignment or assembly.
Args:
element: "face", "edge", or "vertex".
element_index: 0-based index (use get_topology to find indices).
Returns:
JSON with global center, normal, axis, radius, endpoints, and object Placement.
|
| align_shapesA | Move an object so one of its elements aligns with a target element. Modes: "touch" (face-to-face, normals opposing), "center" (centers
coincide, translation only), "axis" (cylindrical axes aligned).
offset: extra distance along target normal after alignment ("touch" only).
Args:
element / element_index: Element on the object to move.
target_element / target_element_index: Element on the target.
mode: Alignment mode: "touch", "center", or "axis".
offset: Extra distance along target normal (positive = away).
Returns:
JSON with success and the new Placement.
|
| get_anchorsA | List an object's assembly anchors in GLOBAL coordinates (read-only). Auto-derives standard anchors from the Shape (bbox_center/min/max, com,
axis_mid/start/end for the dominant cylindrical face, face0..2_center for
the largest planar faces) and merges explicit named anchors defined via
set_anchors (explicit wins on a name clash). Call this BEFORE placing
parts and plan mates from the returned numbers — never guess coordinates.
Returns:
JSON with anchors: {name: {pos, dir, source: "auto"|"explicit"}}.
|
| set_anchorsA | Define explicit named anchors on an object. Stored on the object (persists with the document) and follows Placement
moves. coord_frame="global" converts document coords to local via the
inverse Placement — use it whenever your source coordinates are global.
Args:
anchors: {name: {"pos": [x, y, z], "dir": [x, y, z] | null}}.
replace: Replace all existing anchors instead of merging.
coord_frame: "local" (stored as-is) or "global".
with_screenshot: Attach a screenshot of the result (default: no screenshot).
Returns:
JSON with anchor_count; records a modeling-session step.
|
| assembleA | Assemble parts by snapping named anchors together (ONE transaction). Each mate: {"obj", "anchor", "target", "target_anchor",
"mode": "center"|"touch"|"axis", "offset": float=0}.
Per-mate residuals (mm, plus degrees for touch/axis) are measured AFTER
the move; a mate over tolerance fails. For PERSISTENT joints use
assembly_session. Full semantics: operation_help("assemble").
Args:
mates: Non-empty list of mate dicts (see above).
tolerance: Max allowed post-move residual in mm (default 0.1).
stop_on_error: Abort and roll back at the first failed mate.
with_screenshot: Attach a screenshot (default: none).
Returns:
JSON with per-mate residuals and passed/failed counts.
|
| verify_assemblyA | Audit the document's spatial sanity (read-only, pure data feedback). Reports: floating (nearest neighbour farther than float_threshold mm),
interferences (common volume over interference_min_volume mm3), and
per-check pass/fail for requested anchor pairs {"obj", "anchor",
"target", "target_anchor", "tolerance"?}. Call after modeling/assembly
steps for a numeric health report instead of eyeballing screenshots.
Args:
checks: Optional anchor-pair distance checks (see above).
float_threshold: Nearest-neighbour gap (mm) for "floating" (default 1.0).
interference_min_volume: Minimum common volume (mm3) to report.
Returns:
JSON with floating/interferences/checks lists and a summary.
|
| assembly_sessionA | Independent assembly state machine with PERSISTENT joints (FreeCAD
Assembly workbench) — the mate-based counterpart to one-shot assemble. Workflow: start(ground=part) -> add_component(part) per part ->
mate(a, b, joint_type, trim?) per joint -> solve -> verify -> complete.
Joints persist in the document: move a parent part, call solve, and
children follow. rollback(to_step) un-does joints/trims and restores
placements atomically.
A mate ref is {"part": <name>} plus exactly ONE of face="FaceN" /
anchor=<name> / point=[x,y,z]. Full reference (operations, joint types,
trim semantics): operation_help("assembly_session").
|
