td-atlas

Overview Schema Source Related Servers Discussions Admin

td_snapshot

Save a component's current parameters, wiring, and DAT code to a file. Take before/after snapshots to diff changes or restore the earlier state.

Instructions

Save a component to a file so it can be diffed later.

This is how to keep "every parameter of this branch" before changing it, instead of dumping them to text by hand. path is the COMP holding the branch. Take one snapshot before a round of edits and another of the same path after, under a different label, then pass both files to td_project_diff. It lists each parameter that moved as name: before -> after, including expressions and custom parameters, and it lists wiring and DAT code too. That is three calls. Snapshots go to ~/.td-atlas/snapshots, and a label used again replaces its file, so reusing a label loses the state you meant to compare against.

The before snapshot is also the roll-back point. td_project_text on it gives each parameter in the form td_set_params takes, with {"expr": ...} where the diff shows only the expression's text. The diff does not mark which values are expressions, so put values back from the text, not from the diff. Paths in the file start at the COMP's own name, so a snapshot of /project1/branch holds /branch/blur1, which is /project1/branch/blur1 live. td_undo is shorter while the edits are still on the undo stack.

A component is written rather than the whole session because saving the session is a Save As: it repoints TouchDesigner at the snapshot file and leaves the artist working in ~/.td-atlas instead of their own project.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`path`	No		/project1
`label`	No		snapshot

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 7, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so thoroughly: it discloses the snapshot directory, that reusing a label replaces the file, that the diff does not mark expressions, and the path-relative behavior. It also explains the reasoning for snapshotting a component rather than the session.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every paragraph earns its place, covering purpose, workflow, file locations, pitfalls, rollback, and alternatives. It is front-loaded with the core purpose and organized logically.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a snapshot tool with no annotations and an output schema, the description is complete: it explains side effects, file locations, how to use snapshots with diff and text tools, rollback behavior, and why the tool exists. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, and it does. It defines `path` as the COMP holding the branch and explains `label` semantics, including that reusing a label overwrites the previous snapshot. This adds meaning far beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Save a component to a file so it can be diffed later.' It clearly distinguishes the tool from siblings by naming td_project_diff, td_undo, and td_project_text and explaining how each relates to snapshots.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use guidance: take a snapshot before editing, then after, and pass both to td_project_diff. It also gives a when-not-to-use alternative ('td_undo is shorter while the edits are still on the undo stack') and explains why saving the whole session is avoided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.