@@ -13,7 +13,7 @@ Envoy works with any MCP client, including:
 
 ## Capabilities
 
-Envoy exposes **40+ MCP tools** organized into categories:
+Envoy exposes **46 MCP tools** organized into categories:
 
 | Category | Examples |
 |----------|---------|
@@ -27,6 +27,7 @@ Envoy exposes **40+ MCP tools** organized into categories:
 | **Embody Integration** | Tag, save, query externalizations |
 | **TDN Export/Import** | Export/import network snapshots as JSON |
 | **Code Execution** | Run arbitrary Python in TouchDesigner |
+| **Batch Operations** | Combine multiple tool calls into a single request |
 
 For the complete tool reference, see [Tools Reference](tools-reference.md).
 
@@ -43,7 +44,7 @@ You can regenerate these files at any time with `op.Embody.InitEnvoy()` (MCP + A
 ## Key Features
 
 - **Zero setup** — Embody auto-installs all dependencies (`mcp`, `uvicorn`, etc.) when Envoy is first enabled
-- **Auto-restarts** on port change
+- **Auto-restarts** on port change or crash (exponential backoff, up to 3 attempts)
 - **Localhost-only** binding (127.0.0.1) for security
 - **Piggybacked logs** — every MCP response includes recent log entries
 - **30-second timeout** per operation to prevent hangs
@@ -1,6 +1,6 @@
 # Tools Reference
 
-Envoy exposes 40+ MCP tools for interacting with TouchDesigner. All tools use the standard MCP protocol and can be called by any compatible client.
+Envoy exposes 46 MCP tools for interacting with TouchDesigner. All tools use the standard MCP protocol and can be called by any compatible client.
 
 ## Operator Management
 
@@ -42,6 +42,7 @@ Envoy exposes 40+ MCP tools for interacting with TouchDesigner. All tools use th
 | Tool | Parameters | Description |
 |------|-----------|-------------|
 | `get_op_position` | `op_path` | Get operator position, size, color, and comment |
+| `get_network_layout` | `comp_path`, `include_annotations?` | Get positions of ALL operators (and annotations) in a COMP in one call. Returns bounding_box. Use instead of repeated `get_op_position` calls |
 | `set_op_position` | `op_path`, `x?`, `y?`, `width?`, `height?`, `color?`, `comment?` | Set operator position, size, color (`[r,g,b]` floats 0-1), or comment |
 | `layout_children` | `op_path` | Auto-layout all children in a COMP |
 
@@ -133,6 +134,29 @@ These tools run locally on the STDIO bridge script, not inside TouchDesigner. Th
 !!! info "Bridge architecture"
     Claude Code connects to Envoy via a STDIO bridge script (`.claude/envoy-bridge.py`). The bridge translates between Claude Code's STDIO transport and Envoy's HTTP endpoint. It handles MCP protocol handshake locally when TD is down, so these meta-tools are always available. See [Architecture](architecture.md) for details.
 
+## Batch Operations
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `batch_operations` | `operations` | Execute multiple operations in a single request. Reduces latency and token overhead |
+
+`operations` is a list of `{"tool": str, "params": dict}` objects. Each entry maps to an existing tool name and its parameters. Stops on first error.
+
+**When to use**: 3+ calls to the same tool type (positioning, connecting, parameter setting, flags). Use `execute_python` instead when you need conditionals, loops, or computed values between operations.
+
+**Example** — position 4 operators + connect them in one call:
+```json
+{"operations": [
+  {"tool": "set_op_position", "params": {"op_path": "/project1/noise1", "x": 400, "y": 0}},
+  {"tool": "set_op_position", "params": {"op_path": "/project1/comp1", "x": 800, "y": 0}},
+  {"tool": "set_op_position", "params": {"op_path": "/project1/level1", "x": 1200, "y": 0}},
+  {"tool": "set_op_position", "params": {"op_path": "/project1/null1", "x": 1600, "y": 0}},
+  {"tool": "connect_ops", "params": {"source_path": "/project1/noise1", "dest_path": "/project1/comp1"}},
+  {"tool": "connect_ops", "params": {"source_path": "/project1/comp1", "dest_path": "/project1/level1"}},
+  {"tool": "connect_ops", "params": {"source_path": "/project1/level1", "dest_path": "/project1/null1"}}
+]}
+```
+
 ## MCP Prompts
 
 | Prompt | Parameters | Description |
 
@@ -17,7 +17,7 @@ Embody is three tools working together — *forward velocity*, *lateral velocity
 
     ---
 
-    An embedded [MCP](https://modelcontextprotocol.io/) server with **45 tools** that lets Claude Code, Cursor, and Windsurf talk directly to your live TouchDesigner session. Say what you want — operators, connections, parameters, extensions, fixes — and watch it happen. Idea → network in seconds.
+    An embedded [MCP](https://modelcontextprotocol.io/) server with **46 tools** that lets Claude Code, Cursor, and Windsurf talk directly to your live TouchDesigner session. Say what you want — operators, connections, parameters, extensions, fixes — and watch it happen. Idea → network in seconds.
 
     [:octicons-arrow-right-24: Setup Envoy](envoy/setup.md)
 
@@ -68,11 +68,11 @@ You describe what you want. The AI works with your live network — operators, c
 | | Feature | Description |
 |---|---------|-------------|
 | :material-sync: | **Automated Externalization** | Tags COMPs and DATs, keeps external files in sync — auto-restores from disk on project open |
-| :material-robot: | **Envoy MCP Server** | 42 tools connect AI assistants to your live TD session |
+| :material-robot: | **Envoy MCP Server** | 46 tools connect AI assistants to your live TD session |
 | :material-file-document: | **TDN Format** | Export/import operator networks as diffable JSON for code review and snapshots |
 | :material-keyboard: | **Keyboard Shortcuts** | Double-tap ++lctrl++ to tag, ++ctrl+shift+u++ to save — minimal friction |
 | :material-cog: | **Parameter Tracking** | Automatically detects parameter changes and marks COMPs dirty |
-| :material-test-tube: | **30 Test Suites** | Comprehensive automated testing with 587 test methods |
+| :material-test-tube: | **41 Test Suites** | Comprehensive automated testing framework |
 | :material-note-text: | **Structured Logging** | Multi-destination logging with file rotation, ring buffer, and MCP access |
 
 ---