Batch: Run Tools
cad_batchExecute an ordered sequence of AutoCAD operations in a single round trip, binding earlier results as inputs to later steps for efficient automation.
Instructions
Execute an ordered list of tool calls in ONE round trip.
N calls collapse into one request/response pair, and bind lets a later
step reference an earlier step's result so handles never have to be echoed
back through the model.
steps=[
{"tool": "entity_create_line", "args": {...}, "bind": "edge"},
{"tool": "point_from_snap", "args": {"handle": "$edge", "snap": "mid"},
"bind": "mid"},
{"tool": "entity_create_circle","args": {"cx": "$mid.x", "cy": "$mid.y",
"radius": 4}},
]Successful steps report only their handle; pass verbose=True for the full result. Anything without a handle is returned whole.
VALIDATION runs first, always: an unknown tool, a schema-invalid argument or
a reference no earlier step binds refuses the whole batch before anything
executes. on_error governs run-time failures only. dry_run=True returns
that validation report and executes nothing.
ERRORS are typed, never text: each failed step carries error.kind - one of
unsupported (with the backend capability), invalid_args, refused, failed,
unknown_tool, unresolved_ref, denied, malformed_step.
ATOMICITY is reported, not assumed. Read the atomicity block: on the
headless backend rollback restores a full document snapshot; on live AutoCAD
it sends an UNDO whose landing AutoCAD never confirms. The default
on_error="stop" claims nothing and is exact on both.
NOT CALLABLE from a batch: the raw command/LISP escape hatches, and cad_batch itself. Call those directly.
For a few hundred entities of the same kind, entity_batch_create is denser still (no per-step tool name) - and it can be one step of a cad_batch.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| steps | Yes | Ordered steps. Each: {'tool': <tool name>, 'args': {...}, 'bind': <optional name>}. 'bind' names this step's result so a later step can reference it as '$name' (its handle), '$name.field' or '$name.list.0'. '$$' is a literal dollar sign. | |
| dry_run | No | Validate every step against its tool's real JSON Schema and execute nothing. | |
| verbose | No | Return each step's full result instead of just its handle. | |
| on_error | No | stop (default): halt at the first failure, keep what already ran. continue: run every step. rollback: open a checkpoint first and undo on failure - read the returned `atomicity` block for what that is worth on this backend. | stop |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||