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

Operator Flags

Operator Positioning & Layout

Annotations

Performance Monitoring

Connections

Code Execution

Introspection & Diagnostics

MCP Prompts

Embody Integration

TDN Network Format

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 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

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.

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 {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.

Bridge Meta-Tools

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

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