---
name: mcp-tools-reference
description: "MUST READ before first MCP tool call in a session. Complete Envoy tool catalog with parameters and usage."
---
<!-- Generated by Embody/Envoy - Do not remove this comment -->

# Envoy MCP Tool Reference

## Operator Management

| Tool | Parameters | Description |
|------|-----------|-------------|
| `create_op` | `parent_path`, `op_type`, `name?` | Create a new operator (e.g., `baseCOMP`, `noiseTOP`, `textDAT`, `gridPOP`) |
| `create_extension` | `parent_path`, `class_name`, `name?`, `code?`, `promote?`, `ext_name?`, `ext_index?`, `existing_comp?` | Create a TD extension: baseCOMP + text DAT + extension wiring |
| `delete_op` | `op_path` | Delete an operator |
| `copy_op` | `source_path`, `dest_parent`, `new_name?` | Copy operator to new location |
| `rename_op` | `op_path`, `new_name` | Rename an operator |
| `get_op` | `op_path` | Get full operator info (type, family, parameters, inputs, outputs, children) |
| `query_network` | `parent_path?`, `recursive?`, `op_type?`, `include_utility?` | List operators in a container |
| `find_children` | `op_path`, `name?`, `type?`, `depth?`, `tags?`, `text?`, `comment?`, `include_utility?` | Advanced search using TD's `findChildren` |
| `cook_op` | `op_path`, `force?`, `recurse?` | Force-cook an operator |

## Parameter Control

| Tool | Parameters | Description |
|------|-----------|-------------|
| `set_parameter` | `op_path`, `par_name`, `value?`, `mode?`, `expr?`, `bind_expr?` | Set value, expression, bind expression, or mode |
| `get_parameter` | `op_path`, `par_name` | Get value, mode, expression, bind info, label, range, menu entries, default |

## DAT Content

| Tool | Parameters | Description |
|------|-----------|-------------|
| `get_dat_content` | `op_path`, `format?` | Get DAT text or table data (`"text"`, `"table"`, `"auto"`) |
| `set_dat_content` | `op_path`, `text?`, `rows?`, `clear?`, `confirm_wipe?` | Full-replace DAT content. **Wipe guardrail**: calls that would leave the DAT empty (`text=""`, `rows=[]`, or `clear=True` with no content) are refused unless `confirm_wipe=True`. **For partial edits to text DATs, prefer `edit_dat_content`** -- it sends only the changed substring (much cheaper for large DATs). Use `set_dat_content` for tables, full rewrites, or intentional wipes. |
| `edit_dat_content` | `op_path`, `old_string`, `new_string`, `replace_all?`, `confirm_wipe?` | Surgical text edit on a DAT -- replaces `old_string` with `new_string`. Mirrors Claude Code's Edit tool: `old_string` must appear exactly once by default; widen with surrounding context for uniqueness, or pass `replace_all=True` to replace every occurrence. Token-efficient -- only the changed substring crosses the wire. **Text DATs only**; tables go through `set_dat_content(rows=...)`. Refuses empty `old_string`, identical strings, and edits that would wipe the DAT (unless `confirm_wipe=True`). |

## Operator Flags

| Tool | Parameters | Description |
|------|-----------|-------------|
| `get_op_flags` | `op_path` | Get all flags |
| `set_op_flags` | `op_path`, `bypass?`, `lock?`, `display?`, `render?`, `viewer?`, `current?`, `expose?`, `allowCooking?`, `selected?` | Set one or more flags |

## Operator Positioning & Layout

| Tool | Parameters | Description |
|------|-----------|-------------|
| `get_op_position` | `op_path` | Get 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 position, size, color (`[r,g,b]` 0-1), or comment |
| `layout_children` | `op_path` | Auto-layout all children in a COMP |

## Annotations

| Tool | Parameters | Description |
|------|-----------|-------------|
| `create_annotation` | `parent_path`, `mode?`, `text?`, `title?`, `x?`, `y?`, `width?`, `height?`, `color?`, `opacity?`, `name?` | Create annotation (`"annotate"`, `"comment"`, `"networkbox"`) |
| `get_annotations` | `parent_path` | List all annotations with properties and enclosed operators |
| `set_annotation` | `op_path`, `text?`, `title?`, `color?`, `opacity?`, `width?`, `height?`, `x?`, `y?` | Modify annotation properties |
| `get_enclosed_ops` | `op_path` | Get ops enclosed by annotation, or annotations enclosing an op |

## Performance Monitoring

| Tool | Parameters | Description |
|------|-----------|-------------|
| `get_op_performance` | `op_path`, `include_children?` | Get CPU/GPU cook times, memory, cook counts |
| `get_project_performance` | `include_hotspots?` | Get project-level FPS, frame time, GPU/CPU memory, dropped frames, active ops, GPU temp. Optional hotspot ranking of top N COMPs by cook time |

