mcp-tools-reference
Skill213 starsChanged 2 months agoMITView on GitHub
MUST READ before first MCP tool call in a session. Complete Envoy tool catalog with parameters and usage.
In this repository30 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- web/llms-full.txtllms.txt
- web/llms.txtllms.txt
- add-mcp-toolSkill
- agent-testsSkill
- briefSkill
- build-uiSkill
- collabSkill
- create-extensionSkill
- create-operatorSkill
- debug-operatorSkill
- externalize-operatorSkill
- glsl-shadersSkill
- manage-annotationsSkill
- merge-divergent-toxSkill
- movie-exportSkill
- multi-instanceSkill
- multi-session-etiquetteSkill
- operator-gotchasSkill
- parameter-designSkill
- pop-networksSkill
- publish-specimenSkill
- releaseSkill
- run-testsSkill
- specimen-authoringSkill
- td-api-referenceSkill
- td-recoverySkill
- testingSkill
- visual-aestheticsSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 138
Use it for 3+ calls to the same tool (positioning, connecting, parameter setting, flags).
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- Generated by Embody/Envoy - Do not remove this comment - sha:97883e94fea97725 -->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. Development only: blocks TD's main thread 15+ s and restarts Envoy; refused in Perform Mode (perform_mode) |
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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.