Dispatch up to 8 tool calls in one model roundtrip.

Each sub-call's result is returned in a structured array — per-call failures don't abort siblings. Use this for read-only sweeps ("inspect 5 things at once") to save model-to-server-to-model latency.

Hard constraints:

• Maximum 8 sub-calls per invocation.

• Nested td_tool_batch calls are rejected per-sub-call (fork-bomb guard).

• Sub-calls execute sequentially (TD's Python API is not thread-safe).

Returns: {"ok": True, "count": int, "results": [ {"tool": str, "ok": bool, "result": dict|None, "error": str|None, "elapsed_ms": int}, ... ]}

``error`` is always ``str | None`` — dict errors from
``format_tool_error`` are normalised to their ``message`` field.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Compatibility/expert surface for typed PatchPlan construction. For new concept-to-network TouchDesigner builds, prefer td_brain_plan followed by td_brain_execute.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Read-only PatchPlan preview for compatibility/expert workflows. For new visual builds, prefer td_brain_plan because it carries concept, corpus, and validation context.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Destructive compatibility/expert PatchPlan executor. Prefer td_brain_execute for BrainPlans because it is the default validated transaction path for TDPilot-authored builds.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Read-only validation for patch compatibility workflows. BrainPlan workflows should use td_brain_plan and td_brain_execute so validation is tied to the authored plan.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Generate PatchPlan variants for compatibility/expert workflows. For new creative builds, start with td_brain_plan so variants remain grounded in a BrainPlan.

Use this when a request is pattern-shaped with an exact validated topology or technique composition. It returns a non-mutating concept graph, typed patch plan, and server-derived intent coverage; execute only when coverage is complete. For artistic, multi-domain, spatial, camera/depth/fog, or implicit-architecture requests, start directly with td_brain_ground → td_brain_propose.

Use this when the request is artistic, multi-domain, spatial, or implicit-architecture requests, and whenever td_brain_plan returns blocked: it returns a read-only grounding pack (task features, corpus evidence, candidate operators, parameter contracts, operator availability, live state, exemplars, and the draft authoring contract) so you can write a draft for td_brain_propose. Do not use it for trivial single-node edits.

Use this when you have authored a draft candidate graph from a td_brain_ground grounding pack and need TDPilot to validate it into an executable BrainPlan. It is read-only and never mutates TouchDesigner: accepted drafts are compiled, gated by parameter semantics, and cached server-side so td_brain_execute(plan_id=...) can run them immediately; rejected drafts return machine-readable rejections to fix and retry.

DEFAULT apply path for a BrainPlan: use this when you already have a BrainPlan from td_brain_plan (or a draft from td_brain_propose) and need TDPilot to apply it transactionally with validation, rollback, and optional local learning. Prefer the lower-level td_transaction_apply only when you hold a ready PatchPlan/BrainPlan and want to drive raw transaction controls yourself (no grounding, no learning). Do not use the legacy td_plan_patch / td_patch_* pipeline for new builds.

Low-level executor: use this when you already hold a ready PatchPlan or BrainPlan and want to drive raw preflight, snapshot, validation, dry-run, max-op, and rollback controls yourself. For the normal BrainPlan build flow prefer td_brain_execute, which wraps this layer and adds grounding-aware concept profiles and optional local learning. Do not use the legacy td_plan_patch / td_patch_* pipeline for new builds.

Use this when you already have BrainPlan or transaction data and want to render the optional local cockpit UI. This is read-only presentation; call td_brain_plan or td_brain_execute first for authoritative data.

Read the text or table content of a DAT node.

Write text or table content into a DAT node (overwrites existing).

Create or update a custom parameter page on a COMP.

Execute Python code inside TouchDesigner.

Capture a TOP frame as base64 inline, or to disk via save_path.

Use this for a quick single-frame visual: with save_path set the image is written to disk TD-side and only metadata + the path come back — use this for repeated visual verification. Without it the response embeds base64 image data; ask the user before repeated base64 screenshots because each image can consume significant tokens in model context. Prefer td_capture_frame when you want metadata-first (resolution/format/bytes) with the image behind a confirm/save_path gate; prefer td_capture_and_analyze when you also need cooking state and errors folded into the same call.

Read CHOP channel data (values/samples).

Read SOP/POP geometry data (points/prims).

Read structured POP metadata and attribute samples.

Get cooking/performance info for a subtree.

Search nodes across a subtree.

Legacy scopes ('name'/'type'/'family'/'all') hit the existing TD-side /api/search endpoint. New v1.6.0 scopes ('dat_text', 'param_exprs') iterate via the /api/exec endpoint — no .tox rebuild required.

Get errors + warnings for a node (optionally recursive).

Subscribe to runtime TD events for a node.

Remove a runtime-event subscription for a node path.

Read recent runtime event history from the server-side event buffer.

List the child operators (nodes) directly under a network path.

Get detailed info about a node (type, errors, warnings, parameters).

The parameters dict is capped at param_limit entries (default 50, hard ceiling 200) — full COMP serialization can blow past 80 KB. Use td_get_params with name/page filters when you need the rest.

When include_notes=True, any markdown note saved via td_component_notes for this path is attached as a note field.

Get parameter values and metadata for a node.

Set node parameters (static values or live expressions).

Parameter-semantics checks are advisory here by default (param_semantics_policy= 'warn'): findings are attached but the write proceeds, since some out-of-range values are legitimate in TD (e.g. extending a soft UI range). Use param_semantics_policy='block', or the brain/transaction path which gates automatically, when you want invalid bindings to stop the write.

Create a new TouchDesigner operator of a given type under a parent path.

Delete a node by its absolute path.

v1.4.6 Bug A PoC: explicit-args signature instead of the old params: DeleteNodeInput wrapper. FastMCP wraps params: Model signatures under a params: {"$ref": ...} property that MCP clients collapse to an opaque {}. Explicit args produce a flat schema the client can render directly — callers see path as a required string with description and min_length instead of having to guess. The Annotated[str, Field(...)] pattern carries the same validation the old Pydantic model had.

Copy/duplicate an existing node (with its parameters) to a new node.

Rename a node to a new name within its parent network.

Connect two nodes (source output → target input).

Disconnect a node's input or output connector.

Get upstream/downstream connections for a node.

Return concise, source-cited hints for a topic, op_type, or intent.

Sources include hint packs shipped under src/td_mcp/hints/packs/ (skill pitfalls, canonical recipes), with future expansion to live knowledge-store essays. Every hint cites its source.

The response shape:

{
  "topic": ...,
  "op_type": ...,
  "confidence": 0.87,
  "hints": [
    {"id": ..., "priority": "critical|useful|context", "rule": ...,
     "source": "tdpilot-core §11", "source_kind": "skill_pitfall"},
    ...
  ],
  "next_tools": ["td_get_param_help", "td_screenshot"],
  "hint_pack_version": "v1.6.0-1",
  "available_topics": [...],
  "available_op_types": [...]
}

Get TouchDesigner project info: version, build, project name, OS. Returns a JSON envelope.

List available operator families (TOP, CHOP, SOP, DAT, COMP, MAT, POP). Returns a JSON envelope.

Detect MCP client capabilities plus server/component versions and runtime config. Returns a JSON envelope.

Get MCP server runtime metrics: telemetry, events, streams, safety, snapshots, jobs. Returns a JSON envelope.

Search the knowledge corpus for operators, palette, releases, snippets, or articles.

Get full documentation card for an operator type or a specific node.

Get help for a specific parameter: live metadata + knowledge card entry + current value.

Search for OP Snippets by keyword and optional family.

Look up a palette component by name or search by query.

Get release notes for a specific build (default: current).

Check if an operator type is compatible with a specific build.

Search POPx operator documentation — GPU particles, falloffs, simulations.

Get full documentation for a POPx operator (e.g. 'Particle SIM', 'Shape Falloff').

Describe the MCP server surface: tool count, resource count, capabilities, version.

Persist a free-form markdown knowledge entry (prose/notes/essays).

Returns the entry id. The body is stored at ~/.tdpilot/knowledge//entries/.md and the metadata in index.json. Local-only, never pushed anywhere. Prefer td_memory_save (with td_memory_learn) when you want to capture a structured, replayable technique recipe rather than free-form prose.

Search the free-form markdown knowledge store. Returns summaries (no bodies).

Use this for prose reference content — notes, essays, prose-with-math saved via td_knowledge_save. Use td_knowledge_get afterward to fetch a specific entry's body. Prefer td_memory_recall when you want the structured, replayable technique-recipe library (learned via td_memory_learn, rebuilt with td_memory_replay) rather than free-form notes.

Fetch the full markdown body + metadata for one entry.

List free-form markdown knowledge-entry summaries, newest first.

Prefer td_memory_list for the structured, replayable technique library.

Instantiate a legacy scaffold; feedback/audio macros are not complete visuals.

List all available macro templates (built-in plus user templates). Returns a JSON envelope.

Inspect parameters plus truthful capability, I/O, limitations, and completion status.

Analyze a network subtree and extract a reusable technique recipe.

Auto-detects complexity:

• small (<10 nodes): full recipe with all params and expressions

• medium (10-20): full recipe

• large (>20): structure summary + key params only

Returns the technique dict — pass it to td_memory_save to persist.

Save a structured, replayable technique to the project or global library.

Use the output of td_memory_learn as the technique input, or construct a technique dict manually. Prefer td_knowledge_save when you want to capture free-form markdown prose/notes rather than a replayable network recipe.

Search the structured, replayable technique library by text query and/or tags.

Returns summaries (not full recipes). Use td_memory_replay to rebuild a found technique as live nodes. Prefer td_knowledge_recall when you want free-form markdown notes/essays (prose reference content) rather than replayable recipes.

Rebuild a saved technique in a new location in the TD project.

Creates nodes, sets parameters and expressions, wires connections. Only works for techniques with a full recipe (small/medium complexity).

Mark a technique as favorite and/or rate it (0-5).

Copy a project technique to the global library so it's available across all projects.

Export the technique library as a portable JSON object for sharing or backup.

Import techniques from an exported library (from td_memory_export).

Get, set, list, or delete user preferences.

Preferences store things like: preferred color palettes, default resolutions, favorite operator types, naming conventions, etc.

List saved (structured, replayable) techniques, filterable by scope, tags, and favorites.

Prefer td_knowledge_list for the free-form markdown notes/essays store.

Recent tool-call activity from this MCP server's ring buffer.

Returns a JSON array of entries newest-first, each with ts, tool, args_summary, result_summary, duration_ms, ok. The buffer holds the most recent 200 calls; older entries are evicted.

Pairs with the in-TD activity_log Table DAT mirror so the same data is also wireable into a live visual patch.

Check for and optionally install a newer TDPilot release from GitHub.

Default behavior (check_only=True) hits the GitHub releases API and returns {installed, latest, newer_available, release_url, asset_urls}. Set check_only=False to actually download and install — this writes to ~/.tdpilot/td_component/tdpilot.tox, the Claude Code plugin cache, and the repo working-tree (when running from a clone). On success returns md5 fingerprints for each install path so the caller can verify sync.

Releases v1.6.9 through v2.0.3 shipped without the tdpilot.tox asset; against those, check_only=False returns error_code="release_asset_missing" with remediation hints instead of installing. Releases after v2.0.3 attach the asset automatically (.github/workflows/release-assets.yml).

Network-only — does not touch TouchDesigner. Safe to run when TD is closed.

Report whether the local server, TD component, packages, and public surfaces are in sync.

Strict version/auth sync diagnostic without exposing secret material.

Per-COMP markdown notes — what this subnet does, why it's wired this way, gotchas, TODOs. External JSON storage by default; embed=True also writes a hidden Text DAT inside the COMP for portability.

Autonomous visual goal optimization via bounded parameter search.

Asynchronous temporal dynamics observation (frame, cooking, events).

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Legacy compatibility planner returning the pre-v1.5 patch dict shape. For new concept-to-network TouchDesigner work, prefer td_brain_plan followed by td_brain_execute.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Read-only validation for legacy td_plan_patch dicts. For new TDPilot-authored builds, use the BrainPlan path: td_brain_plan then td_brain_execute.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Read-only recipe compatibility check. Use td_brain_plan for new grounded visual-programming requests that should become a BrainPlan.

Read-only project audit. Pair with td_brain_plan for new build/debug requests that need plan-aware changes afterward.

Recommend official palette or built-in operator components for a given goal.

Search for official examples and snippets matching a query.

Suggest better official alternatives for a given intent, with gotcha warnings.

Read current timeline state: frame, seconds, FPS, playing. Returns a JSON envelope.

Control timeline playback: play/pause, jump to frame, set FPS.

Save/load/undo/redo project lifecycle operations.

Pulse a pulse-type parameter (e.g. a button par).

Get Python help documentation for a TD class/module.

List available Python classes in the TD runtime. Returns a JSON envelope.

Set parameter safety bounds with enforcement mode.

Clear parameter bounds for specific paths, or all bounds if paths is None.

Detect instability signals: FPS, heavy cookers, critical errors.

Emergency stabilization: pause timeline, clamp safety, capture baseline snapshot.

Capture a scene snapshot (structure + params; optionally visual).

List saved scene snapshots (newest first).

Diff two snapshots, or a snapshot against live state.

Restore parameter values from a previously saved snapshot.

This tool replays the parameter values captured in the snapshot back onto the live TouchDesigner network. It restores parameter values only — it does not add, remove, or rewire nodes. For structural rollback (topology changes such as added/deleted nodes or connection changes) use TouchDesigner's native Ctrl+Z undo stack instead.

Use dry_run=True to preview what would be changed without applying anything. Supply partial with a list of node paths to limit the restore to a subset of the snapshot.

Aggregated scene state vector (cached for _tr.TD_STATE_VECTOR_TTL seconds).

Read beat/phrase-derived timeline state (bars, beats, phrase position).

Return where the user currently is in TouchDesigner: active network pane, selection, project metadata, timeline state. Reduces the cold-start tax of needing to ask the user 'what path are you working in?' before every patch.