mcp-tools-reference

<!-- Generated by Embody/Envoy - Do not remove this comment - sha:6109d82d7690b624 --> # 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` |