Tools Reference

Envoy exposes 49 MCP tools for interacting with TouchDesigner, plus 4 bridge meta-tools (listed below). All tools use the standard MCP protocol and can be called by any compatible client.

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, initialized and ready to use
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. Set include_utility=True to include annotations
find_children	op_path, name?, type?, depth?, tags?, text?, comment?, include_utility?	Advanced search using TD's findChildren — filter by name pattern, type, depth, tags, text content, or comment
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 a parameter's value, expression, bind expression, or mode (constant/expression/export/bind)
get_parameter	op_path, par_name	Get parameter value, mode, expression, bind info, export source, label, range, menu entries, and default

DAT Content

Tool	Parameters	Description
get_dat_content	op_path, format?	Get DAT text or table data ("text", "table", or "auto")
set_dat_content	op_path, text?, rows?, clear?, confirm_wipe?	Full-replace DAT content. Wipe guardrail refuses text="", rows=[], or clear=True with no content unless confirm_wipe=True is passed. For partial edits to text DATs, prefer edit_dat_content -- it sends only the changed substring.
edit_dat_content	op_path, old_string, new_string, replace_all?, confirm_wipe?	Surgical text edit on a DAT (mirrors Claude Code's Edit tool). Replaces old_string with new_string. By default old_string must appear exactly once -- pass replace_all=True to replace every occurrence. Token-efficient: only the changed substring crosses the wire. Text DATs only; use set_dat_content(rows=...) for tables.

Operator Flags

Tool	Parameters	Description
get_op_flags	op_path	Get all flags: bypass, lock, display, render, viewer, current, expose, selected, allowCooking
set_op_flags	op_path, bypass?, lock?, display?, render?, viewer?, current?, expose?, allowCooking?, selected?	Set one or more flags on an operator

Positioning & Layout

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

Annotations

Tool	Parameters	Description
create_annotation	parent_path, mode?, text?, title?, x?, y?, width?, height?, color?, opacity?, name?	Create an annotation. Modes: "annotate" (default, has title bar), "comment", "networkbox"
get_annotations	parent_path	List all annotations in a COMP with their properties and enclosed operators
set_annotation	op_path, text?, title?, color?, opacity?, width?, height?, x?, y?	Modify properties of an existing annotation
get_enclosed_ops	op_path	Get operators enclosed by an annotation, or annotations enclosing an operator

Connections

Tool	Parameters	Description
connect_ops	source_path, dest_path, source_index?, dest_index?, comp?	Wire two operators together. Set comp=True for COMP connectors (top/bottom)
disconnect_op	op_path, input_index?, comp?	Disconnect an operator's input. Set comp=True for COMP connectors (top/bottom)
get_connections	op_path	Get all input/output connections (includes COMP connections for COMPs)

Performance Monitoring

Tool	Parameters	Description
get_op_performance	op_path, include_children?	Get CPU/GPU cook times, memory usage, 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

Code Execution

Tool	Parameters	Description
execute_python	code	Execute Python in TD; set the result variable to return values. Auto-lints newly-created ops and emits a LAYOUT WARNING when they are left at (0,0) or overlapping (unlike create_op, raw comp.create() does not auto-position)

Introspection & Diagnostics

Tool	Parameters	Description
get_td_info	(none)	Get TD version, build, OS, and Envoy version
get_op_errors	op_path, recurse?	Get error and warning messages for an operator and its children
exec_op_method	op_path, method, args?, kwargs?	Call a method on an operator (e.g., appendRow, cook)
get_td_classes	(none)	List all Python classes/modules in the td module
get_td_class_details	class_name	Get methods, properties, and docs for a TD class
get_module_help	module_name	Get Python help text for a module (supports dotted names like td.tdu)

Embody Integration

Tool	Parameters	Description
externalize_op	op_path, tag_type?	Tag and externalize operator to disk (auto-detects type if omitted)
remove_externalization_tag	op_path	Remove externalization tag
get_externalizations	(none)	List all externalized operators with status
save_externalization	op_path	Force save an externalized operator to disk
get_externalization_status	op_path	Get dirty state, build number, timestamp, file path

TDN Format

Tool	Parameters	Description
read_tdn	comp_path?, include_dat_content?, max_depth?, embed_all?	Preferred for reading ≥3 operators. Return the live network as a TDN dict (in-memory, never written to disk). ~20-90× fewer tokens than a get_op walk thanks to default-omission, type_defaults, and par_templates compaction
export_network	root_path?, include_dat_content?, output_file?, max_depth?	Write a .tdn file to disk. Same payload as read_tdn plus file I/O and stale-file cleanup
import_network	target_path, tdn, clear_first?	Recreate a network from a .tdn file
diff_tdn	target?, max_changed_ops?, max_bytes?	What is UNSAVED in TDN networks -- the live in-memory network vs the on-disk .tdn, the view git cannot give. Omit target for a whole-project summary (every live TDN COMP, which changed + counts); pass a COMP path OR a .tdn file path/bare filename for one COMP in full per-field detail (old=disk, new=live). For committed/history diffs use plain git diff -- Embody installs a .tdn diff driver that keeps those clean. Read-only, non-interactive

TOP Capture

Tool	Parameters	Description
capture_top	op_path, format?, quality?, max_resolution?	Capture a TOP's output as an image. Saves to temp file and returns the path. Small images (<20 KB) also include an inline MCP ImageContent preview. Default: JPEG at 80% quality, max 640px long edge.

Logging

Tool	Parameters	Description
get_logs	level?, count?, since_id?, source?	Get recent log entries from ring buffer. Filter by level, source, or use since_id for incremental polling
run_tests	suite_name?, test_name?	Run test suites and return results

Auto-piggybacked logs

Every MCP tool response includes a _logs field with up to 20 log entries generated since the previous tool call. This lets you monitor operations in real-time without needing to call get_logs separately.

Bridge Meta-Tools

These tools run locally on the STDIO bridge script, not inside TouchDesigner. They work even when TD is not running — this is how Claude Code can launch or restart TD without an active Envoy connection.

Tool	Parameters	Description
get_td_status	(none)	Check if TD is running, Envoy reachable, crash detection, process liveness, restart attempts remaining
launch_td	timeout?	Launch TD with the project's .toe file. Waits for Envoy to become reachable (default: 120s)
restart_td	timeout?	Gracefully quit TD and relaunch. Waits for exit before relaunching (default: 120s)
switch_instance	instance?	List all registered TD instances (omit instance) or switch to a different running instance. See Multiple Instances

Bridge architecture

Claude Code connects to Envoy via a STDIO bridge script (.embody/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 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:

{"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
search_op	op_name, op_type?	Guide for searching operators by name
check_op_errors	op_path	Guide for inspecting and resolving operator errors
connect_ops	(none)	Guide for wiring operators together
create_extension_guide	(none)	Guide for creating TD extensions with proper patterns