mcp-tools-reference

name	mcp-tools-reference
description	MUST READ before first MCP tool call in a session. Complete Envoy tool catalog with parameters and usage.

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
diff_tdn	target?, max_changed_ops?, max_bytes?	What's UNSAVED in TDN networks (live vs on-disk .tdn) -- the view git can't give. Omit target -> whole project (every live TDN COMP, summarized); target = a COMP path OR a .tdn file path/bare filename -> that one COMP in full detail (old=disk, new=live). For committed/history diffs use plain git diff (Embody's .tdn diff driver keeps those clean). Read-only.

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.

When to use diff_tdn: whenever the user asks "what's changed / unsaved?" for TDN networks. It shows what is UNSAVED -- the live in-memory network vs the on-disk .tdn -- which git cannot see (git only reads disk, never TD's live state). Omit target (or pass ""/"project") for a whole-project summary (every live TDN COMP: which changed + counts); pass a target (a COMP path OR a .tdn file path/bare filename, resolved to its COMP) for one COMP in full detail (old=disk, new=live). For committed/history diffs (what changed vs the last commit) use plain git diff -- Embody installs a .tdn git diff driver so those are clean (the volatile export header is stripped). Read-only, non-interactive. Requires TD running.

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:

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