## Connections

| Tool | Parameters | Description |
|------|-----------|-------------|
| `connect_ops` | `source_path`, `dest_path`, `source_index?`, `dest_index?`, `comp?` | Wire two operators. `comp=True` for COMP connectors |
| `disconnect_op` | `op_path`, `input_index?`, `comp?` | Disconnect an input |
| `get_connections` | `op_path` | Get all input/output connections |

## Code Execution

| Tool | Parameters | Description |
|------|-----------|-------------|
| `execute_python` | `code` | Execute Python in TD. Set `result` variable to return values |

## Introspection & Diagnostics

| Tool | Parameters | Description |
|------|-----------|-------------|
| `get_td_info` | _(none)_ | TD version, build, OS, Envoy version |
| `get_op_errors` | `op_path`, `recurse?` | Get error and warning messages for op and children |
| `exec_op_method` | `op_path`, `method`, `args?`, `kwargs?` | Call a method on an operator |
| `get_td_classes` | _(none)_ | List all Python classes in `td` module |
| `get_td_class_details` | `class_name` | Get methods, properties, docs for a TD class |
| `get_module_help` | `module_name` | Python help text for a module |

## MCP Prompts

| Prompt | Parameters | Description |
|--------|-----------|-------------|
| `search_op` | `op_name`, `op_type?` | Guide for searching operators |
| `check_op_errors` | `op_path` | Guide for inspecting/resolving errors and warnings |
| `connect_ops` | _(none)_ | Guide for wiring operators |
| `create_extension_guide` | _(none)_ | Guide for creating extensions |

## Embody Integration

| Tool | Parameters | Description |
|------|-----------|-------------|
| `externalize_op` | `op_path`, `tag_type?` | Tag and externalize operator to disk (one step) |
| `remove_externalization_tag` | `op_path` | Remove externalization tag |
| `get_externalizations` | _(none)_ | List all externalized operators |
| `save_externalization` | `op_path` | Force re-export an already-externalized operator |
| `get_externalization_status` | `op_path` | Get dirty state, build, timestamp, path |

## TDN Network Format

| Tool | Parameters | Description |
|------|-----------|-------------|
| `read_tdn` | `comp_path?`, `include_dat_content?`, `max_depth?`, `embed_all?` | **Preferred for reading ≥3 operators.** Returns live network as a TDN dict. ~20-90x fewer tokens than `get_op`+`query_network` walks thanks to default-omission, type_defaults, and par_templates. |
| `export_network` | `root_path?`, `include_dat_content?`, `output_file?`, `max_depth?` | Write `.tdn` to disk. Same payload as `read_tdn` plus file I/O and stale-file cleanup. |
| `import_network` | `target_path`, `tdn`, `clear_first?` | Recreate network from `.tdn` JSON |

**When to prefer `read_tdn`:** exploring or auditing ≥3 operators, checking structure and parameters-as-authored, mapping connections, reading annotations. Scope cost with `comp_path`; cap with `max_depth` on large roots.

**When NOT to use `read_tdn`:** evaluated-expression runtime values (`get_parameter`), cook errors (`get_op_errors`), DAT/CHOP/TOP output data (`get_dat_content`, `capture_top`), cook timing (`get_op_performance`), flag state after runtime mutation (`get_op_flags`). `read_tdn` is an authored-state snapshot, not a runtime probe.

## TOP Capture

| Tool | Parameters | Description |
|------|-----------|-------------|
| `capture_top` | `op_path`, `format?`, `quality?`, `max_resolution?` | Capture a TOP's output as an image. Returns file path + optional inline preview |

## Logging

| Tool | Parameters | Description |
|------|-----------|-------------|
| `get_logs` | `level?`, `count?`, `since_id?`, `source?` | Get recent log entries from ring buffer |

**Auto-piggybacked logs**: Every MCP response includes a `_logs` field with up to 20 recent entries. Log files inside Embody's logs directory (see the `Logfolder` parameter on the Embody COMP) have the complete picture.

## Bridge Meta-Tools

These run locally on the STDIO bridge — they work even when TD is not running.

| Tool | Parameters | Description |
|------|-----------|-------------|
| `get_td_status` | _(none)_ | Check if TD is running, Envoy reachable, crash detection, process liveness. Includes instance registry |
| `launch_td` | `timeout?` | Launch TD with the project's `.toe` file, wait for Envoy (default: 120s) |
| `restart_td` | `timeout?` | Gracefully quit TD and relaunch, wait for Envoy (default: 120s) |
| `switch_instance` | `instance?` | List all registered TD instances (omit `instance`) or switch the bridge to a different running instance (provide toe basename without `.toe`). See `/multi-instance` skill for workflow |

## 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"}}
]}
