MCP Tools Reference

Envoy MCP Tool Reference

Mutating TD-authoring operations are wrapped in TD undo blocks (one batch_operations call = one Ctrl+Z step); read-only tools, run_tests, cook_op, and disk-only ops (export_network, save_externalization) are not.

Operator Management

Parameter Control

DAT Content

CHOP / POP Data

Reduced reads -- never a blind dump. A 4x600 CHOP is 2,400 raw floats; these return the shape and range instead.

Why the POP guard is on point count, not sample count: POP.points(attr, startIndex, count) accepts both slicing arguments and ignores them (verified on 2025.33070) -- the readback happens regardless. Asking for 4,096 points from a 160k POP measured slower than reading all of them. Reach for samples only when you actually need values, and prefer a smaller upstream POP for inspection.

Operator Flags

Operator Positioning & Layout

Annotations

Performance Monitoring

Connections

Code Execution

Envoy's own host: execute_python refuses (nothing runs; error_code envoy.embody.host_destroy_refused) code that would destroy or reload the Embody COMP, an ancestor, / or Envoy's extension DAT in the same call -- me and parent() ARE the Embody COMP here. delete_op, destroy-class exec_op_method and reload pulses via set_parameter refuse the same targets. Stop and ask the user; only when they asked to move or remove Embody, follow the refusal text (one deferred run() string).

Introspection & Diagnostics

MCP Prompts

Embody Integration

TDXN Network Format

read_tdn and diff_tdn remain registered as DEPRECATED aliases that call straight through -- the old names are published in shipped rule files and saved agent prompts, so they keep working. Prefer read_tdxn / diff_tdxn.

When to prefer read_tdxn: 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_tdxn: 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_tdxn is an authored-state snapshot, not a runtime probe.

When to use diff_tdxn: whenever the user asks "what's changed / unsaved?" for TDXN networks. It shows what is UNSAVED -- the live in-memory network vs the on-disk .tdxn -- 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 TDXN COMP: which changed + counts); pass a target (a COMP path OR a .tdxn file path/bare filename, resolved to its COMP) for one COMP in full detail (old=disk, new=live). For committed/history diffs use plain git diff. Read-only, non-interactive. Requires TD running.

TOP Capture

For visual work, success is verified by capturing and judging the output TOP, not by a clean network alone; see /visual-aesthetics.

Logging

Auto-piggybacked logs: A _logs field rides along only when a WARNING or ERROR was logged during the call (capped at ~8) -- routine INFO/DEBUG/SUCCESS history is omitted to keep responses token-lean. Warning cursors are per session (from the bridge's identity headers), so concurrent sessions each receive their own copy of a warning -- one session polling first no longer consumes it for the others.

Unattended sessions: nothing answers a dialog, so preset the Embody parameter that decides it: Tdxnpalettehandling (palette Black Box vs Full Export), Filecleanup (deleted-file prompt), Tdxnlockedwarn (quiet) and Tdxndatsafety (save-time content report). Saves never prompt: save through save_project and read save warnings in get_job_status(job_id)["warnings"] -- the save's reinit can keep them out of _logs.

Auto-piggybacked peer advisories: a _peers field rides along when your request touches territory another session modified recently (last ~10 min) -- one entry per peer: {label, scope, tool, age_s, conflict}. conflict: true means a peer WROTE an overlapping scope within the last minute AND your operation is also a write -- treat it as a hard stop: check get_sessions, coordinate (or divide work by COMP subtree), and only then proceed. Non-conflict advisories are informational and deduped per (peer, scope) for ~5 min; conflicts always ride.

Destructive-op gate: delete_op, import_network with clear_first=True, run_tests, and batches containing them are REFUSED (MULTI-SESSION GATE error naming the holder/peer) while a live peer session claims the scope or wrote it within the last minute. Pass override=True only when certain, and say so. Call get_logs for the full history, or read the log files in Embody's logs directory (see the Logfolder parameter on the Embody COMP).

Auto-attached recovery hints: when a tool returns an error, a recovery_hints list may ride along -- each entry is {code, cause, action, next_tools} keyed off the error message (path-not-found, wrong family, empty capture, thread conflict, timeout, ...). It tells you the likely cause and which tool to call next, so recover by following it rather than retrying the same failing call verbatim. Every error envelope also carries error_code (envoy.<area>.<condition>, envoy.error when unclassified) -- branch on it, not on the message text.

Write effects: every write tool's response may carry _effects -- errors/warnings that appeared after YOUR write, an fps drop, and for DAT writes the compile state of every GLSL operator consuming that DAT (its dock host and any operator referencing it by parameter): shaders_checked (what was linted), new_shader_errors (failures your write introduced), shader_errors_persist (still failing after a later write). Fix those before building further.

Testing

Bridge Meta-Tools

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

Convoy Tools (LAN work relay)

Seventeen additional meta-tools drive Convoy, relaying work to Convoy-enabled Embody nodes on the trusted LAN through the local per-user host app. Status and inventory calls (get_convoy_status, convoy_list_nodes, convoy_list_controllers, convoy_ping) never wake TouchDesigner.

• convoy_select_node pins THIS session to one exact node -- ordinary Envoy tools then run there until convoy_select_node with clear=true.
• convoy_call / convoy_batch run registered operations on explicit one-off targets; pass a unique idempotency_key per intended action so a retry reconciles instead of double-running.
• convoy_get_job / convoy_ack_job / convoy_cancel_job reconcile durable deliveries; acknowledge a finished delivery you have safely observed so the target can release its protected result artifacts.
• convoy_forget_node deletes a stale node row on THIS machine's host app (a renamed, moved, or deleted project's leftover). It refuses only while the node has a delivery that has not FINISHED, and names the blocking delivery ids in its refusal (a finished-but-unacknowledged result never holds a row -- results are fetched by delivery id and outlive it); dead and long-unseen rows are also evicted automatically by the host's retention sweep.
• convoy_get_artifact / convoy_save_artifact fetch results BY ARTIFACT REFERENCE and verify them locally -- never open a remote C:\... or /Users/... path as if it were local.
• convoy_start_node / convoy_restart_node manage node lifecycle; restarts require the node's CURRENT runtime id (from convoy_list_nodes) plus a unique idempotency_key, and the default policy refuses dirty or unverifiable project state.
• convoy_update_embody self-updates Embody on one node (node=<id|name|hostname>) or the whole fleet (all=true) by dispatching the bounded update_embody operation as durable per-node jobs -- no TD Python grant involved; offline/disabled/Perform Mode nodes are skipped by name.
• convoy_owlette is an optional read-mostly site bridge that fails closed without credentials.
• convoy_lifecycle_state / convoy_lifecycle_quit are TD-side tools reserved for the Convoy host's own lifecycle session; any other session gets Convoy lifecycle host session required. Use convoy_restart_node instead.

Batch Operations

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