> ## Documentation Index > Fetch the complete documentation index at: https://docs.parashell.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Document and object tools > Document lifecycle, object CRUD, groups, parts library insertion, appearance, patterns, and recompute. Document lifecycle, object CRUD, groups, parts library insertion, appearance, patterns, and recompute. Tool count: `15`. Client note: `ctx` is injected by the MCP server and is not supplied as a user argument. ## `add_to_group` Signature: ```python theme={null} add_to_group(doc_name: str, group: str, members: list[str]) -> list[TextContent | ImageContent] ``` Descriptor: ```text theme={null} Move existing objects into a group. Group and members accept either object names or take_snapshot uids. Args: doc_name: Document containing the objects. group: Group name or uid. members: List of object names / uids to move into the group. ``` ## `create_document` Signature: ```python theme={null} create_document(name: str) -> list[TextContent] ``` Descriptor: ```text theme={null} Create a new document in Parashell. Args: name: The name of the document to create. ``` ## `create_group` Signature: ```python theme={null} create_group(doc_name: str, name: str, members: list[str] | None = None, parent: str | None = None) -> list[TextContent | ImageContent] ``` Descriptor: ```text theme={null} Create an App::DocumentObjectGroup and optionally populate it. Groups are a lightweight container - useful for organizing a flat object list into Base / Column / PlanetSystem.Earth / etc. and for applying a single placement to a whole sub-assembly. Members and parent accept either object names or take_snapshot uids. Args: doc_name: Document to create the group in. name: Name for the new group. members: Optional list of objects to move into the group at creation. parent: Optional parent group/container the new group should live inside. ``` ## `create_object` Signature: ```python theme={null} create_object(doc_name: str, obj_type: str, obj_name: str, transaction_id: str, analysis_name: str | None = None, obj_properties: dict[str, Any] = None) -> list[TextContent | ImageContent] ``` Descriptor: ```text theme={null} Create a new object in Parashell. Object type starts with 'Part::', 'Draft::', 'PartDesign::', or 'Fem::'. Every model edit must run inside an open transaction. Open one with transaction_create first, pass its id here, then transaction_apply to persist or transaction_cancel to roll back. Args: doc_name: The name of the document to create the object in. obj_type: The type of the object to create (e.g. 'Part::Box', 'Part::Cylinder', 'Draft::Circle'). obj_name: The name of the object to create. transaction_id: Id of the open transaction returned by transaction_create. analysis_name: Optional FEM analysis container name to add the object to. obj_properties: The properties of the object to create. ``` ## `create_objects` Signature: ```python theme={null} create_objects(doc_name: str, items: list[dict[str, Any]], recompute: bool = True) -> list[TextContent | ImageContent] ``` Descriptor: ```text theme={null} Batch-create many objects in a single call. Each entry in 'items' has the same shape as create_object's parameters: { "Name": "Tier1", optional, auto-generated when omitted "Type": "Part::Box", required, Parashell TypeId "Properties": { optional, applied via the same setter "Length": 50, "Width": 50, "Height": 10, "Placement": {"Base": {"x": 0, "y": 0, "z": 100}} }, "Analysis": "MyFEMAnalysis" optional FEM container } The whole list is processed inside a single GUI task, so the recompute happens once at the end (set recompute=False to defer entirely). Errors on individual items don't abort the batch - they are reported in the 'errors' array with the item index, attempted name, and message. Args: doc_name: Document to create objects in. items: List of object specs. recompute: Whether to recompute the document at the end. Default True. ``` ## `create_pattern` Signature: ```python theme={null} create_pattern(doc_name: str, source_object: str, kind: Literal['circular', 'linear', 'grid'], count: int, params: dict[str, Any] | None = None, copy_mode: Literal['duplicate', 'link'] = 'duplicate', name_prefix: str | None = None, recompute: bool = True) -> list[TextContent | ImageContent] ``` Descriptor: ```text theme={null} Place N copies of a source object in a circular, linear, or grid pattern. Pattern kinds and their params: - "circular": {"center": [x, y, z], default [0, 0, 0] "axis": [x, y, z], default [0, 0, 1] "total_angle_deg": 360, 360 = full circle, e.g. 90 for quarter sweep "full_circle": true, when true, count divides 360 exactly "include_first": true} when false, first instance is skipped - "linear": {"direction": [x, y, z], default [1, 0, 0] "spacing": 50.0, distance between adjacent copies in mm "length": 200.0} alternative to 'spacing': total span - "grid": {"u_axis": [1, 0, 0], row direction "v_axis": [0, 1, 0], column direction "cols": 4, columns per row "rows": 3, number of rows "spacing_x": 50, "spacing_y": 50} count is ignored when rows*cols is given copy_mode controls how the copies are produced: - "duplicate": creates an independent Part::Feature for each copy with a deep-copied shape. Best for permanent geometry like gear teeth, planet arms, sun rays. - "link": creates an App::Link to the source for each copy. Edits to the source propagate to every copy. Best for orbital tracks or instances that should share a master. Source can be referenced by name or take_snapshot uid. Args: doc_name: Document containing the source. source_object: Object name or uid. kind: "circular", "linear", or "grid". count: Number of copies. For circular full circles this becomes the division count. params: Pattern-specific params (see above). copy_mode: "duplicate" or "link". name_prefix: Optional prefix for new object names. Defaults to "__". recompute: Whether to recompute after placement. Default True. ``` ## `delete_object` Signature: ```python theme={null} delete_object(doc_name: str, obj_name: str, transaction_id: str) -> list[TextContent | ImageContent] ``` Descriptor: ```text theme={null} Delete an object from a Parashell document. Every model edit must run inside an open transaction. Pass the id from transaction_create; deletion is reversible via transaction_cancel until transaction_apply persists it. Args: doc_name: The name of the document containing the object. obj_name: The name of the object to delete. transaction_id: Id of the open transaction returned by transaction_create. ``` ## `edit_object` Signature: ```python theme={null} edit_object(doc_name: str, obj_name: str, obj_properties: dict[str, Any], transaction_id: str) -> list[TextContent | ImageContent] ``` Descriptor: ```text theme={null} Edit an object in Parashell. Every model edit must run inside an open transaction. Pass the id from transaction_create; the change is rolled back by transaction_cancel or persisted by transaction_apply. Args: doc_name: The name of the document containing the object. obj_name: The name of the object to edit. obj_properties: The properties to update on the object. transaction_id: Id of the open transaction returned by transaction_create. ``` ## `get_parts_list` Signature: ```python theme={null} get_parts_list() -> list[TextContent] ``` Descriptor: ```text theme={null} Get the list of parts available in the Parashell parts library addon. ``` ## `insert_part_from_library` Signature: ```python theme={null} insert_part_from_library(relative_path: str, transaction_id: str) -> list[TextContent | ImageContent] ``` Descriptor: ```text theme={null} Insert a part from the Parashell parts library addon. Every model edit must run inside an open transaction. Pass the id from transaction_create; persist with transaction_apply or roll back with transaction_cancel. Args: relative_path: Relative path of the part within the parts library directory. transaction_id: Id of the open transaction returned by transaction_create. ``` ## `list_documents` Signature: ```python theme={null} list_documents() -> list[TextContent] ``` Descriptor: ```text theme={null} Get the list of currently open documents in Parashell. ``` ## `recompute_document` Signature: ```python theme={null} recompute_document(doc_name: str | None = None, force: bool = False, clear_redo: bool = False, soft_timeout: float | None = None, async_threshold: float | None = None) -> list[TextContent | ImageContent] ``` Descriptor: ```text theme={null} Recompute a document object-by-object in dependency order. Re-evaluates parametric features along the topological dependency graph. Useful after editing properties or geometry through execute_code or other tools where a recompute has not been triggered automatically. The response includes per-document health: how many objects were recomputed, how many remain unhealthy after the pass, and the full health record for each unhealthy object - including state flags, must_execute, and shape diagnostics (is_null, is_valid, is_closed, volume, area, vertex/edge/face/solid counts, and bounding box). Use check_objects for an on-demand scan that does not trigger a recompute. Args: doc_name: Document name to recompute. If omitted, recomputes every open document. force: Pass True to recompute every object regardless of touched state. clear_redo: Pass True to clear the document's undo/redo stack before recomputing. soft_timeout: Seconds before the pass gives up and returns a partial-progress report naming the object it stalled on. None uses the configured default. async_threshold: Seconds before the pass detaches into a background job and returns a job_id to poll with recompute_status. None uses the configured default. ``` Response shape: ```text theme={null} status is one of "complete", "timed_out", "running", or "error". - complete: results carries the per-document health report described above. - timed_out: soft_timeout was hit; stuck_on names the object it stalled on and results holds the partial report. - running: async_threshold was hit; job_id is returned for recompute_status polling while the recompute continues in the background. - error: error carries the failure message. ``` Operational notes: * The initial call always returns before the bridge transport deadline: the effective async cutoff is bounded below the RPC timeout, so a long recompute detaches into a background job instead of raising a transport timeout. * soft\_timeout may exceed the transport deadline; it governs the background job, which you observe through recompute\_status rather than the initial call. * Poll a returned job\_id with recompute\_status instead of blocking. ## `recompute_status` Signature: ```python theme={null} recompute_status(job_id: str) -> list[TextContent | ImageContent] ``` Descriptor: ```text theme={null} Poll the status of an asynchronous recompute_document job. Pass the job_id returned by recompute_document when a recompute exceeded the async threshold. Reports progress (objects done, current object), the stalled object on a soft timeout, or the final per-document result when complete. Args: job_id: The job identifier returned by recompute_document. ``` Response shape: ```text theme={null} status is one of "running", "timed_out", "complete", or "error". - running: objects_recomputed / objects_total progress plus current_object. - timed_out: stuck_on names the object the recompute stalled on. - complete: results carries the final per-document health report. - error: error carries the failure message, or the job_id was not found. ``` ## `remove_from_group` Signature: ```python theme={null} remove_from_group(doc_name: str, group: str, members: list[str]) -> list[TextContent | ImageContent] ``` Descriptor: ```text theme={null} Remove objects from a group without deleting them. Args: doc_name: Document containing the objects. group: Group name or uid. members: List of object names / uids to remove from the group. ``` ## `set_appearance` Signature: ```python theme={null} set_appearance(doc_name: str, targets: list[str], properties: dict[str, Any]) -> list[TextContent] ``` Descriptor: ```text theme={null} Apply a single set of ViewObject properties to many objects at once. Replaces the per-object setattr loop for ShapeColor / Transparency / Visibility / DisplayMode. Targets accept object names or take_snapshot uids. Recognised properties: - ShapeColor / LineColor / PointColor: [r, g, b] or [r, g, b, a] in [0, 1]. - Transparency: int 0..100. - LineWidth: float. - PointSize: float. - Visibility: bool. - DisplayMode: "Shaded", "Wireframe", "Flat Lines", "Hidden line", "Points", "As is". - Any other ViewObject property exposed by the underlying object - set verbatim if it exists, otherwise reported in 'errors'. Args: doc_name: Document containing the targets. targets: List of object names or uids. properties: Dict of view properties to apply to every target. ``` ## `part_design_polar_pattern` Signature: ```python theme={null} part_design_polar_pattern() -> list[TextContent] ``` Descriptor: ```text theme={null} run polar pattern using its axis property ``` Runs the Part Design polar-pattern command. Programmatic `PartDesign::PolarPattern` objects use the case-sensitive `Axis` property. `ReferenceAxis` is not a PolarPattern property.