<!-- Generated by Embody/Envoy - Do not remove this comment - sha:571893bf5ef1354c -->
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. The contracts behind the multi-session, job, bridge and Convoy tools, and the fields that ride on every response (_logs, _peers, gates, recovery_hints, _effects), are in references/coordination.md in this skill's folder (get_guidance(topic='mcp-tools-reference/coordination') without a skills folder). The short version: a LAYOUT WARNING, THREADING WARNING or MULTI-SESSION GATE line in _logs is a hard stop, _peers with conflict: true is a hard stop, an error carries error_code plus recovery_hints to follow instead of retrying, and _effects on a write names the errors, fps drop and shader failures your write caused.
Operator Management
| Tool | Parameters | Description |
|---|
create_op | parent_path, op_type, name?, language? | Create a new operator (e.g., baseCOMP, noiseTOP, textDAT, gridPOP). Auto-positions it and hugs any docked companions below it (docks_placed). A textDAT starts as python; pass language (glsl, json, yaml, xml, text) for anything else |
create_extension | parent_path, class_name, name?, code?, promote?, ext_name?, ext_index?, existing_comp?, parent_shortcut? | Create a TD extension: baseCOMP + text DAT + extension wiring |
delete_op | op_path, override? | Delete an operator (multi-session gated; override bypasses, say so). Refuses the Embody COMP, its ancestors, / and Envoy's extension DAT |
copy_op | source_path, dest_parent, new_name? | Copy operator to new location. Auto-positions the copy and hugs its docked companions (docks_placed) |
rename_op | op_path, new_name | Rename an operator |
get_op | op_path, include_defaults? | Returns NON-DEFAULT parameters by default (include_defaults=True for all); parameter-heavy COMPs are expensive (~3k+ tokens full), prefer read_tdxn for structure reads |
query_network | parent_path?, recursive?, op_type?, include_utility? | Compact operator list: path/type/family/depth; name = last path segment. include_utility=True includes annotations |
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; rejects invalid Menu values with valid menuNames; sequence-block names auto-grow (const5name -> 6 blocks); reload and clone pulses on Envoy's own host are refused |
get_parameter | op_path, par_name?, search?, search_in?, depth?, max_results?, details? | Single-parameter mode is compact by default (path, parameter, value, mode, label, mode-specific refs, menuNames); details=True restores default/style/range/menuLabels/menuIndex. Search mode (search glob or substring over name/value/expr/any across a subtree) ignores details |
describe_op_type | op_type, pattern?, page?, include_menus? | Parameter names, labels, styles, creation defaults and menu values for an operator TYPE before it exists. Call it once per unfamiliar type instead of guessing a name into set_parameter; pattern globs names AND labels, page narrows; unknown type -> did_you_mean, empty match -> hint. Cached per type |
DAT Content
| Tool | Parameters | Description |
|---|
get_dat_content | op_path, format? | DAT text or table ("text", "table", "auto"), or "stats" to reduce a table to per-column stats + head/tail rows |
set_dat_content | op_path, text?, rows?, clear?, confirm_wipe? | Full-replace DAT content. Refuses no-action calls and wipes (text="", rows=[], clear=True) unless confirm_wipe=True. For partial text edits prefer edit_dat_content |
edit_dat_content | op_path, old_string, new_string, replace_all?, confirm_wipe? | Surgical text edit on a text DAT; old_string must appear exactly once unless replace_all=True; not-found errors include diagnostics. Tables go through set_dat_content(rows=...) |
CHOP / POP Data
Reduced reads, never a blind dump: a 4x600 CHOP is 2,400 raw floats; these return shape and range.
| Tool | Parameters | Description |
|---|
get_chop_data | op_path, channels?, samples?, compare_to? | Per-channel min/max/mean/std/first/last, capped at 32 channels. channels is a name glob; samples>0 adds head/tail raw values; compare_to another CHOP adds a per-channel diff |
get_pop_data | op_path, attributes?, samples?, max_points? | Point/prim/vert attribute metadata (~0.02 ms at ANY point count). Reading point VALUES is a GPU->CPU readback (~9.5 ms at 16k points, ~69 ms at 160k), so samples>0 is opt-in and refused above max_points (default 50,000). POP.points() ignores its slicing arguments (verified 2025.33070), so the guard is on point count |
Operator Flags, Positioning, Layout
| Tool | Parameters | Description |
|---|
get_op_flags | op_path | All flags |
set_op_flags | op_path, bypass?, lock?, display?, render?, viewer?, current?, expose?, allowCooking?, selected?, cloneImmune?, componentCloneImmune?, showCustomOnly?, showDocked? | Set one or more flags; a flag the operator cannot carry comes back in unsupported_flags |
get_op_position | op_path | Position, size, color, comment |
get_network_layout | comp_path, include_annotations? | Compact layout for all children: path/type/nodeX/nodeY/nodeWidth/nodeHeight plus bounding_box; docked ops carry dockedTo. 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. Moving a host re-hugs its docked companions (docks_moved); position the host before any explicitly-placed dock |
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"); load /manage-annotations first |
get_annotations | parent_path | 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 | Ops enclosed by an annotation, or annotations enclosing an op |
Connections, Performance, Code
| 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 | All input/output connections, one input entry per connector |
get_op_performance | op_path, include_children? | CPU/GPU cook times (ms), memory, cook counts |
get_project_performance | include_hotspots? | Project FPS, frame time, GPU/CPU memory, dropped frames, active ops, GPU temp; optional top-N COMP hotspots |
run_soak_test | duration_s?, interval_s?, fps_target?, label?, stop?, idempotency_key? | Background performance soak (job id back immediately; poll get_job_status). Samples the Perform CHOP on the frame hook without cooking or capturing anything; logs perturbing Envoy calls and excludes their 2 s neighborhood from the clean stats; finishes with trends, exact drops, GPU headroom, hotspots and a PASS/WARN/FAIL verdict. stop=True ends it early. See /testing |
execute_python | code | Execute Python in TD; set result to return values. Lints created ops (LAYOUT WARNING) and worker-side run() (THREADING WARNING); refuses code that would destroy or reload Envoy's own host (envoy.embody.host_destroy_refused), where me and parent() ARE the Embody COMP |
Introspection & Diagnostics
| Tool | Parameters | Description |
|---|
get_td_info | (none) | TD version, build, OS, Envoy version |
get_op_errors | op_path, recurse? | Errors and warnings for op and children: cook errors, Python tracebacks (kind: "script", invisible to op.errors()), and GLSL compile failures (shaderErrors) |
exec_op_method | op_path, method, args?, kwargs? | Call a method on an operator (destroy-class methods on Envoy's host are refused) |
get_td_classes | (none) | All Python classes in the td module |
get_td_class_details | class_name | Methods, properties, docs for a TD class |
get_module_help | module_name | Python help text for a module |
get_docs | query, section?, source?, max_chars? | Official TD docs: offline mirror first, docs.derivative.ca fallback; returns title, source, sections_available, content; ambiguous offline lookups return matches |
get_guidance | topic? | THIS project's checked-in doctrine: the rules, the skills and their references/*.md (topic <slug>/<file>). Bare call lists topics; matching ignores case and punctuation. Worker-side, no TD round-trip. The only way clients with no skills folder (VS Code, Copilot, Windsurf) see them |
get_focus | (none) | What the user is looking at: network, selected, current, rollover, target. "This operator" means the SELECTED/current op, never the rollover |
get_sessions | (none) | Connected AI sessions, their recent scopes and claims, you, and the shared task ledger; check at session start and before destructive work |
claim_scope / release_scope | scope, note?, ttl? | Cooperative WRITE lease on an op-path prefix, file:<path> or project:<name>; project:worktree-* claims are durable |
announce_task / update_task | title, scopes?, note? / task_id, status?, note?, commit? | The shared task ledger: announce substantive work, then done_uncommitted, committed (sha) or abandoned |
preflight_landing | worktree_path | Landing safety check for a worktree diff against main-tree dirt, peer claims and unsaved live TDXN state; run before porting any worktree diff |
Embody Integration and TDXN
| Tool | Parameters | Description |
|---|
externalize_op | op_path, tag_type? | Tag and externalize an operator to disk in one step (load /externalize-operator first) |
remove_externalization_tag | op_path, delete_file? | Remove tracking (tag + row + TDXN breadcrumb); check removed_anything, not removed_tags, to confirm cleanup |
get_externalizations / get_externalization_status | (none) / op_path | All externalized operators / dirty state, build, timestamp, path for one |
save_externalization | op_path | Force re-export an already-externalized operator |
read_tdxn | comp_path?, include_dat_content?, max_depth?, embed_all? | Preferred for reading >=3 operators: the live network as a TDXN dict, ~20-90x fewer tokens than get_op+query_network walks. An authored-state snapshot, not a runtime probe: evaluated values, cook errors, output data, cook timing and runtime flags come from get_parameter, get_op_errors, get_dat_content/capture_top, get_op_performance, get_op_flags |
export_network | root_path?, include_dat_content?, output_file?, max_depth?, embed_all? | Write .tdxn to disk; with output_file it returns a compact summary, not the document |
import_network | target_path, tdn, clear_first?, override? | Recreate a network from a parsed TDXN document (gated with clear_first=True) |
diff_tdxn | target?, max_changed_ops?, max_bytes? | What is UNSAVED in TDXN networks (live vs on-disk), the view git cannot give. Omit target for a whole-project summary; a COMP path or .tdxn file for one COMP in full (old=disk, new=live). Committed history: plain git diff |
read_tdn and diff_tdn remain as deprecated aliases.
Capture, Logs, Jobs, Bridge
| Tool | Parameters | Description |
|---|
capture_top | op_path, format?, quality?, max_resolution?, inline?, sample_grid? | Capture a TOP to a temp image (or an NxN RGBA grid with sample_grid>=2). The text carries a Quality verdict from the raw pixels: FAIL is a black, flat or fully-transparent frame. Never declare a visual task done on a FAIL |
capture_op | op_path, format?, quality?, max_resolution?, inline? | Capture ANY operator: TOPs natively, every other family through a transient OP Viewer TOP |
get_logs | level?, count?, since_id?, source? | Recent log entries from the ring buffer (200 entries; the log files in Embody's Logfolder hold the rest) |
run_tests | suite_name?, test_name?, override?, background?, idempotency_key?, confirm_saved? | Embody unit-test suites; background=True (recommended for full runs) returns a job id |
get_job_status | job_id? | Status of background jobs (run_tests, save_project, update_embody, run_soak_test); omit the id to list recent jobs |
save_project | idempotency_key? | Save the project as a tracked job |
update_embody | idempotency_key? | Self-update Embody as a tracked job |
get_td_status | (none) | Bridge-side: TD running, Envoy reachable, frozen-main-thread flags, instance registry, live sessions; works with TD down |
launch_td / restart_td | timeout? | Launch or gracefully relaunch TD with the project's .toe |
list_dialogs / dismiss_dialog | instance?, screenshot? / instance?, dialog?, action? | See and clear the modal dialog that is freezing TD; call list_dialogs FIRST when every tool times out |
switch_instance | instance?, all_sessions? | List TD instances or re-pin this session; pass instance=<name> on any tool for a single call (/multi-instance) |
convoy_* | see references/coordination.md | Eighteen LAN work-relay tools: pin a node with convoy_select_node, then ordinary tools run there |
Batch Operations
| Tool | Parameters | Description |
|---|
batch_operations | operations, override? | Several tool calls in one request; operations is a list of {"tool": str, "params": dict}; stops on the first error; one undo step |
Use it for 3+ calls to the same tool (positioning, connecting, parameter setting, flags); use execute_python when you need conditionals, loops or computed values between operations.
{"operations": [
{"tool": "set_op_position", "params": {"op_path": "/project1/noise1", "x": 400, "y": 0}},
{"tool": "set_op_position", "params": {"op_path": "/project1/level1", "x": 800, "y": 0}},
{"tool": "connect_ops", "params": {"source_path": "/project1/noise1", "dest_path": "/project1/level1"}}
]}
MCP Prompts
search_op(op_name, op_type?), check_op_errors(op_path), connect_ops(), create_extension_guide() are guide prompts, not tools.
