How do I use td-atlas?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@td-atlas check health of my running TouchDesigner instance" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

td-atlas

by grigabyte

Overview Schema Source Related Servers Score Discussions Admin

Python

Local

td-atlas

An atomised index of TouchDesigner, a live bridge into a running instance, and an offline reader for saved projects — exposed to AI agents over MCP.

An agent building in TouchDesigner needs three things at once: exact knowledge of the operators and parameters on this machine, control of a running instance that can be undone in one step, and a way to read a saved project without opening it. Miss the first and it guesses parameter names. Miss the second and a failed step leaves half a network behind. Miss the third and every question about an existing project needs the application running.

td-atlas is built on two observations:

Almost everything an agent needs to know about TouchDesigner already ships inside the application.
TouchDesigner reports almost nothing when work silently does nothing.

What it does — The atom index · The bridge · What TouchDesigner does not report · The call journal · Reading projects offline · The network text, written on save

Getting it running — Install · Compatibility · As an MCP server · The skill · As a bundle · Troubleshooting

Working on it — Documentation · Development · Layout · Contributing · Licence

The atom index

Two passes produce one SQLite index, exact for the build it was made from rather than scraped from a wiki describing some other release.

Static pass — offline, no TouchDesigner process, 23–30 seconds measured on an M-series Mac:

Source in the app bundle	What it yields
`Config/TDParameterHelp.json`	every operator and parameter: labels, prose, types
`Samples/Learn/OfflineHelp/`	the offline wiki — Python classes, operator pages, glossary entries, concept and technique articles
`Samples/Palette/`	ready-made components — projection mappers, corner-pinners, audio analysers
`Samples/Learn/OPSnippets/`	working example networks, one per operator
`Config/Help/{command.help,exprhelp}`	command and expression entries

Runtime pass — instantiates every operator type inside a non-cooking sandbox and reads what documentation does not record: defaults, numeric ranges and clamps, menu options, parameter pages and ordering, connector counts, and the contracted type names TouchDesigner writes when it saves. Cooking is disabled on the sandbox so that creating a Video Device In TOP does not open a camera.

The two passes do not add up, and the runtime pass is the reason: it finds operator types the help JSON does not describe and thousands of parameters it does not list — mostly the ones whose defaults and menu options are only knowable by asking a live instance.

The counts are a property of your build, not of this README. Run td-atlas status: it prints the operators, parameters and wiki articles your index actually holds, and that line — not this page — is what the project treats as authoritative. For scale, on the build this README was written against (2025.32460, macOS) it reads 667 ops, 24251 params, 2060 articles.

Related MCP server: TDPilot

The bridge

A Web Server DAT and a callbacks DAT, built from a script rather than shipped as a .tox — so the bridge is readable, diffable, version-controlled, and re-running the bootstrap upgrades it in place (or td-atlas reload, through the bridge itself).

Beyond exec:

td_health — the silent-failure detector. See below.
render — any TOP's pixels back as PNG, plus contact sheets for anything time-based, because a strobe judged from one frame is a coin toss.
batch — several operations inside one ui.undo block. A failed batch rolls back and leaves no partial network. A successful one is a single Ctrl+Z for the artist.
errors — every node reporting an error or warning.

Requests are authenticated with a token by default.

What TouchDesigner does not report

errors covers what TouchDesigner calls an error. td_health covers what it does not:

TouchDesigner (TouchDesigner Non-Commercial) — 61/60 fps, 16/51 operators cooking
[ERROR] 33 operator(s) did not cook once in 91 frames. A branch nothing
        displays or records is never pulled, so it is not running at all
         /project1/AV/fb, /project1/AV/out, /project1/AV/rec
[ERROR] 1 operator(s) had their resolution silently reduced by the licence —
        the output is smaller than asked for
[ERROR] 1 output operator(s) switched off — these produce nothing and report
        no error
         /project1/AV/aout (audio output)
[WARN ] 1 operator(s) cost more than 8 ms per cook (a whole frame at
        60 fps is 16.7 ms)
         /project1/src_b (430 ms)
[note ] Non-Commercial licence: resolution is capped at 1280x1280, realtime
        H.264/H.265 export on Nvidia GPUs is unavailable, and the result may
        not be used in paid work

Findings from a real session, re-rendered by the printer the code has now and wrapped for this page. The path lists are cut to what was recorded: the real output prints up to six paths under a finding and then +N more, and the clamped-resolution finding names its operators too.

Every one of those was hit while building a real composition; none of them raised an error. It also distinguishes a genuinely dead network from a paused timeline or a backgrounded window, where the frame clock is frozen and there is no evidence either way.

The call journal

The status panel inside TouchDesigner holds the last call and the next one overwrites it. That answers "is the bridge alive"; it does not answer "the agent broke something yesterday, what was it". ~/.td-atlas/calls.jsonl does: one line per bridge call, written by the host, outliving the session.

$ td-atlas log --failures
08-29 22:23:51  FAIL  op_info             16.6ms  /project1/does_not_exist
        LookupError: no operator at path '/project1/does_not_exist'
08-29 22:23:51  FAIL  par_set             16.5ms  /tdatlas/jrn_noise
        AttributeError: /tdatlas/jrn_noise (noiseTOP) has no parameter 'nosuchpar'

$ td-atlas log --summary
11 calls, 5 failed (45%)   08-29 22:23 to 08-29 22:23

where it fails
  op_create          1 of 2
  par_set            1 of 2
  exec               1 of 1

Both samples are cut short. --failures ends with the mapped repair for the most recent refusal — a cause: and a fix: line; --summary also names the refusal types on a reasons: line and lists the five slowest calls.

td_log is the same thing for an agent, so it can read its own trail rather than repeat a call that already refused.

Written by the host and not by the bridge, deliberately. A Table DAT inside TouchDesigner dies with the process, and keeping it would mean saving the project — which is a Save As that moves the artist's file. A file written from inside a frame was measured at 124–200 us, three to five times the whole panel repaint. On the host the append costs 41.6 us of nobody's frame, next to a round trip that already cost 16 ms.

Bounded at 1 MiB — about 5,300 calls, measured — with the oldest lines dropped first. Parameters are not logged: only the method, the outcome, the duration, the path, the caller and a batch's step count. A DAT's text and a whole network stay out of it, and the bridge token is scrubbed from every line before it is written.

Reading projects offline

TouchDesigner ships toeexpand, which unpacks a .toe/.tox into a tree of text files. td-atlas reads that tree, so a project can be inspected, searched and compared without TouchDesigner running — and without touching the original, since everything happens on a copy in a cache.

td-atlas project read  myproject.toe --path /project1 --params
td-atlas project grep  myproject.toe "def onValueChange"
td-atlas project diff  before.toe after.toe
td-atlas project variant save myproject.toe --label before-the-rewire
td-atlas project variant diff myproject.toe --label before-the-rewire --other after

grep reaches code no file search can: the Python and GLSL inside DATs lives in the container, not on disk. diff compares meaning — added, removed, retyped, rewired and re-parameterised operators, plus a line diff of changed DAT code, with pure repositioning kept separate so it cannot bury a real change. Paired with td_snapshot that is an audit trail for agent edits.

The file formats are undocumented, so the readers were derived by measurement: the payload prologue is a fixed 27 bytes with a length field (scanning for a newline instead corrupts about a third of the shaders), bit 4 of a parameter's flags word marks expression mode, and the 71 saved-name aliases come from instantiating every type and comparing what TouchDesigner writes with what it reports.

The network text, written on save

The bridge can write the network out as text beside the .toe every time the artist saves, so a project gets a diffable history in git without anybody remembering to ask for one. It is off by default — writing a file into somebody's own project folder is not something to start doing unasked — and turning it on is one key in ~/.td-atlas/config.json:

{ "text_on_save": true }

The file is <project>.network.json beside the .toe, in the same format td-atlas project text produces. The version number TouchDesigner adds on each save is stripped, so one project keeps one text and git holds the history. The write is atomic (a temporary in the same directory, then a rename), and a file already at that name that is not one of ours is never overwritten — the bridge refuses and says so on its status panel.

Measured on 2025.32460, the text costs about 0.25–0.30 ms per operator, so networks are covered up to a cap of 2000 operators — beyond that the save would grow by more than half a second and the bridge writes nothing, again saying so on the panel. Raise it with "text_on_save_max_ops" if you would rather wait.

The text covers the artist's own root components. TouchDesigner's /local and /perform, the bridge's own /tdatlas, and the external .tox roots /ui and /sys are left out — each by a measured rule the handler's comments give.

This text is printed from the live network, and the one td-atlas project text prints is read from the expanded file, so the two are not byte-identical. Seven classes of difference are known and nothing else was left over: measured on 2025.32460 over a purpose-built network of 45 operators — 21 built by the fixture, the other 24 the annotation component's own subtree — 104 of 722 compared fields differ.

fields	class	why
80	custom parameter placement	The file keeps a custom parameter's value in `.parm` beside the built-in ones and its definition in `.cparm`, which the reader does not parse — so the reader files the value under `parms` where the live side files it under `custom_parms`. Forty parameters, two fields each.
10	custom parameter at its default	A custom parameter still at its default has no `.parm` line at all, so the file side has nothing to show; the live side prints every custom parameter.
8	float text formatting	The file keeps TouchDesigner's own printing (`2e+06`), the live side prints `2000000`.
3	parameter at its default with a flags word	`.parm` carries a line for a default-valued parameter whose flags word is not zero; the live side drops anything `isDefault`.
1	COMP input wiring	A COMP's operator input is stored in a `.network` file, which the offline reader does not parse, so the file-side text shows no inputs where the live-side text shows them.
1	flag vocabulary	`.n` flags the live gather has no name for (`showDocked`).
1	the `.tox` save's own root parameter	`enableexternaltox` is written into the root of a saved `.tox` and of no `.toe` — an artefact of how the measurement was taken, not of the text.

None of those numbers is a memory: tests/live_network.py builds the network again and tests/test_live_text_diff.py fails if a field falls outside these seven classes. It sits behind the live marker, so a plain pytest does not collect it at all; pytest -m live runs it, and needs an instance with the bridge.

Two more classes stood here until the measurement found their cause, and both were bugs of ours rather than limits of the text. The .table header's row and column counts were read the wrong way round, so a 3×2 table came back as 2×3 — and the round trip had never caught it, because the writer repeated the same swap. And a panel COMP's wire to the COMP beside it sits in the file's inputs block while live it hangs off inputCOMPConnectors, which the live gather did not read; it now reads both connector lists, each wire under its own connector's index. Both sides are fixed.

Install

Nothing has been released yet. The repository is not public and no version has been tagged, so three of the addresses named on this page resolve to nothing today: the clone URL below, the plugin marketplace under The skill, and the release the bundle's registry submission points at under As a bundle. Each of them is the address it will have, and each says so where it appears — a 404 there is the state of the project, not a mistake at your end. Everything else on this page works from a checkout you already have.

TouchDesigner has to be installed first: the index is built from your copy of the application and holds the values that copy reports, so there is nothing to download. Python 3.11 or newer. See Compatibility for platforms and for what the connector can change in your project.

git clone https://github.com/grigabyte/td-atlas   # public with the first release
cd td-atlas
uv venv                     # or: python3 -m venv .venv
uv pip install -e .         # or: .venv/bin/pip install -e .

There is no package on PyPI, so pip install td-atlas and uvx td-atlas will not find anything — the checkout is the install. Then, from the checkout:

.venv/bin/td-atlas build      # offline index, 23–30 s, no TouchDesigner process
.venv/bin/td-atlas install    # stage the bridge, print the bootstrap and MCP lines

Everything below writes td-atlas for short. Unless the virtualenv is activated, call it by path — .venv/bin/td-atlas, or .venv\Scripts\td-atlas on Windows — because a system Python will not see the package.

td-atlas install prints two things to paste. First, into TouchDesigner's textport (Dialogs → Textport and DATs), once per project:

exec(open('/Users/you/.td-atlas/bootstrap.py').read())

Second, a claude mcp add line for your MCP client — see below. Pass --write-mcp-json DIR to additionally write (or merge into) DIR/.mcp.json with that same entry.

Then, with TouchDesigner open and the bridge staged, complete the index with the runtime facts only a live instance knows:

td-atlas probe

Then td-atlas doctor, which is the only thing here that says whether the install actually took. It names the repair on every link that is not ok and exits non-zero when one is broken, so it also tells you where you are if you came in halfway: on a host with nothing built it reports index : FAIL … fix: td-atlas build and bridge : warn … fix: td-atlas install.

Compatibility

TouchDesigner. Everything here was measured against build 2025.32460. The index is not a copy of a wiki — it is read out of the application directory you point at, so another build gives another index; td-atlas doctor catches an index built from a TouchDesigner that has since been moved, updated or replaced, which nothing else reports. The bridge and the host agree on a protocol version and refuse each other when they disagree, naming the side that is behind.

Python. 3.11 or newer on the host. The code that runs inside TouchDesigner is held to 3.11 with no third-party imports, because that is the interpreter the application ships.

Operating systems.


macOS	developed and measured here; every number in this README comes from it
Windows	the code paths run in CI (`windows-latest`, Python 3.11-3.14, first run 2026-09-07); TouchDesigner on Windows is unverified — no Windows machine with TouchDesigner on it was ever involved
Linux	not supported: TouchDesigner is not released for it

What is still unverified on Windows, precisely: the install-discovery layout follows Derivative's published install tree rather than measurement; toeexpand's path separators are inferred from its macOS output; the clipboard copy (clip) has never been run. And two things are now known to be weaker there. ~/.td-atlas and the token file in it are narrowed with chmod, which on Windows sets only the read-only attribute — measured: the directory reports mode 0o777 where 0o700 was asked for, so other accounts are kept out by whatever ACL the user profile already carries and by nothing this project does. And the call journal cannot report a home that refuses writes, because os.access does not see a refusal there.

CI's windows-latest leg (.github/workflows/ci.yml) ran for the first time on 2026-09-07, and that is what turned those from inferences into readings. It found eleven failures. Four were defects in this code: both of the registry's liveness probes, the project path written into a bridge's registry record, and the encoding of the generated bundle manifest. One was a test asserting a POSIX separator about a Windows filesystem path. The remaining six are checks whose premise Windows does not have — os.chmod there can neither narrow a mode nor make a path refuse access — and they skip with that reason written out, in tests/windows_gaps.py.

All four are fixed, but the fourth took three more runs and two wrong diagnoses. A port with nothing on it read as "cannot tell" there, and that was first blamed on WSA error numbers the POSIX errno names did not match — Windows' errno is the WSA table, so they matched all along. It was then blamed on the connection not resolving at all, because the next run printed 10035, CPython's way of saying its own timeout elapsed. Both were guesses about a duration nobody had measured. Instrumented, the runner answered: a closed loopback port there refuses in about two seconds — eight samples across the four Python versions, 2002 to 2041 ms — against 0.04 ms on macOS. The 0.25 s the probe allowed was simply short, so it is now 3 s on both systems, and a bridge that is gone reads as absent on Windows too. What that costs is about two seconds, once, for each dead record td-atlas instances prunes there; the number and the trade are written on config.py's PROBE_BUDGET.

One more reading came out of those runs, on Python 3.11 alone: time.time() on Windows stepped in ~15.6 ms jumps until CPython 3.13, so a test that asked whether one registry write followed another read both as the same instant. The timestamp is right — the host is a different process and compares it against its own wall clock — so the test stopped asking a clock for a resolution it does not have. Its reasoning is in tests/test_instances.py::test_the_record_is_refreshed_by_traffic_but_not_by_every_request.

What the leg does not close: a GitHub runner has no TouchDesigner and cannot have one, so everything that discovers an installation or shells out to toeexpand skips. A green Windows column means the Windows code paths run and their unit tests pass — not that TouchDesigner on Windows has ever been driven by this code.

What this can change in your project. Worth reading before pointing an agent at work you care about.

The bridge is a component inside your open project. Pasting the bootstrap line builds /tdatlas in the running project — a Web Server DAT, a callbacks DAT and a status panel. Re-running the line upgrades those nodes in place. It is a node in your network like any other, and it is saved with the project if you save the project.
Edits are real edits. td_build, td_set_params, td_set_flags, td_annotate, td_extension_add, td_palette_load and td_exec change the live network. td_build wraps a batch in one ui.undo block, so it is a single Ctrl+Z, and a failed batch rolls itself back; td_exec is arbitrary Python and carries no such guarantee.
Nothing saves your project. No tool calls project.save(). td_snapshot writes a component to ~/.td-atlas/snapshots, deliberately: saving the session would be a Save As and would leave you working inside ~/.td-atlas rather than your own file.
Writing text beside the .toe is off by default and needs "text_on_save": true in ~/.td-atlas/config.json. A file at that name that is not one of ours is never overwritten.
Reading a project never touches it. toeexpand and toecollapse work in place, and toecollapse renames the original to <name>.bkp1 — so every offline read copies the file into a cache under ~/.td-atlas/cache first. Writing (td_project_write, td_variant_restore) refuses an output path that already exists rather than replacing it.
On the host td-atlas writes only under ~/.td-atlas: the index, the staged bridge, the call journal calls.jsonl (capped at 1 MiB), snapshots, variants and the expansion cache. The cache is capped by count and evicted least-recently-used; td-atlas doctor says how many expansions it holds and td-atlas doctor --clear-cache empties it.

As an MCP server

Run td-atlas install and paste the claude mcp add … line it prints — it points at the current interpreter by absolute path, so it keeps working regardless of the MCP client's own working directory or whether any virtualenv is activated. Wiring it in by hand looks like:

claude mcp add td-atlas -- /path/to/python -m td_atlas.cli mcp

41 tools in three groups: 9 index tools that work offline, 23 live tools that act on a running instance, 9 project-file tools that read and write .toe/.tox from disk. Every one of them, with its arguments and what it is for, is listed in plugin/skills/touchdesigner/references/tools.md — one list, held to the code by a test, rather than a second copy here that would drift.

td_build and td_set_params validate parameter names against the index before sending, so the usual mistakes come back as corrections:

- t: is a parameter group, not a settable parameter (try: tx, ty, tz)
- typ: no such parameter (try: type, ty)
- type: 'simplex5d' is not a valid menu entry
        (try: simplex4d, simplex3d, simplex2d, sparse, perlin4d)
- period: -3 is below the clamped minimum 0.0

The skill

plugin/skills/touchdesigner/ is an agent-facing guide: how to work through the connector, and a reference of every trap that produced no error while costing real time — dormant branches, CPU operators hiding in a menu, feedback loops that converge to grey, an audio codec that reports success and writes no file, a licence that halves your resolution without saying so.

It installs as a plugin rather than by copying the directory, so that updating it is one command instead of a second cp nobody remembers to run. This repository is its own marketplace — from the first release, since a marketplace is fetched over the network and this repository is still private:

/plugin marketplace add grigabyte/td-atlas
/plugin install touchdesigner@td-atlas

Later, /plugin marketplace update pulls in whatever the skill has learned. Until the repository is public the skill is the directory in your checkout — point an agent at plugin/skills/touchdesigner/SKILL.md and nothing else is missing but the one-command update.

As a bundle

.mcpb is an MCP Bundle: a zip holding a local MCP server plus a manifest.json describing it, which a supporting client installs when you open the file. Build one from a clean checkout:

.venv/bin/python scripts/build_mcpb.py

It writes dist/td-atlas-<version>.mcpb, regenerates packaging/manifest.json from pyproject.toml, and writes dist/server.json — the submission for the official MCP registry, carrying the SHA-256 of the bundle built beside it. The download URL inside that submission names a GitHub release that does not exist yet. Publishing is a separate, deliberate step — scripts/publish.sh, which is what creates that release — and until it has been run the bundle is something you build and open locally, not something to hand out. What that step checks first, and what it does not, is in docs/publishing.md.

Two things the bundle does not carry, and cannot: the index, which is built on your machine from your installation and holds machine-specific values, and the bridge, which needs td-atlas install and one pasted line. So a bundle install gives you the project-file tools immediately and tells you which command unlocks the rest.

Troubleshooting

td-atlas doctor is the first move for anything that looks like a setup problem: it walks the chain — environment, TouchDesigner, index, index build, probe, bridge, MCP server — and prints the command that repairs each broken link, exiting non-zero when one is broken. The table below is what the messages mean.

Symptom	What it is	What to run
`doctor` says `bridge : absent`	a state, not a fault: no TouchDesigner has registered a bridge and nothing is listening on the port	open the project and paste the `td-atlas install` bootstrap line into the textport
a live tool refuses with "nothing answered on the bridge port"	TouchDesigner is not running, or is running without the bridge	`td-atlas doctor`, then the bootstrap line
"The running bridge reports protocol N, below the minimum 7 this client supports" — and, from an MCP tool, that line plus the hint "the bridge and this host speak different protocol versions"	the staged bridge is older (or newer) than this checkout. The oldest bridge accepted is protocol 7; an older one is refused at connect rather than allowed to fail later on the first new method	`td-atlas reload` — it is the one command that talks to a bridge the version check would otherwise reject
a call comes back `UnknownMethod`	same cause, seen from the other side: the bridge has no such method because it was staged from an older package	`td-atlas reload`, then repeat the call
"the bridge rejected the token this host sent"	the bridge's token and `~/.td-atlas/config.json` disagree	`td-atlas doctor` compares them; `td-atlas install` re-stages against the current one
"something answered on that port but not with a bridge reply"	another program holds the port, or the Web Server DAT is misconfigured	`td-atlas doctor`, then `td-atlas install`
a call times out	every request runs on TouchDesigner's main thread during a cook, so a long script blocks it	wait, then retry in smaller pieces rather than one long `td_exec`
"this host has no atom index yet"	nothing was built	`td-atlas build`, then `td-atlas probe` with TouchDesigner open
"the index names a file that is not on disk"	TouchDesigner was moved, updated or reinstalled since the index was built	`td-atlas build`, then `td-atlas probe`
`doctor` says `index build` disagrees	the index was built from a different TouchDesigner than the one installed now. Nothing else reports this — the tools simply answer with the other build's values	`td-atlas build`
a network reply ends `TRUNCATED:`, or a line reads `... N more child(ren) not listed`	the network is larger than one reply carries — the node budget, or the per-component child cap; the cut is named so it is not read as the whole network	ask again with a narrower `path`
a line reads `... N direct child(ren), not walked at depth D`	not a cut at all but the depth you asked for, said out loud: a leaf and a component holding thousands of operators would otherwise arrive as the same line. `N` counts direct children only, so what hangs below them is not in it	ask again with a larger `depth`, or `path` at that node
`td_errors` says "the walk stopped after N operator(s) at and under `path`", or `td_health` says "only N operator(s) at and under `path` were sampled"	the walk hit its node budget: "nothing is wrong" covers the part that was walked and nothing else, and the remainder each names is a floor, not a total	run it again on a subtree, with `path`
`td_errors` reports nothing about a component you just built	its `path` defaults to the project. Asking it for `/` is worse, not better: the walk is breadth-first and bounded, and TouchDesigner's own `/ui` and `/sys` swallow the budget before anything of yours is reached	name the component in `path`
`td_health` reports script errors it could not read	the read failed on this build; unknown, not clean	the reply names the reason; treat that area as unchecked
a write refuses because the output already exists	deliberate: `toecollapse` renames what it finds to `<name>.bkp1`, so nothing is written over	choose a path that does not exist
`~/.td-atlas/cache` has grown	every offline read unpacks a copy there; it is capped and evicted least-recently-used, but an old cache stays until you say so	`td-atlas doctor` says how many expansions it holds, `td-atlas doctor --clear-cache` empties it
the MCP client cannot start the server	it is launching an interpreter that has no `td_atlas` installed	`td-atlas install` prints the exact `claude mcp add` line, absolute interpreter path and all; `doctor`'s `mcp server` link verifies it

td-atlas log --failures shows what the bridge actually refused, with timestamps, after the fact; td_log is the same for an agent.

Documentation

Document	For
`plugin/skills/touchdesigner/SKILL.md`	Agents using the connector
`plugin/skills/touchdesigner/references/gotchas.md`	Every trap that produced no error
`plugin/skills/touchdesigner/references/tools.md`	All 41 MCP tools
`AGENTS.md`	Agents contributing to this repository
`CONTRIBUTING.md`	How to run the tests and the linter before a pull request
`CHANGELOG.md`	What changed per version, and every protocol change without fail
`docs/architecture.md`	How the three layers fit together, and why
`docs/cli.md`	Every `td-atlas` subcommand and flag, and what each one needs
`docs/decisions.md`	A dated register of the decisions that shaped the code
`docs/formats.md`	The reverse-engineered `.toe`/`.tox` format, with evidence
`docs/publishing.md`	What is checked before a release, and by which command

Development

uv pip install -e . pytest
pytest                  # needs no running TouchDesigner
pytest -m live          # the rest: needs one running, with the bridge
uvx ruff check .
td-atlas reload         # re-stage the bridge and reload it through itself

The suite is the invariant: no test fails for want of a running TouchDesigner. That is held two different ways, and the difference matters when you read a summary. Tests that drive a live instance sit behind the live marker, which pyproject.toml deselects — a plain run does not collect them, and says how many it left out rather than counting them as passes. Tests that need TouchDesigner merely installed skip instead, and say so, because the same checks pass on any machine with the application present. So a plain pytest is green on a machine with neither.

See AGENTS.md before changing anything — particularly the code that runs inside TouchDesigner, which is Python 3.11 with no third-party imports and a hard rule against blocking.

Layout

td-atlas/
├── README.md               this file
├── AGENTS.md               contributor guide, human or agent
├── CONTRIBUTING.md         the short version: how to run the checks
├── CLAUDE.md               entry points for an agent opening this repository
├── CHANGELOG.md            Keep a Changelog; every protocol change is in it
├── LICENSE                 MIT
├── pyproject.toml
├── .gitignore
├── .github/
│   ├── workflows/ci.yml    pytest and ruff, macOS and Windows, Python 3.11-3.14
│   └── ISSUE_TEMPLATE/     build, OS and `td-atlas doctor` output
├── docs/
│   ├── architecture.md     the three layers and the reasoning
│   ├── cli.md              every subcommand and flag, and what it needs
│   ├── decisions.md        the dated register of decisions behind the code
│   ├── formats.md          the undocumented .toe format, measured
│   └── publishing.md       the release gates, each with its command
├── .claude-plugin/
│   └── marketplace.json    this repository as a marketplace
├── packaging/
│   ├── manifest.json       the MCPB manifest, generated from pyproject.toml
│   └── .mcpbignore         what stays out of the bundle
├── scripts/
│   ├── build_mcpb.py       build the bundle, the registry submission, build.json
│   └── publish.sh          the one step that sends anything outward
├── plugin/                 the plugin the marketplace above offers, and
│   │                       the only part of this tree it installs
│   ├── .claude-plugin/plugin.json
│   └── skills/
│       └── touchdesigner/  the agent skill
│           ├── SKILL.md
│           └── references/{gotchas,tools}.md
├── src/td_atlas/
│   ├── install.py          locate a TouchDesigner installation
│   ├── config.py           the ~/.td-atlas handshake between host and TD
│   ├── cli.py              command line, parity with the MCP tools
│   ├── journal.py          the append-only trail of bridge calls
│   ├── atoms/              the offline index
│   │   ├── extract_static.py   pass over the app bundle
│   │   ├── probe.py            runtime pass, incl. type-alias derivation
│   │   ├── htmltext.py         wiki HTML -> text, with categories
│   │   ├── validate.py         parameter checking before anything is sent
│   │   └── store.py            SQLite schema, FTS5 search and ranking
│   ├── bridge/             talking to a running instance
│   │   ├── client.py           JSON-RPC over HTTP, stdlib only
│   │   ├── health.py           the silent-failure detector
│   │   └── filmstrip.py        contact sheets, with a stdlib PNG encoder
│   ├── component/          code that runs *inside* TouchDesigner
│   │   ├── bootstrap.py        builds the bridge network in place
│   │   ├── handler.py          the RPC handler
│   │   └── ruff.toml           TouchDesigner's injected globals, declared
│   ├── project/            reading .toe/.tox without TouchDesigner
│   │   ├── expand.py           driving toeexpand/toecollapse on a copy
│   │   ├── formats.py          the undocumented file formats
│   │   ├── model.py            the operator tree and type resolution
│   │   ├── diff.py             semantic comparison
│   │   ├── render.py           tree description and code search
│   │   ├── serialize.py        the whole network as text
│   │   ├── rebuild.py          the return leg: text back into a .toe
│   │   ├── variants.py         saved states, text plus a byte copy
│   │   └── release.py          building the bridge as a .tox
│   └── mcp/
│       ├── server.py           the MCP tools over all three layers
│       └── hints.py            the recovery table every refusal is rendered from
└── tests/
    ├── conftest.py         shared fixtures
    ├── live_network.py     the fixture network the live text diff is measured on
    └── test_*.py           a plain run needs no TouchDesigner running

Generated and not in git: .venv/, the index and staged bridge under ~/.td-atlas/, and dist/ — the built bundle, dist/server.json and dist/build.json, which records the commit the bundle came from so publish.sh can refuse a stale one. .mcp.json is written by td-atlas install --write-mcp-json and holds a path specific to your machine, so it is ignored too.

Ignored and not generated: memory-bank/, the owner's working notes. They are about how this project is worked on rather than what it is, so nothing in the tree above depends on them; what a reader needs out of them lives in docs/.

Licence

MIT — see LICENSE. TouchDesigner is a product of Derivative Inc.; this project is not affiliated with them and redistributes nothing from the installation, it only reads what is already on your machine.

Available Tools

41 tools

td_annotateA

Leave a note in the network saying what you built and why.

Reach for this at the end of a build, not as decoration: the network you made records what it does and nothing about why, and the person who opens the project next reads the network editor, not this conversation. An Annotate is a coloured box with your text in it, sitting beside the nodes it describes.

text is the body (newlines work), title the bar along the top. Without position the note is placed where it does not cover anything, and without size it takes the default 382x288 network units — make it big enough to enclose the nodes it is about and td_annotations will report them as the ones it covers.

Pass path (an existing note) instead of parent to rewrite that note rather than add another — the right call when you rerun a build. The reply always names the path the note actually has: TouchDesigner ignores the name given at creation, so name is applied afterwards and can be refused if a sibling holds it.

mode is comment, networkbox or annotate: a comment is text only, a network box groups nodes without a title bar.

ParametersJSON Schema

Name	Required	Default
`mode`	No
`name`	No
`path`	No
`size`	No
`text`	Yes
`color`	No
`owner`	No
`title`	No
`parent`	No	/project1
`position`	No
`font_size`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/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 well: it reveals that TouchDesigner ignores the name at creation, that the reply always returns the actual path, that omitted position avoids covering other items, and that size determines which nodes td_annotations reports as covered. It also explains the behavior of the three mode variants and the rewrite-vs-add distinction between path and parent.

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 prose is dense and front-loaded, starting with purpose before diving into parameter nuances. Every paragraph contributes non-obvious operational details, and the backtick parameter references keep the structure scannable despite its length.

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

Completeness4/5

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

For an 11-parameter tool with no annotations and an empty schema description, the description covers nearly every behavioral trap (name handling, placement, defaults, rewrite semantics). Small gaps remain around color, font_size, owner, and the empty-string default for mode, but an agent has enough to invoke it correctly in most cases.

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

Parameters4/5

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

Although schema coverage is 0%, the description gives meaningful semantics to most parameters: text, title, position, size, path, parent, name, and mode. It omits color, owner, and font_size, but those are largely self-explanatory from their names; still, the description does not fully compensate for the schema's complete lack of per-parameter docs.

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 ('Leave a note in the network saying what you built and why') and further defines an Annotate as a colored box with text placed beside nodes. It clearly separates this tool from its read-side sibling by noting that td_annotations will report the nodes a note covers.

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

Usage Guidelines4/5

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

It gives explicit when-to-use guidance ('Reach for this at the end of a build') and a when-not warning ('not as decoration'), plus a specific rerun-build rule for choosing path over parent. It does not name an alternative tool for reading or managing annotations, so the contrast with siblings is implicit rather than explicit.

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

td_annotationsA

Read the notes in a network — including the ones a person left for you.

Check this before building in a project you did not build. An artist can leave a brief as an Annotate beside the nodes it concerns, which is the natural place to put it and completely invisible to every other tool here: it is not an error, not a parameter and not a name.

Each note comes back with the nodes its box sits over, so a note saying "this chain is the one to keep" can be matched to the chain. That list is geometric — the tiles whose centre falls inside the box — so a node the artist dragged half out of the box counts as outside.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No		/project1
`depth`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden, and it does well by explaining that notes are returned with the nodes their boxes cover and that membership is geometric based on tile centers. The read-only nature is implied by 'Read,' but it stops short of stating permission needs or any error/edge-case behavior.

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 front-loaded with the core purpose and then adds usage guidance and a subtle geometric nuance. Each paragraph earns its place: what the tool does, when to use it, and what the returned node list actually means. No filler or repetition.

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

Completeness3/5

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

The behavioral and output aspects are well covered, and the output schema exists, so return structure is not the issue. However, the two parameters are entirely undocumented: the agent can call with defaults but cannot reason about non-default path or depth values. That is a significant gap for a tool meant to be invoked, not just understood at a high level.

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

Parameters1/5

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

Schema description coverage is 0%, and the description never explains what 'path' or 'depth' mean, nor what effect they have on the results. The defaults /project1 and 8 are present, but the agent has no way to know how to intentionally target another network or adjust depth.

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 object: 'Read the notes in a network.' It also clarifies scope ('including the ones a person left for you') and establishes differentiation by noting these notes are 'completely invisible to every other tool here,' so an agent can clearly tell this from siblings like td_annotate or project readers.

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?

It gives an explicit when-to-use instruction: 'Check this before building in a project you did not build.' It also tells the agent not to expect annotations to appear as errors, parameters, or names in other tools, effectively providing a when-not-elsewhere rule and preventing fruitless searches through siblings.

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

td_buildA

Apply several edits to the project as one atomic, undoable block.

Prefer this over separate calls: if any step fails the whole batch is rolled back, so the project never ends up half-modified, and a successful batch is a single Ctrl+Z for the person using TouchDesigner.

Each operation is {"method": ..., "params": {...}} where method is one of op_create, op_delete, op_connect, op_disconnect, par_set.

op_create takes parent, type, name, optional pars {name: value}, optional position [x, y], optional connect [{"from": path, "index": 0}], and optional text for a DAT's contents — shader and script source belongs there, not in a separate td_exec, so it lands inside this undo block. Values may be a constant, {"expr": "..."} for an expression, {"bind": "..."} or {"pulse": true}. Parameter names are validated against the index first.

Pass the same owner you claimed the area with — it carries into every step, and without it your own claim refuses the batch.

ParametersJSON Schema

Name	Required	Default
`owner`	No
`undo_name`	No	agent edit
`operations`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior5/5

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

No annotations are provided, so the description carries the full burden of explaining behavior. It does so thoroughly: atomic rollback, single undo, owner requirement, supported operation methods, value encodings, and validation order are all disclosed.

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

Conciseness4/5

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

The text is dense but organized: it opens with the core value proposition, then lists operation methods, expands op_create arguments, and closes with validation and owner requirements. Each sentence adds needed detail, though the nested format examples make it slightly long.

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

Completeness4/5

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

Given the complexity of batch editing with multiple operation types, the description covers the essential context: atomicity, undo behavior, operation syntax, parameter value forms, and ownership. It does not discuss return values, but an output schema appears to exist, so that is an acceptable omission.

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

Parameters4/5

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

The description adds substantial meaning for the central 'operations' parameter, enumerating methods like op_create and op_delete and detailing nested parameters such as pars, position, connect, and text. It also clarifies 'owner' by explaining it must be the claimed area. The 'undo_name' parameter is not explained, but the most complex parameter is richly documented.

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 precise statement: 'Apply several edits to the project as one atomic, undoable block.' It clearly identifies the resource (project) and the core action (applying edits in a batch), leaving no ambiguity about what the tool does.

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?

The description explicitly advises 'Prefer this over separate calls' and explains the benefit: atomic rollback and a single undo step. It also contrasts with td_exec by noting that shader/script text belongs in op_create rather than a separate call, giving clear usage direction.

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

td_claim_scopeA

Announce one subtree of the network as yours while you work in it.

Reach for this before a run of edits whenever another agent or session may be touching the same project: without a claim, two agents editing the same nodes overwrite each other and neither result reports anything wrong. owner is any string that identifies you (a task name, a session id) — it is what the other agent is told when it is refused.

The claim covers everything below path: '/project1/audio' includes '/project1/audio/eq1' but not '/project1/audio2'. It lapses on its own after ttl_seconds, so a crash cannot park a subtree for the session; claim again to renew. This is an agreement between agents, not a lock — it does not constrain a person editing those nodes by hand.

Write calls must carry the same owner to pass their own claim; the refusal text says which owner to send.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`owner`	Yes
`ttl_seconds`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden, and it delivers: path-scope semantics with examples, automatic TTL expiry, crash-safety implications, the fact that it is an agreement rather than a lock, and the requirement that write calls carry the same owner. This is unusually transparent and actionable.

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 front-loaded with the core purpose, then organized into coherent paragraphs covering usage, path semantics, expiry, and enforcement. Every sentence adds useful information for correct invocation; there is no filler or repetition.

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 coordination tool with no annotations and no parameter descriptions in the schema, this description covers why to use it, how claims work, how to refresh them, what happens on expiry, and how ownership is enforced on writes. The output schema exists, so not restating return values is acceptable. Nothing necessary for correct use 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 description coverage is 0%, so the description must explain the parameters. It does: 'path' is clarified with subtree boundary examples, 'owner' is explained as any identifying string shown in refusal messages, and 'ttl_seconds' is tied to expiry and renewal. This fully compensates for the bare input schema.

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

Purpose4/5

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

The opening line states a specific action and resource: 'Announce one subtree of the network as yours while you work in it.' This clearly communicates it is a claiming/ownership tool for a scope subtree, though it does not explicitly name or contrast sibling tools like td_release_scope or td_scopes.

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

Usage Guidelines4/5

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

The description gives clear when-to-use guidance: 'Reach for this before a run of edits whenever another agent or session may be touching the same project.' It also explains the failure mode it prevents and how to renew a claim. It does not explicitly mention when not to use it or point to release alternatives, but the usage context is strong.

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

td_docsA

Search or read TouchDesigner's documentation, mirrored offline.

Pass page to read one article in full (for example 'Write_a_GLSL_Material' or 'Noise_TOP'); otherwise query searches all 2000-odd pages and returns matching excerpts. Covers concepts and guides, not just operators.

ParametersJSON Schema

Name	Required	Description	Default
`page`	No
`limit`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It communicates that the tool is a non-mutating read/search operation, that the documentation is 'mirrored offline', and that query results are 'matching excerpts' while page reads return full articles. This goes beyond the schema and covers the essential behavioral traits an agent needs.

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 compact and front-loaded. The first sentence states the core purpose, and the following sentences provide necessary mode details and scope. Every sentence adds value without redundancy or filler.

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

Completeness4/5

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

For a read-only documentation tool, the description covers the main functionality, both usage modes, the scope, and gives examples. It omits the `limit` parameter and doesn't explicitly compare with sibling tools, but those are minor gaps, especially since the output schema exists to cover return shapes. Overall it is sufficient for an agent to invoke the tool correctly in most scenarios.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must explain all parameters. It clearly explains `page` and `query` with examples, but does not mention `limit` at all. This leaves the agent to guess that `limit` controls result count. The description compensates well for the two main parameters but not completely for all three.

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 ('Search or read TouchDesigner's documentation') and immediately clarifies the two modes: passing `page` reads one article in full while `query` searches all pages and returns excerpts. It also distinguishes itself from operator-specific siblings by noting it 'covers concepts and guides, not just operators.' This is clear and differentiated.

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

Usage Guidelines4/5

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

The description gives explicit guidance on when to use `page` versus `query`, with concrete examples. The phrase 'not just operators' implies a broader scope than sibling tools like td_search_operators, but it stops short of explicitly naming alternatives or stating 'use this instead when...' so the routing guidance is implied rather than fully explicit.

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

td_doctorA

Check the whole chain — install, index, probe pass, bridge, this server.

Run this when something is wrong and it is not obvious which link broke, or before trusting a long build session. The trap it exists for is the one that raises nothing: an index built from a different TouchDesigner build still answers every question, with defaults and menu options that describe the other build, so an agent configures parameters that may not exist and the only symptom is a network that quietly does not work. It also separates 'not running' (a state) from 'registered but silent' and 'answering but refusing the token', which need different repairs. Each line names the command that fixes it.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It discloses that the tool checks the entire chain, separates distinct failure states ('not running', 'registered but silent', 'answering but refusing the token'), and emits lines that 'name the command that fixes it.' This strongly implies a read-only diagnostic that produces repair guidance. It does not explicitly state permissions or side effects, but the framing is behaviorally informative.

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

Conciseness4/5

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

The description opens with a one-line purpose, then the key usage trigger, then the motivating failure mode and state distinctions. It is longer than strictly necessary, but every sentence contributes meaningful diagnostic context rather than padding.

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

Completeness4/5

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

For a parameterless diagnostic tool with an output schema, the description provides the when, why, what it checks, what states it separates, and what the output conveys. It is sufficiently complete for an agent to decide when to invoke it and what to expect, though it could be slightly stronger with an explicit statement about whether it makes changes.

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

Parameters4/5

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

The tool takes zero parameters, and schema description coverage is 100%, so there is nothing for the description to add about inputs. The zero-parameter baseline applies.

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

Purpose4/5

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

The description clearly states the tool's mission: 'Check the whole chain — install, index, probe pass, bridge, this server.' It is specific about the resource and the diagnostic nature of the tool, and its scope ('whole chain') implies a distinction from per-component siblings like td_status or td_log, though it does not explicitly name them.

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

Usage Guidelines4/5

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

The description gives explicit trigger conditions: 'Run this when something is wrong and it is not obvious which link broke, or before trusting a long build session.' This is actionable and context-rich. It does not explicitly list when not to use it or name alternative tools, but the guidance is clear enough for an agent to select it appropriately.

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

td_errorsA

Every operator at or under path currently reporting an error or warning.

Node errors are shown as colours in the TouchDesigner UI and are otherwise invisible to you; check this after building something.

The default is the project, not /, and asking for / is usually the wrong move: the walk is breadth-first and bounded, and on an open session TouchDesigner's own /ui and /sys are thousands of operators wide at the shallow levels, so the budget runs out before the walk reaches anything of yours. Point it at the component you built instead.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No		/project1

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and does so well: it discloses that the traversal is breadth-first and bounded, that the budget can run out before reaching user operators when starting from `/`, and that node errors are otherwise invisible. This is meaningful behavioral context beyond the raw schema.

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 tight and front-loaded: the purpose appears in the first sentence, followed by why the tool exists and how to choose the path. The longer budget explanation is directly relevant to avoiding a realistic failure mode, so every sentence earns its place.

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?

Given a single optional parameter and an output schema that can document return values, the description is complete for a diagnostic tool. It covers purpose, when to use it, path-selection pitfalls, and the bounded-walk behavior. No important operational context appears to be 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 description coverage is 0%, so the description must explain the `path` parameter, and it does thoroughly: the default is the project, `/` is usually the wrong target, the walk is bounded, and users should point at their built component. This adds substantial meaning beyond the schema's bare type/default.

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

Purpose4/5

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

The description clearly states the tool returns every operator at or under `path` that is reporting an error or warning, and explains why this matters (errors shown as UI colours are otherwise invisible). It does not explicitly distinguish itself from sibling diagnostic tools such as td_status or td_health, so it stops short of a full sibling differentiation.

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

Usage Guidelines4/5

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

The description explicitly advises checking after building something, warns that the default is the project rather than `/`, and tells the user to point at the component they built. It gives clear context and an exclusion (root is usually wrong), but it does not reference alternative tools or state when to prefer a sibling tool over this one.

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

td_exampleA

Show a working example network for an operator.

TouchDesigner ships an example .tox for most operators. This reads one offline and describes how it is wired and configured — a real usage reference rather than a parameter list.

ParametersJSON Schema

Name	Required	Description	Default
`depth`	No
`op_type`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses that the tool reads 'offline' and describes a .tox example, implying a read-only, non-destructive operation. It doesn't mention what happens if no example exists for the given op_type, whether the output is textual or structured, or any failure modes. However, 'reads one offline' does provide some behavioral signal that this is a safe, local lookup.

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 compact: a one-line purpose followed by a two-sentence elaboration explaining the source (.tox) and the value proposition (real usage reference vs parameter list). Every sentence earns its place — no fluff, no repeated tool name, and the key distinction is front-loaded.

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

Completeness3/5

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

There is an output schema (not shown, but flagged as present), so the return structure may already be documented elsewhere. However, the description omits the depth parameter entirely, no failure-mode information, and no guidance on how to interpret the example. For a tool with only 2 parameters and an output schema, it is mostly usable but leaves a noticeable semantic hole around depth.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate for the two parameters (op_type and depth). It explains op_type implicitly as the operator for which the example is shown, but it never mentions the depth parameter at all. An agent cannot know from the description what 'depth' controls (likely traversal depth or recursion into the example network). The description adds minimal value beyond the schema for op_type and none for depth.

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

Purpose4/5

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

The description clearly states the tool's function: 'Show a working example network for an operator.' It explains the resource (a .tox example file for TouchDesigner operators) and what it does with it (reads it offline and describes wiring/config). While it doesn't explicitly contrast with a sibling tool, the verb 'Show' plus the specific focus on example networks distinguishes it from the many other td_* tools listed.

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

Usage Guidelines4/5

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

The description gives clear context: read an offline example .tox for an operator and use it as a 'real usage reference rather than a parameter list.' It implicitly guides the agent to use this when the user wants to see how an operator is wired/configured in practice, versus other tools like td_operator_schema (schema/params) or td_docs/td_python_api (reference docs). No explicit exclusions or alternatives are named, so not a 5, but the intended usage is reasonably clear.

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

td_execA

Run Python inside TouchDesigner and return its output.

The full td namespace is in scope (op, ops, root, project, ui, app, families, operator type classes). A trailing expression, or a variable named result, is returned. Reach for the structured tools first — this blocks TouchDesigner's main thread while it runs.

ParametersJSON Schema

Name	Required	Description	Default
`code`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden of behavior disclosure. It meaningfully discloses that execution blocks the main thread, that the full td namespace is available, and that the return value is a trailing expression or a variable named result. It does not mention that arbitrary Python could mutate the scene, but the blocking warning and execution semantics provide solid transparency beyond the raw schema.

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 short, front-loaded with the core purpose, and every sentence adds useful information: the execution environment, return semantics, and the blocking caution. No filler or repetition is present.

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

Completeness4/5

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

For a low-parameter exec tool, the description captures the essentials: what runs, what is available, what is returned, and what side effect to expect. It is complete enough for an agent to decide when to call it and how to shape the code input, though it could be more explicit about error behavior or the risk of scene mutation.

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

Parameters4/5

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

The input schema only says the code parameter is a string, so semantic guidance must come from the description. It explains evaluation conventions, such as using a trailing expression or a result variable, and clarifies that the full td namespace is in scope. This materially helps an agent construct valid input despite the 0% schema description coverage.

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: "Run Python inside TouchDesigner and return its output." It clearly identifies what the tool does and how it differs from the structured sibling tools by presenting it as a general execution escape hatch.

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

Usage Guidelines4/5

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

It explicitly advises "Reach for the structured tools first," which tells the agent to prefer siblings when possible. It also warns that this tool blocks TouchDesigner's main thread, a clear condition for when to avoid it. It does not name specific sibling tools or enumerate exact alternative conditions, so it stops slightly short of full 5-level guidance.

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

td_expression_helpC

Look up TouchDesigner expression and command syntax.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.7/5.0

Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure, but it only states the lookup purpose. It does not explain matching behavior, result format, syntax expectations, or any other operational details.

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

Conciseness4/5

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

The description is a single, scannable sentence with no filler words, and the core action is front-loaded. It is concise at the cost of missing useful context, but it is not verbose or poorly structured.

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

Completeness2/5

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

The presence of an output schema reduces the need to describe return values, but the description still leaves usage context and parameter semantics unresolved. Given the large number of documentation-related sibling tools, this one-liner is not enough for an agent to confidently select and invoke the right tool.

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

Parameters2/5

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

The schema has 0% description coverage, and the description does not clarify what 'query' should contain (e.g., operator names, exact expressions, partial syntax) or how 'limit' affects results. The parameter names are self-explanatory at a basic level, but the description adds no semantic value beyond them.

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

Purpose4/5

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

The description uses a specific verb ('Look up') and names a distinct resource ('TouchDesigner expression and command syntax'), so an agent can clearly see what the tool targets. It does not explicitly contrast with documentation/glossary siblings like td_docs or td_glossary, so sibling differentiation is lacking.

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

Usage Guidelines2/5

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

No guidance is provided about when to choose this tool over alternatives such as td_docs, td_python_api, or td_search_operators. There are no exclusions, prerequisites, or context clues beyond the tool's name and one-line description.

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

td_extension_addA

Attach a Python class to a COMP as an extension, in one call.

Reach for this instead of td_exec whenever a component needs methods or state of its own. Done by hand it is five steps — create the COMP, create the DAT, write the text, set three parameters on the Extensions page, re-initialise — and the last one fails silently: measured on 2025.32460, a wrong Extension Object expression or a class that raises in __init__ leaves the COMP reporting no error, no warning, and extensionsReady True, with the real message only in the textport. This tool reads the result back off the COMP and hands you that message.

Aim it either at path (an existing COMP) or at parent plus name (a baseCOMP to create) — not both. code must define class <class_name>, conventionally taking ownerComp and capitalising anything meant to be called from outside: with promote on, capitalised members are callable straight on the COMP, and every member is reachable as op(...).ext.<name>.<member> regardless.

The class name doubles as the name of the textDAT holding the code, which is what the generated Extension Object expression points at (op('./Name').module.Name(me)). extension_name renames the extension for ext lookups without touching the class. index picks which extension slot to write; the wiki says a COMP has four, the sequence took six here. A created COMP is given a free spot in the parent network unless position names one — [x, y] in network units, the left and bottom edges of the tile; it is ignored when aiming at a COMP that already exists.

The code is parsed on this host before anything is sent, so a typo costs no round trip. That check is not a guarantee TouchDesigner accepts it: this host's Python may be newer than TouchDesigner's embedded 3.11, so 3.12+ syntax passes here and fails there — which is caught, but only by the read-back above. Pass the same owner you claimed the area with, or your own claim refuses this write.

ParametersJSON Schema

Name	Required	Description	Default
`code`	Yes
`name`	No
`path`	No
`index`	No
`owner`	No
`parent`	No
`promote`	No
`position`	No
`class_name`	Yes
`extension_name`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A5/5.0

Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden, and it does so thoroughly: it reveals the silent-failure failure mode, the read-back verification, local parsing, Python-version mismatch risks, the owner-claim requirement, and the extension-slot behavior. This far exceeds minimal disclosure.

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 dense and front-loaded: the first sentence states the core purpose, then the manual five-step pain point, targeting rules, naming mechanics, and failure modes follow in logical order. There is no filler; every paragraph earns its place for a 10-parameter tool.

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 complex mutation tool with no annotations, the description covers when to use it, how to target a COMP or create one, parameter roles, error behavior, prerequisites, and version pitfalls. Nothing an agent needs to make a competent first call 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 description coverage is 0%, and the description compensates remarkably: it explains code/class_name, path vs parent/name, extension_name renaming, index slot selection, position coordinate semantics, promote behavior, and owner usage. Every ambiguous parameter receives meaningful context beyond its raw name.

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: 'Attach a Python class to a COMP as an extension, in one call.' It immediately distinguishes the tool from td_exec by stating when this is the right choice. An agent can tell exactly what capability is being offered.

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?

It explicitly says 'Reach for this instead of td_exec whenever a component needs methods or state of its own,' giving a clear selection rule. It also explains the two targeting modes — path vs parent+name — and warns not to supply both, plus when position is ignored.

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

td_flagsA

Read the flags that decide whether a node runs and what is visible.

Run this when a network looks right and produces nothing. A bypassed operator, a COMP with its display or render flag off, and a COMP with cooking disabled are all invisible in a parameter dump and in td_network, and each of them makes a correct network output nothing — the kind of silent failure that costs an hour of re-reading parameters.

unavailable names the flags this operator genuinely does not have, so you can tell "off" from "not a thing here". The clone master is a parameter rather than a flag, so it is not listed; cloneImmune is the flag half.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior5/5

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

With no annotations, the description bears the full burden and does well: it states this is a read operation, explains how to interpret unavailable (absence of flag vs off), and clarifies clone master vs cloneImmune. This gives an agent the exact semantics needed.

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

Conciseness4/5

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

The purpose is front-loaded and each paragraph adds specific value: use case, silent-failure explanation, and output semantics. The 'costs an hour' phrasing is slightly rhetorical but not wasteful.

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

Completeness4/5

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

For a one-parameter read tool with an output schema, the description provides enough usage context and return-semantics detail. The main gap is explicit path format guidance, which is minor given the low complexity.

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

Parameters2/5

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

The schema has one required parameter, path, with no schema description and 0% coverage. The description refers to 'node' and 'operator' but never states that path is the operator path or what format is expected, so the parameter semantics are left largely to inference.

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 first sentence, 'Read the flags that decide whether a node runs and what is visible,' names a specific verb and resource and immediately tells an agent what td_flags is for. It also implicitly distinguishes the tool from write-oriented siblings like td_set_flags.

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

Usage Guidelines4/5

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

The description gives explicit triggers: 'Run this when a network looks right and produces nothing' and enumerates bypassed operators, display/render flags off, and cooking disabled. It explains why other inspections (parameter dump, td_network) miss this, though it does not explicitly name alternative tools to use instead.

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

td_glossaryA

Look up TouchDesigner terminology.

185 glossary entries defining the vocabulary the rest of the docs assume: Cook, Time Slice, Par, CHOP, Clone, Tox, Perform Mode, Sample.

ParametersJSON Schema

Name	Required	Description	Default
`term`	Yes
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior3/5

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

With no annotations, the description carries the safety burden. 'Look up' clearly implies a non-mutating, read-only operation, and the 185-entry count sets scope. However, it does not disclose matching behavior (exact/partial/case-sensitive), what the limit does, or any response details beyond what an output schema might cover.

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 concise and front-loaded with the action and resource. The example list of representative glossary entries is not wasted; it concretely communicates the tool's scope and vocabulary domain.

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

Completeness4/5

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

For a simple two-parameter lookup tool with an output schema, the description supplies enough context: what it does, its scope, and sample terms. It does not explicitly explain parameter semantics, but the clearly named schema parameters and available output schema make the tool usable without major gaps.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must compensate. It partially does by providing example term values ('Cook', 'CHOP', 'Time Slice'), which clarify the 'term' parameter. However, it does not explain the 'limit' parameter's effect or the matching semantics, leaving some burden on the schema names.

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

Purpose4/5

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

The description states a specific verb ('Look up') and resource ('TouchDesigner terminology' / 'glossary entries'), and the 185 entries with examples make the tool's purpose clear. It does not explicitly name or contrast a sibling tool, but the glossary scope is distinct enough from the doc/operator/expression tools.

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

Usage Guidelines4/5

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

The phrase 'vocabulary the rest of the docs assume' gives clear context for when to use this tool: when encountering foundational TouchDesigner terms that other docs rely on. It does not explicitly mention alternatives or exclusions, but the usage context is well implied.

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

td_healthA

Find what is quietly broken — the failures nothing reports.

Run this after building anything, and whenever a composition "looks fine but does nothing". td_errors only covers what TouchDesigner calls an error; this additionally catches:

operators that never cook, because a branch nothing displays or records is never pulled and therefore is not running at all
output operators switched off (audio device, movie recorder, MIDI, OSC) which produce nothing and report nothing
GLSL operators whose shader failed to compile, quoting the compiler's own line: TouchDesigner only warns that an Info DAT would show the details
tracebacks raised inside callbacks and extensions (Execute DAT, Replicator, component callbacks), which are kept apart from the error list. A Script operator's onCook raising during a cook Python asked for is not covered — that traceback goes back to the caller instead
operators costing more than half a frame to cook, and the resulting frame rate collapse
bypassed operators, and the current licence

interval is the gap between the two samples, in seconds, and is capped: this process sleeps through it and answers nothing else meanwhile.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No		/project1
`interval`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/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 behavioral burden and meets it: it reveals the two-sample design, that interval is capped, and that 'this process sleeps through it and answers nothing else meanwhile' — an important blocking trait. It also discloses output behavior like tracebacks being kept apart from the error list and compiler-line quoting for GLSL.

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 section earns its place: a scannable bullet list of failure categories, an explicit exclusion, and a note on blocking behavior. Purpose and usage guidance are front-loaded before the detailed taxonomy, and there is no filler.

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

Completeness4/5

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

For a diagnostic tool with no annotations and no schema descriptions, the description covers when to run it, what it checks, what it does not check, and the blocking interval behavior. The main gap is the undocumented path parameter and the unspecified cap value, though the existing output schema reduces the need to describe return values.

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

Parameters3/5

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

The interval parameter gets a full semantic explanation as the gap between two samples with a cap and blocking behavior. However, the path parameter is never mentioned or explained; given 0% schema description coverage, the description only partially compensates for the schema's silence.

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 concrete mission, 'Find what is quietly broken — the failures nothing reports', then lists specific failure classes it detects, from never-cooking branches to GLSL compile failures and callback tracebacks. It also explicitly distinguishes itself from td_errors, making it easy for an agent to pick the right sibling.

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?

It gives explicit trigger conditions: 'Run this after building anything, and whenever a composition looks fine but does nothing'. It also states when not to expect coverage (e.g., a Script operator's onCook traceback is not caught) and names td_errors as the narrower alternative.

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

td_instancesA

Which TouchDesigner instances are running, and which one these tools reach.

Reach for this whenever the artist may have more than one project open — and always before believing that an edit went where you meant. Every other bridge tool here dials a single bridge chosen on this host (the session file, or a --port/--project flag given to the td-atlas CLI); with two TouchDesigners running, the one it picks may not be the one the conversation is about, and nothing in a successful result would say so. This lists all of them — project, port, build, pid and when each was last seen — and marks the one the other tools are talking to. Aiming at a different one is not possible from here (the CLI's --port/--project have no MCP equivalent yet): name the port to the user and let them decide, rather than assuming the edit landed where they meant.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.9/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 behavioral disclosure burden and meets it: it reveals that other tools may silently pick the wrong instance, that a successful result won't show this, and that this tool cannot retarget. It also notes the missing MCP equivalent of CLI flags, which is a meaningful limitation.

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 front-loaded with the core question and purpose, then each subsequent sentence earns its place by explaining when to use it, what it lists, and its limits. Despite its length, there is no filler; every sentence adds actionable context.

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 zero-parameter, read-oriented listing tool with an output schema present, the description covers scope, return fields, and the actionable user guidance. No critical usage context is missing.

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

Parameters4/5

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

This tool has zero parameters, so the baseline is 4; the empty input schema already provides complete property coverage. The description adds no parameter-level details, but none are needed.

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 by directly stating the tool's resource ('TouchDesigner instances') and its role ('which one these tools reach'), then explicitly says 'This lists all of them' with concrete fields. It clearly distinguishes this from sibling bridge tools that each target a single instance.

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?

It states exact triggering conditions: 'whenever the artist may have more than one project open' and 'always before believing that an edit went where you meant.' It also tells the agent what to do instead of aiming at a different instance ('name the port to the user and let them decide'), explicitly covering the when-not.

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

td_logA

Your own trail: every bridge call this host has made, and how it went.

Reach for this when something is wrong and you do not know what you did — an operator is missing, a parameter is not what you set, the artist says "it broke after you touched it". td_status shows only the last call and the next one overwrites it; this is the whole session, and it survives TouchDesigner being closed and reopened, so it also answers "what happened yesterday".

Also reach for it before repeating a call that failed. failures=True gives the refusals alone, each with the text it refused with, and the repair for the most recent one — repeating a call that a scope claim or a missing path already refused will refuse again for the same reason.

summary=True answers a different question: over everything recorded, which methods refuse and which are slow. Use it to notice a pattern you are inside of — the same method failing five times means the approach is wrong, not the call.

Not everything is here, and the gap matters: only calls that reached the bridge are recorded. The offline tools (td_project_read, td_docs, td_search_operators) never dial it and leave no trace, so an empty journal means no live work, not no work.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`method`	No
`summary`	No
`failures`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does this richly: it reveals persistence across TouchDesigner restarts, that only bridge-reaching calls are recorded, that offline tools leave no trace, and what failures=True/summary=True semantically return. There is no annotation contradiction to worry about.

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?

Although long, every sentence earns its place by adding a usage, behavioral, or caveat detail. The front-loaded summary gives an immediate mental model, and the short paragraph breaks keep it scannable despite the density.

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 tool with no annotations, four parameters, and an output schema, the description covers the core decision logic, persistence, recording limitations, and parameter behavior for the non-obvious flags. The only minor gaps—limit and method—are low-risk because their names and defaults make them self-explanatory, so nothing essential is missing for correct invocation.

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

Parameters3/5

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

Schema description coverage is 0%, so the description needed to compensate. It strongly explains failures=True and summary=True, including what they return and what questions they answer. However, limit and method are never tied to their parameters; their semantics are left to inference from names and defaults, making the compensation partial rather than complete.

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 clear, specific definition: it is a trail of every bridge call this host has made and how it went. It explicitly contrasts with td_status, which shows only the last call, and with offline tools that leave no trace, so an agent can tell exactly what td_log is and is not.

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?

The description gives concrete triggers: use it when something is wrong and you don't know what you did, when you are about to repeat a failed call, or when you need to spot method-level patterns via summary=True. It also names alternatives and caveats—td_status for last-call view and offline tools that never reach the bridge—so the decision boundary is explicit.

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

td_networkA

List the operators inside a component and how they are wired.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No		/project1
`depth`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior3/5

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

With no annotations, the description carries the burden of behavioral disclosure. 'List' implies a read-only operation and the description conveys the basic scope, but it does not mention whether depth controls recursion, whether path must point to a component, or any caveats about how the network is represented. The safe behavior is implied but not explicit.

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?

A single sentence that is front-loaded and free of fluff. Every word adds meaning, and it is appropriately sized for the tool's simple parameter set.

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

Completeness3/5

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

The description gives a clear mental model but omits practical details such as depth semantics, path scope, and any interaction with sibling project tools. Since an output schema exists, return values do not need explanation, but the description still leaves invocation details under-specified for a 0%-coverage schema.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must compensate. It gives partial context: 'inside a component' hints that `path` refers to a component, and 'wired' hints at the purpose of `depth`. However, it does not explain what depth values mean, how path resolution works, or how defaults behave.

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 uses a specific verb ('List') and specifies the resource ('operators inside a component') plus the relation ('how they are wired'). This clearly differentiates it from siblings like td_search_operators and td_operator_schema, which are about finding or describing operators rather than showing a network.

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

Usage Guidelines2/5

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

There is no explicit guidance about when to use this tool versus alternatives. The phrasing implies inspection of a component's internal wiring, but it never states when this tool is preferred over related tools or when it should not be used.

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

td_operator_schemaA

Every parameter of an operator: exact names, defaults, menu options, ranges.

Read this before creating or configuring an operator — it gives the names TouchDesigner actually accepts. Note that TouchDesigner's own documentation describes parameter groups (such as 't' for Translate) while the settable parameters are the members ('tx', 'ty', 'tz'); this returns the members. page filters to one parameter page.

ParametersJSON Schema

Name	Required	Description	Default
`page`	No
`op_type`	Yes
`include_hidden`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It discloses useful behavioral nuances: it returns member parameters rather than groups, and it notes that TouchDesigner's own documentation describes groups while this tool returns the actual settable names. It also mentions the page filter. It leaves some ambiguity about hidden parameters, but overall the behavior is well conveyed.

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 compact and front-loaded with the core purpose in the first line. The subsequent sentences add necessary context about the group/member distinction and the page filter without redundancy. Every sentence serves a clear informational purpose.

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

Completeness4/5

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

The description covers what the tool returns, when to use it, and a key semantic trap. An output schema exists, so the return structure does not need to be described. The main gap is the undocumented `include_hidden` parameter, but overall the description is complete enough for an agent to select and invoke the tool correctly.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate for the input schema. It explicitly explains the `page` parameter, and `op_type` is minimally implied by 'operator.' However, `include_hidden` is not described at all, and no details are given about expected values or usage for the main parameter. This is insufficient for a 3-param schema with no schema-level descriptions.

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 clearly states this tool returns the exact parameters of an operator, including names, defaults, menu options, and ranges. It also distinguishes itself from TouchDesigner's group-level documentation by explicitly returning the settable member parameters, making it distinct from sibling tools like td_op_info or td_set_params.

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

Usage Guidelines4/5

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

The description gives explicit guidance: 'Read this before creating or configuring an operator.' This tells an agent when to consult the tool. It does not explicitly state when not to use it or name alternative tools, so it misses the highest bar for exclusionary guidance.

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

td_op_infoA

Inspect one operator in the running project: type, wiring, live parameter values.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.6/5.0

Behavior3/5

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

With no annotations provided, the description must carry the burden of disclosing behavior. 'Inspect' and 'live parameter values' suggest a read-only query of current runtime state, which is useful. However, it does not explicitly state that no side effects occur, whether permissions are needed, or what happens if the path is invalid. The 'live' qualifier adds some context beyond the tool name, but more transparency would be possible.

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 a single, front-loaded sentence with no fluff. Every word earns its place: 'Inspect one operator in the running project' defines scope, and 'type, wiring, live parameter values' enumerates details. This is an exemplary length for a 1-parameter tool.

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

Completeness4/5

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

Given the low complexity (one parameter, output schema present), the description adequately covers the tool's purpose and the main context ('running project'). The output schema handles return-value documentation, so that is not a gap. It would be more complete if it included a hint about path formatting or mentioned that no mutation occurs, but for a simple inspection tool the current state is nearly sufficient.

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

Parameters3/5

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

The input schema only defines 'path' as a required string with no description (0% coverage). The description says 'Inspect one operator in the running project,' which strongly implies that 'path' is the path to that operator, adding meaning beyond the bare schema. Still, it does not explain the expected format, whether it is a relative or absolute path, or provide any examples, leaving some ambiguity.

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 uses a specific verb ('Inspect') with a clear resource ('one operator in the running project') and enumerates what will be observed: 'type, wiring, live parameter values.' This is immediately distinguishable from sibling tools that search for operators or describe schemas, and it is not a tautology.

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

Usage Guidelines2/5

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

The description implies when to use the tool (when you need details about a specific operator) but provides no explicit guidance about alternatives or exclusions. There is no mention of when not to use it or what other tools (e.g., td_operator_schema, td_search_operators) are better suited for different needs.

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

td_paletteA

Search the ready-made components TouchDesigner ships in its palette.

277 finished tools — projection mappers, corner-pinners, colour pickers, audio analysers, UI widgets. Check here before building something from scratch, then install the one you want with td_palette_load.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	No
`category`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description carries the behavioral disclosure burden. It does make the read-only nature of the operation reasonably clear through 'Search' and provides useful context (277 finished tools), but it does not explicitly address side effects, output behavior, or limitations beyond noting what it is not for.

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 compact and front-loaded. It gives the core purpose in the first sentence, adds useful examples and scale in the second, and closes with actionable next-step guidance. No sentence is wasted.

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

Completeness3/5

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

The core workflow is covered, and the output schema supplies return-shape information, but the missing parameter semantics are a real gap for a tool with no annotations and 0% schema coverage. It is a useful description for basic usage, yet not fully complete for correct invocation with filters or categories.

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

Parameters2/5

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

Schema description coverage is 0%, and the description does not explain query, category, or limit. The parameter names are somewhat self-explanatory, but the agent gets no guidance on how queries match, what category values look like, or how limit behaves, and the description does not compensate for the missing schema documentation.

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 states a specific verb and resource: 'Search the ready-made components TouchDesigner ships in its palette.' It distinguishes itself from the sibling td_palette_load by framing one as search and the other as install, and the concrete examples make the resource unmistakable.

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?

The description explicitly says to 'Check here before building something from scratch' and then tells the agent to use td_palette_load to install the chosen component. This gives clear when-to-use guidance and names the relevant follow-up alternative.

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

td_palette_loadA

Install one of TouchDesigner's palette components into the project.

Reach for this the moment td_palette shows a component that does what you were about to build by hand — it is one call, where the alternative is td_exec with a loadTox path you have to get exactly right, on a machine whose TouchDesigner may not be installed where you assume.

name is the component name td_palette reports. The .tox path comes from the index and is checked on disk before anything is sent, so a stale index fails here rather than as a TouchDesigner traceback. Fourteen palette names exist in two folders each (the Ableton set, operatorPath, vrRenderToMovie): those are refused with the candidates listed until you narrow them with category.

The node's final name is reported back rather than assumed: TouchDesigner names a loaded component after its file, and numbers it (checker1, checker2) when a sibling already holds that name. rename is stricter — a name already taken is refused outright and the load is rolled back, so read the path in the reply rather than assuming the name you asked for.

Loading is not free: measured 0.006 s for a 20-operator component and 1.08 s for kantanMapper's 4,079, all of it on TouchDesigner's main thread.

ParametersJSON Schema

Name	Required	Default
`name`	Yes
`owner`	No
`parent`	No	/project1
`rename`	No
`category`	No
`position`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and does it well. It discloses that the .tox path is checked on disk before sending, stale indexes fail here rather than as a traceback, rename is stricter and rolls back on conflicts, final node names are reported rather than assumed, and loading has measured performance costs on TouchDesigner's main thread.

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 longer than average but every sentence earns its place: purpose, usage alternatives, parameter behavior, edge cases, and performance are all covered in a structured, front-loaded way. There is no filler or repetition.

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

Completeness4/5

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

The description covers the tool's purpose, usage, failure modes, naming behavior, and performance, which is strong context for a complex operation. Minor gaps remain around the owner and position parameters, and the description does not explicitly state how the reply is structured, though an output schema exists.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate. It explains the meaning and behavior of 'name', 'category', and 'rename' in useful detail, including ambiguity handling and conflict behavior. However, 'owner', 'parent', and 'position' are not described, leaving some semantics to inference from their defaults.

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 states a specific verb and resource: 'Install one of TouchDesigner's palette components into the project.' It also differentiates the tool from siblings by naming td_palette as the source and td_exec as the alternative, so an agent can immediately understand what this tool is for and what it is not.

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?

The description gives explicit when-to-use guidance: 'Reach for this the moment td_palette shows a component that does what you were about to build by hand.' It also names the alternative (td_exec with a loadTox path) and explains why this tool is preferable, making the selection decision clear.

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

td_project_diffA

Compare two .toe/.tox files and report what actually changed.

Reports added, removed, retyped, rewired and re-parameterised operators, plus a line diff of any changed DAT code. Nodes that were only dragged to a new position are counted separately so they cannot bury a real change.

ParametersJSON Schema

Name	Required	Description	Default
`after`	Yes
`before`	Yes
`show_moves`	No
`include_text`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It goes beyond a vague summary by specifying output categories, the special handling of moved nodes, and the inclusion of DAT code line diffs. It does not explicitly state whether the operation is read-only, but the wording strongly implies an inspection tool, and the additional behavioral details are substantive.

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 three sentences with no fluff: the first states the core purpose, the second lists the types of changes reported, and the third clarifies a key behavioral nuance. Every sentence adds value and it remains highly scannable.

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

Completeness4/5

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

An output schema is present, so explaining the return structure is unnecessary. The description covers the main operations and edge cases (moves, DAT code). It does not elaborate on parameter meanings or potential limitations, but these are partially inferable and the overall behavior is well conveyed. A minor gap remains for a tool with four parameters.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must compensate for missing parameter documentation. It indirectly describes 'before' and 'after' via 'Compare two .toe/.tox files', and the behaviors related to show_moves and include_text are implied ('Nodes that were only dragged... counted separately', 'line diff of any changed DAT code'). However, it never explicitly maps these behaviors to parameter names, leaving room for ambiguity.

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?

Description states a specific verb ('compare') and a concrete resource ('.toe/.tox files') and enumerates what is reported: added, removed, retyped, rewired, re-parameterised operators, and DAT code diffs. This clearly distinguishes it from sibling tools like td_variant_diff, which focus on variants.

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

Usage Guidelines4/5

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

The description provides clear context: use this tool when you need to compare two TouchDesigner project files and see actual changes. It does not explicitly mention alternatives or when-not-to-use, but the domain is narrow enough that an agent can infer appropriate usage. Lacks explicit exclusions but is not misleading.

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

td_project_grepA

Search the Python and GLSL held inside a project's DATs.

Ordinary file search cannot reach this code: it lives inside the .toe container, not on disk. pattern is a regular expression.

ParametersJSON Schema

Name	Required	Description	Default
`file`	Yes
`limit`	No
`pattern`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior3/5

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

No annotations are provided, so the description carries the behavioral burden. It discloses that the searched code lives inside the .toe container and that pattern is a regular expression. It does not mention return format, limit behavior, or side effects, but the output schema partially covers return expectations.

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 compact and front-loaded with the action, followed by a useful one-sentence rationale about the .toe container. Every sentence earns its place with no filler.

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

Completeness3/5

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

The description captures the search scope and the unusual container situation, which is the core context an agent needs. However, the required file parameter is ambiguous and limit's effect is not explained, leaving meaningful gaps for a 3-parameter tool with no annotation support.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. Only pattern is clarified as a regular expression; file and limit are left undefined, forcing the agent to infer their meaning from parameter names and defaults.

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?

States a specific verb and resource: 'Search the Python and GLSL held inside a project's DATs.' It also differentiates from ordinary file search by explaining the .toe container limitation, making the tool's unique purpose clear.

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

Usage Guidelines4/5

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

Explicitly tells the agent that ordinary file search cannot reach this code because it lives inside the .toe container, so this tool is the correct route for searching DAT code. It doesn't name sibling alternatives or list exclusions, but the context is clear.

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

td_project_readA

Read a .toe or .tox from disk, without TouchDesigner running.

Returns the operator tree with wiring. path narrows to a subtree such as '/project1', depth is how many levels of children to show, and params adds the parameter values that differ from the defaults — which is all a saved project records, so it is exactly what someone chose deliberately.

ParametersJSON Schema

Name	Required	Description	Default
`file`	Yes
`path`	No
`depth`	No
`params`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations provided, the description carries the full behavioral disclosure burden. It explains the output ('operator tree with wiring'), the offline/read-only nature implied by 'Read' and 'without TouchDesigner running', and clarifies the subtle behavior of `params` (only values differing from defaults, which is exactly what a saved project records). It doesn't mention error handling or side effects, but the read-only safety profile is adequately conveyed.

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?

Three well-ordered sentences: the first states the core action, the second states the return shape, and the third maps each optional parameter to its meaning. The final clause about saved project records is illustrative, not redundant, and the whole description is compact with every sentence earning its place.

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

Completeness4/5

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

The description gives the tool's purpose, usage context, parameter semantics, and return concept. The output schema covers detailed return structure, so it need not list return fields. Minor gaps remain around path format or error behavior, but for a read-only project inspection tool with a solid output schema, this is nearly complete.

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 description coverage is 0%, so the description must compensate fully—and it does. `file` is implicit as the .toe/.tox path, `path` is described as narrowing to a subtree with an example, `depth` is defined as child levels, and `params` is explained with an important semantic nuance about saved non-default values. This goes well beyond the bare schema and gives an agent enough to set each parameter correctly.

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 states a specific verb ('Read'), a clear resource ('.toe or .tox from disk'), and a concrete result ('operator tree with wiring'). It also differentiates itself from live-session tools by explicitly noting it works 'without TouchDesigner running'. This is sufficient for an agent to distinguish the tool from siblings like td_project_write or td_network.

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

Usage Guidelines4/5

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

The description provides a clear usage context: reading saved project files from disk when TouchDesigner is not running. This implies the tool is for offline inspection, helping an agent decide when to invoke it. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full routing guidance.

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

td_project_textA

Dump a whole .toe/.tox network as JSON, without TouchDesigner running.

Use this when td_project_read's tree is not enough — when the answer needs
every parameter, the wiring, the flags and the DAT code at once, for
instance before rewriting a component or explaining what an unfamiliar
project actually does.

DAT text arrives as an array of lines rather than one escaped string, so a
single changed line stays a single changed line; join the array with '

' to get the file back byte for byte. Standard JSON otherwise.

A network larger than `max_bytes` is refused rather than truncated: a cut
dump is not parseable JSON, and `path` narrows the dump to one component.

ParametersJSON Schema

Name	Required	Description	Default
`file`	Yes
`path`	No
`max_bytes`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.9/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 well. It discloses that TouchDesigner need not be running, that DAT text is represented as an array of lines (not an escaped string), that joining the array with newline reconstructs the file byte-for-byte, and that oversized networks are refused rather than truncated to preserve parseable JSON.

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 front-loaded with the core purpose and then adds only necessary behavioral and usage details. Every sentence earns its place: purpose, when-to-use, DAT line encoding, and max_bytes/path semantics are all essential and efficiently worded.

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?

Given the output schema exists, the description does not need to enumerate return fields. It provides all essential context for successful invocation: what the tool does, when to use it, how DAT text is encoded, how size limits behave, and what path does. No critical operational detail is missing.

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

Parameters4/5

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

The schema has 0% description coverage, so the description must compensate. It explicitly explains max_bytes (refusal rather than truncation) and path (narrowing the dump to one component). The file parameter is not explicitly described, but the tool's opening sentence makes its role clear enough as the .toe/.tox file to dump.

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: 'Dump a whole .toe/.tox network as JSON, without TouchDesigner running.' It further differentiates the tool from td_project_read by explaining that this tool is for cases where the tree is not enough and every parameter, wiring, flags, and DAT code are needed at once.

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?

Explicit usage guidance is provided: 'Use this when td_project_read's tree is not enough' and concrete examples are given such as before rewriting a component or explaining an unfamiliar project. It also explains when not to rely on the default — a network larger than max_bytes is refused and path narrows the dump — giving the agent clear decision criteria.

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

td_project_writeA

Write an edited td_project_text dump back into a new .toe/.tox.

The return leg of td_project_text: edit the JSON, hand the whole document back here, and get a file TouchDesigner opens — with no instance running.

Three things to know before reaching for it, because each one is a silent wrong answer otherwise:

file must still be the original the text came from. The dump covers five of the forty-odd kinds of file a .toe holds; panel layouts, replicator settings and custom parameter definitions live in the others and are copied across from the original. There is no path from text alone to a .toe.
output must not exist. Repacking writes the file whole, and this tool will not overwrite anything of the user's. Write beside it and diff.
Read the gaps in the reply. Anything the text asked for that could not be written — a new operator, a changed operator type, a custom parameter page — is listed rather than approximated, and the built file does not say what the text said.

Changing a parameter, its expression, a DAT's code, a table cell, the wiring, the flags, the placement or the colour all work, as does deleting an operator.

ParametersJSON Schema

Name	Required	Description	Default
`file`	Yes
`text`	Yes
`output`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations present, the description carries full responsibility and meets it well. It discloses that output must not exist, that the tool will not overwrite user files, that the original file is required because not all .toe content is represented in the dump, and that unsupported changes are listed rather than approximated.

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

Conciseness4/5

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

The description is long but well structured, front-loading the core purpose and then using three clear bullet points for critical caveats. A small amount of redundancy exists around the no-overwrite and no-instance points, but every section earns its place for a tool with this much subtlety.

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?

Given the tool's complexity, the description is remarkably complete: it explains preconditions, what can be changed, what will not be written, how failures are reported, and that the built file may differ from the text. An output schema exists, so return-value details do not need to be repeated.

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

Parameters4/5

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

The schema has 0% description coverage, so the description must compensate. It does: file must be the original source, text is the edited JSON dump, and output must not already exist. This adds meaningful constraints beyond the raw string type, though explicit path or format details are not given.

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?

States a precise operation: writing an edited td_project_text dump back into a new .toe/.tox. It is clearly framed as the return leg of td_project_text, which distinguishes it from sibling tools like td_project_read or td_build.

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

Usage Guidelines4/5

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

Provides clear context: use after editing a td_project_text dump, with no running instance, and only when the original file is still available. It does not explicitly name alternatives or say 'use X instead', but the framing as the return leg makes the intended workflow unambiguous.

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

td_python_apiA

Python members and methods available on a class, with inherited ones.

name is an operator type ('noiseTOP') or a class ('TOP', 'OP', 'Par', 'UI'). query filters the member list. Signatures and return types come from the reference shipped with this TouchDesigner build.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`query`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.7/5.0

Behavior3/5

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

No annotations are provided, so the description carries the behavioral disclosure burden. It discloses that inherited members are included and that signatures/return types come from the shipped TouchDesigner reference. However, it does not clarify query matching behavior, invalid-name handling, or whether the result is a flat list or grouped structure.

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 compact and well-structured: a one-line summary of the tool's purpose followed by parameter semantics. Every sentence adds useful information and there is no redundant filler.

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

Completeness4/5

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

For a query/listing tool, the description covers the main purpose, input semantics, and data source. An output schema exists, so return values need not be described in text. Missing details such as query syntax, case sensitivity, or example usage are minor but would round out the context.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate. It does this well for `name` by giving concrete examples ('noiseTOP', 'TOP', 'OP', 'Par', 'UI') and explaining `query` as a filter. The exact syntax or matching rule for `query` is not specified, which prevents a perfect score.

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

Purpose4/5

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

The description clearly identifies the resource: Python members and methods available on a class, including inherited ones. It also specifies the input type (`name` is an operator type or class) and the action of filtering with `query`. It does not explicitly distinguish itself from sibling tools like `td_docs` or `td_operator_schema`, but the focus on Python API members/methods is distinct enough.

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

Usage Guidelines3/5

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

The description implies when to use the tool: when you need the Python API surface of a class or operator type, with optional filtering. It explains the roles of `name` and `query` but does not state explicit when-to-use/when-not-to-use guidance or mention alternatives among the many sibling tools.

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

td_release_scopeA

Give a claimed subtree back before its claim expires.

Call it as soon as a run of edits is finished — otherwise the next agent waits out the whole time-to-live for nothing. Only the owner named on the claim can release it.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`owner`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior3/5

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

With no annotations provided, the description must carry the burden of behavioral disclosure. It reveals an ownership requirement and urgency around timing, which is useful. However, it does not describe failure behavior, idempotency, or side effects of releasing a claim—details an agent might need for a state-mutating operation.

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 three short sentences with no filler: first sentence states the purpose, second provides timing guidance, third sets the ownership restriction. It is front-loaded and every sentence contributes value.

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

Completeness4/5

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

For a simple two-parameter tool with an output schema, the description covers the core lifecycle—releasing a claim, when to release, and who may release. Minor gaps remain around error conditions and behavior for non-owners, but overall the definition is sufficient for correct invocation.

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

Parameters2/5

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

Schema description coverage is 0%, so the description needed to compensate by explaining the `path` and `owner` parameters. It only indirectly hints that `path` is the claimed subtree and `owner` is the claim owner in the ownership sentence, without explicitly defining their meaning, format, or expected values.

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 uses a specific verb phrase 'Give a claimed subtree back' followed by the condition 'before its claim expires,' clearly identifying both the action and the resource. This distinguishes it from sibling tools like td_claim_scope, which handles the claiming side.

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

Usage Guidelines4/5

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

It explicitly states when to call the tool ('as soon as a run of edits is finished') and explains the consequence of delaying (next agent waits out the full TTL). It also provides a clear constraint ('Only the owner named on the claim can release it'). However, it does not name alternative tools or explicitly state when not to use it.

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

td_renderA

Render a TOP and return the image, so you can see what you built.

TouchDesigner is a visual tool: check your work with this rather than inferring it from parameter values. height defaults to preserving the TOP's aspect ratio.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`width`	No
`height`	No

TDQS

A3.8/5.0

Behavior3/5

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

With no annotations, the description carries the full burden. It discloses that the tool returns an image and that 'height defaults to preserving the TOP's aspect ratio', which is useful. However, it does not state whether the operation is read-only or has any side effects, and it does not mention potential errors or limitations.

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 three sentences with no fluff. The main purpose is front-loaded, followed by a rationale and a key parameter detail. Every sentence earns its place.

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

Completeness3/5

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

For a simple 3-parameter tool, the description covers the core purpose, return type, and an important parameter behavior. However, it omits the meaning/format of the required `path`, does not explain `width`, and does not clarify whether rendering is safe/read-only. This leaves meaningful gaps for an agent to call it correctly.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate. It only adds meaning for the `height` parameter (aspect ratio preservation), leaving `path` and `width` essentially unexplained. The required `path` parameter is ambiguous, and `width` depends on schema defaults alone.

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 clearly states a specific verb ('Render'), a specific resource ('a TOP'), and the outcome ('return the image, so you can see what you built'). This distinguishes it from all sibling tools, none of which mention rendering or returning an image.

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

Usage Guidelines4/5

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

The description gives clear context: 'check your work with this rather than inferring it from parameter values', telling the agent when to use this tool instead of analyzing parameters. It does not explicitly name alternatives, but the guidance is actionable and contextually sufficient.

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

td_scopesA

Which subtrees other agents have claimed, and until when.

Check this before editing a project someone else may be in — it is the only way to see a claim before a write bounces off it, and it names the owner to coordinate with.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior3/5

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

With no annotations, the description carries the full burden of explaining behavior. It conveys that the tool is a non-mutating lookup ('check this before editing') and exposes claim ownership and expiry. However, it does not explicitly state that the tool has no side effects, does not edit anything, or describe any caveats such as staleness or permission requirements.

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 compact and front-loaded: the first line defines exactly what the tool reports, and the second line gives actionable guidance. Every sentence earns its place with no filler or redundancy.

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

Completeness4/5

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

For a zero-parameter read-only lookup with an output schema, the description provides enough context: what is returned in substance, when to call it, and why it matters. It does not deeply discuss related scope-management tools or edge cases, but those are not necessary for basic correct invocation.

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

Parameters4/5

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

The tool has zero parameters, and the schema already reflects that with an empty properties object. There is no parameter semantics for the description to add, so the baseline of 4 applies. The description appropriately focuses on output meaning rather than input details.

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

Purpose4/5

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

The description clearly states that the tool reports which subtrees other agents have claimed and until when, which is a specific and identifiable purpose. It implies a read-only listing operation and differentiates itself from sibling claim-management tools by focusing on viewing existing claims, though it does not explicitly name alternatives.

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

Usage Guidelines4/5

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

The description gives a concrete usage context: check this before editing a project someone else may be in. It also explains why it matters—it is the only way to see a claim before a write fails and it identifies the owner to coordinate with. It stops short of stating when not to use the tool or naming alternatives directly.

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

td_search_operatorsA

Find TouchDesigner operators by what they do.

Searches names, labels, summaries and full documentation. Use this first, in plain language ("blur an image", "read a MIDI device", "instance geometry"). family optionally narrows to TOP, CHOP, SOP, DAT, MAT, COMP or POP.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes
`family`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations, the description carries the burden and does so reasonably well by disclosing what fields are searched, that plain-language queries are expected, and that family optionally filters results. It does not mention limit behavior or output ordering, but the core search behavior is clearly characterized.

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?

Three sentences with the main purpose front-loaded, followed by concrete examples and the one optional filter. Every sentence contributes useful information with no filler.

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

Completeness4/5

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

For a simple search tool with an output schema, the description covers the key decisions: what to query, when to use it, and how to narrow by family. The only notable omission is `limit` semantics, which is minor given its default.

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

Parameters4/5

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

Since schema description coverage is 0%, the description compensates by explaining query semantics through examples and enumerating valid family values (TOP, CHOP, SOP, DAT, MAT, COMP, POP). The `limit` parameter is not described, but its default and integer type reduce ambiguity.

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: 'Find TouchDesigner operators by what they do.' It further clarifies the search surface ('names, labels, summaries and full documentation'), making it easy to distinguish from sibling tools like td_search_parameters.

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

Usage Guidelines4/5

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

The description gives explicit usage context: 'Use this first' and supplies concrete plain-language query examples. It does not name alternatives or state when not to use this tool, so it stops short of a full 5.

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

td_search_parametersA

Find which operators have a parameter matching a description.

Useful when you know the effect you want but not which operator provides it — "feedback amount", "sample rate", "instancing".

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

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

With no annotations provided, the description carries the burden of behavioral disclosure. 'Find' implies a read-only lookup, and the description explains the matching concept, but it does not explicitly state side-effect-free behavior, matching semantics, or query interpretation beyond examples.

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 compact and front-loaded with the core action. The second sentence adds useful context and concrete examples without any filler.

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

Completeness4/5

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

For a simple two-parameter search tool, the description provides enough context to understand its purpose and invocation. The output schema is present, so return details are not required. The only minor gap is the lack of any mention of limit behavior or result set scope.

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

Parameters3/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. It adds useful query semantics by giving examples like 'feedback amount', 'sample rate', and 'instancing', clarifying that query is a natural-language effect description. However, it does not explain the limit parameter or how results are ordered or constrained.

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: 'Find which operators have a parameter matching a description.' This clearly distinguishes it from sibling tools like td_search_operators, which likely search by operator name, by focusing on parameter descriptions as the search target.

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

Usage Guidelines4/5

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

It gives a clear trigger for when to use the tool: 'when you know the effect you want but not which operator provides it.' This is concrete usage context, though it does not explicitly name alternatives or state when not to use the tool.

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

td_set_flagsA

Turn node flags on or off — bypass a node, hide it, stop it cooking.

The write half of td_flags, and the way to bypass an operator without deleting it. flags is {"bypass": true} and the like.

Every write is read back before this reports success, because the failure it exists to prevent is silence: TouchDesigner accepts pickable on COMPs only and refuses allowCooking = false outside a COMP, and a flag that exists but does nothing on this family would otherwise look like it landed. A refusal names the flag and the family, and nothing is left half-set.

Pass the same owner you claimed the area with, or your own claim refuses this write.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`flags`	Yes
`owner`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It explains read-back verification before reporting success, TouchDesigner-specific flag/family restrictions, the guarantee that nothing is left half-set, and the requirement to pass the same owner. This is much richer than a generic write description.

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 longer than average, but every sentence adds necessary context: the lead states the action, the second sentence positions it against siblings, and the later paragraphs justify the read-back, error behavior, and owner requirement. The structure front-loads the core purpose and groups supporting details 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?

This is a mutation tool with no annotations and an open-ended `flags` object, so the description needs to explain safety, failure modes, and owner semantics. It does all of that, and even provides domain constraints (pickable on COMPs only, allowCooking refusal outside COMPs). The presence of an output schema means return values do not need to be detailed here.

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

Parameters4/5

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

Schema description coverage is 0%, so the description is the primary semantic source. It explains `flags` with a concrete literal example (`{"bypass": true}`) and gives `owner` meaning via the claim-scope requirement. However, `path` is not explicitly described in the prose, leaving the agent to infer it from the parameter name and required status.

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 object: 'Turn node flags on or off', followed by concrete examples (bypass, hide, stop cooking). It also explicitly positions itself as 'the write half of td_flags', clearly distinguishing it from the sibling read/list tool.

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

Usage Guidelines4/5

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

The description clearly frames when to use this tool: to write flags, bypass an operator without deleting it, and as the counterpart to td_flags. It does not spell out explicit 'when not to use' conditions or alternative tools beyond td_flags, but the core usage context is unambiguous.

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

td_set_paramsA

Set parameters on an existing operator, checked against the index first.

Values may be a constant, {"expr": "..."} for an expression, {"bind": "..."} or {"pulse": true}. Pass op_type to have the names validated locally before anything is sent. Pass the same owner you claimed the area with, or your own claim refuses this write.

ParametersJSON Schema

Name	Required	Description	Default
`pars`	Yes
`path`	Yes
`owner`	No
`op_type`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior4/5

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

With no annotations, the description carries the full burden of disclosing behavior. It does this well by explaining index checks, local validation with `op_type`, the owner-claim requirement, and that a write can be refused. It does not describe side effects or permissions beyond owner checks, but the output schema covers return value expectations.

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 compact and front-loaded with the core action. Each subsequent sentence adds distinct behavioral or parameter guidance without repetition or fluff. The line breaks make the value-format and usage notes easy to scan.

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

Completeness3/5

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

The tool has moderate complexity, no annotations, and zero schema descriptions, so the description needs to cover a lot. It handles value formats, owner requirements, and local validation well. But it omits any explanation of what `path` refers to and how parameter names in `pars` map to the operator schema, so an agent may struggle to construct a correct call.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must compensate. It explains value formats for `pars` (constant, expr, bind, pulse) and gives meaning to `op_type` and `owner`. However, the main parameters `path` and the structure of `pars` keys are not explicitly described, leaving a meaningful gap for agents.

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 states a specific verb and resource: 'Set parameters on an existing operator'. It also adds operational context ('checked against the index first'), which clarifies what this tool actually does beyond the name. This is distinct from sibling tools like td_set_flags or td_annotate.

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

Usage Guidelines3/5

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

The description gives useful invocation guidance: pass `op_type` for local validation and pass the correct `owner` to avoid a refused write. However, it does not explain when to choose this tool over an alternative, such as td_set_flags or td_annotate. Usage context is implied rather than explicit.

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

td_snapshotA

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

Take one before a round of edits and another after, then pass both to td_project_diff to see exactly what changed. Snapshots go to ~/.td-atlas/snapshots.

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.

ParametersJSON Schema

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

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description carries the behavioral burden. It clearly discloses the file destination (~/.td-atlas/snapshots) and explains that a component is written rather than the session, avoiding a subtle Save As side effect. It does not cover overwrite or naming behavior, but the key side effects are stated.

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?

Three short paragraphs, each with a distinct job: purpose, usage pattern, and rationale. The most important information is front-loaded, and there is no filler.

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

Completeness3/5

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

The workflow and file location are covered, and the existing output schema means return values need not be described. However, with no annotations and no parameter explanation, the exact role of path and label remains a meaningful gap for confident invocation.

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

Parameters2/5

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

Schema description coverage is 0%, and the description never explains what 'path' or 'label' mean or how they affect the snapshot. The defaults give hints, but the description adds no direct parameter guidance.

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 names a precise verb and resource: 'Save a component to a file'. It also states the intended purpose ('so it can be diffed later') and explicitly connects to td_project_diff, distinguishing it from sibling tools.

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?

It gives an explicit workflow: take a snapshot before edits, another after, then pass both to td_project_diff. It also explains why saving the whole session is inappropriate, providing a clear boundary for when to use this tool.

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

td_statusB

Whether TouchDesigner is reachable, and what project it has open.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

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

With no annotations, the description must disclose side effects or behaviors, but it only states the basic check. It does not mention whether this is a read-only operation, potential errors, or any impact on the TouchDesigner 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 a single concise sentence, front-loaded with the core purpose. No extraneous information is included.

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

Completeness3/5

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

The description covers the essential purpose but omits details about the output format or any error conditions. Given the simplicity of a status check, it is adequate but not exhaustive.

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

Parameters3/5

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

The tool has zero parameters, so the schema coverage is complete and there is nothing to explain. The baseline score of 3 applies.

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

Purpose4/5

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

The description clearly states the tool's function: checking TouchDesigner reachability and retrieving the open project. It is specific enough to distinguish from siblings like td_python_api or td_exec, though it lacks an explicit verb like 'check' or 'return'.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives such as td_health or td_project_read. The context is implied but not stated, leaving the agent without clear usage direction.

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

td_undoA

Undo (or redo) the last change, including whole td_build batches.

ParametersJSON Schema

Name	Required	Description	Default
`redo`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.6/5.0

Behavior3/5

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

No annotations are provided, so the description carries the burden. It discloses that the tool mutates state by undoing or redoing the last change and that it can affect entire td_build batches, but it doesn't mention persistence, irreversibility, success/failure behavior, or side effects.

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?

One compact sentence with the action and scope front-loaded. There is no redundant or filler wording.

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

Completeness4/5

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

The tool is simple, with one optional boolean parameter and an output schema, so the description covers the core invocation shape. The main missing piece is behavioral context around when an undo is possible and what exactly is affected, but low complexity keeps this from being a major gap.

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

Parameters3/5

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

The schema has a single boolean 'redo' with 0% description coverage. The phrase 'Undo (or redo)' hints at the parameter's purpose, but it doesn't explicitly state that true means redo while false/default means undo.

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

Purpose4/5

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

The description uses a specific action, 'Undo (or redo)', and a clear target, 'the last change', with an added scope note about whole td_build batches. This is distinct from siblings like td_variant_restore, though it doesn't explicitly name an alternative.

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

Usage Guidelines3/5

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

The intended use is implied: call it when the last change should be reverted or redone. There is no explicit guidance about when not to use it, prerequisites, or when to prefer a sibling tool like td_variant_restore.

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

td_variant_diffA

Compare two saved variants of the same project.

The same semantic comparison td_project_diff runs, aimed at two saved states instead of two files: added, removed, retyped, rewired and re-parameterised operators, plus a line diff of changed DAT code. Nodes that only moved are counted separately so they cannot bury a real change.

ParametersJSON Schema

Name	Required	Description	Default
`file`	Yes
`after`	Yes
`before`	Yes
`show_moves`	No
`include_text`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It details the exact categories of comparison (added, removed, retyped, rewired, re-parameterised operators, plus DAT line diff) and notes that moved nodes are counted separately so they cannot hide a real change. A small gap is that it does not explicitly state the operation is read-only, though 'compare' strongly implies it.

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?

Three sentences with no filler. The main purpose is front-loaded, the next sentence adds useful comparison detail, and the final sentence clarifies an important behavioral nuance about move handling. Every sentence earns its place.

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

Completeness3/5

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

The output schema exists, so return structure is covered. The description does a good job conveying comparison semantics, but the absence of parameter guidance is significant given zero schema descriptions and no annotations. The optional booleans in particular remain underspecified for an agent attempting a correct invocation.

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

Parameters2/5

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

Schema description coverage is 0%, and the description does not explain individual parameters. file, before, after, show_moves, and include_text are left to their names and defaults. The move-counting behavior hints at show_moves, and the DAT line diff hints at include_text, but this is indirect and does not compensate for a 5-parameter tool with zero schema documentation.

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 states a specific verb and resource: 'Compare two saved variants of the same project.' It also differentiates itself from the sibling td_project_diff by specifying that this tool targets two saved states rather than two files, so an agent can tell them apart without opening schemas.

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?

The description explicitly names td_project_diff as the analogous file-based comparison and clarifies that td_variant_diff is aimed at two saved states instead. This gives clear context for choosing between the two tools and implies the when-not condition (use td_project_diff for files).

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

td_variant_listA

List saved variants — of one .toe/.tox, or of every project that has any.

Each line carries when it was saved, how large it is, and whether the original file has changed since. That last one is information rather than a warning: a restore reads the variant's own copy, so a changed original cannot affect it.

ParametersJSON Schema

Name	Required	Description	Default
`file`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and does so well: it explains the output line fields (save time, size, changed-file indicator) and clarifies the changed-original flag is informational, not a warning, because restore reads the variant's own copy. This prevents a likely misinterpretation.

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?

Two short paragraphs with no filler. The core action and scope come first, and the second paragraph adds essential output and nuance. Every sentence earns its place.

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 one-optional-parameter list tool with an output schema present, the description is complete: it explains the parameter's optionality, lists the output attributes, and disambiguates a subtle behavioral point. Nothing critical is missing for an agent to invoke it correctly.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate. It does by indicating that a single .toe/.tox can be targeted, while omitting the parameter means listing across every project that has variants. It does not explicitly name the 'file' parameter or specify path format, but the semantic is clear.

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 states a specific verb ('List') and resource ('saved variants') and immediately scopes the operation to one .toe/.tox file or every project that has variants. This makes it distinguishable from sibling tools like td_variant_save, td_variant_restore, and td_variant_diff by naming the list operation.

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

Usage Guidelines3/5

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

The use case is implied: call it when you want to inspect saved variants, and the file parameter is described by the one-project vs all-projects scope. However, it does not explicitly state when not to use it or point to restore/diff/save as alternatives for other variant operations.

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

td_variant_restoreA

Write a saved variant back out as a .toe/.tox file.

A byte copy of what was saved, not a repack: nothing is collapsed, so TouchDesigner's toecollapse never runs and never moves a user's file aside to a .bkp1 name. output must not exist — hand back a new path and compare with td_project_diff rather than replacing anything in place. A directory as output keeps the name the file had when it was saved.

ParametersJSON Schema

Name	Required	Description	Default
`file`	Yes
`label`	Yes
`output`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly explains that the write is a byte copy, toecollapse never runs, no .bkp1 file is created, output must not exist, and a directory output keeps the original saved filename. This is unusually transparent.

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 compact yet information-dense. It front-loads the core purpose and then adds only essential behavioral constraints, with no redundant filler. Every sentence earns its place.

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

Completeness3/5

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

The description covers critical behavior and output semantics well, and an output schema exists so return values need not be explained. However, with no annotations and no schema descriptions, the meaning of `file` and `label` is still under-specified, leaving a meaningful gap in what the agent needs to call the tool correctly.

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

Parameters2/5

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

The schema provides no descriptions for any of the three parameters. The description thoroughly clarifies the `output` parameter, but `file` and `label` are left to inference from the tool name and sibling context. For a 0% schema-description coverage, the description should compensate for all parameters but does not.

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 states a specific action: write a saved variant back out as a .toe/.tox file. It also distinguishes this from related operations by emphasizing that it is a byte copy, not a repack, and by referencing comparison with td_project_diff rather than in-place replacement.

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?

The description gives explicit usage context: use this to restore a saved variant to a file, do not overwrite an existing output, and use td_project_diff for comparison instead of replacing files. This gives the agent clear when-to-use and when-not-to-use guidance.

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

td_variant_saveA

Keep the current state of a .toe/.tox so it can be returned to and compared.

Take one before trying a direction, another after, and td_variant_diff says exactly what the direction changed. Nothing of the user's is touched: the variant is the network text plus a byte copy of the file, kept under ~/.td-atlas/variants and grouped by the project's path.

That copy is what makes a restore possible at all: the rebuild is a patcher, so the text alone cannot produce a .toe. It is also cheap — measured across the shipped palette, the copy adds a median 19% on top of the text and no measurable time.

label may hold letters, digits, dot, dash and underscore. A label already in use is refused rather than overwritten. path narrows only the stored text to a subtree; the copy is always the whole file.

ParametersJSON Schema

Name	Required	Description	Default
`file`	Yes
`note`	No
`path`	No
`label`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden and does so impressively. It discloses storage location (~/.td-atlas/variants), grouping by project path, the byte-copy component, duplicate-label refusal, and the path parameter's scoping semantics. It even includes performance characteristics (median 19% overhead) and reassures that 'Nothing of the user's is touched.' This goes well beyond basic mutation disclosure.

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 moderately long but every sentence earns its place: front-loaded purpose, usage example, storage/behavior details, and parameter constraints. The structure flows logically from what to why to parameter-specific caveats. There is no filler or repetition that bloats the description.

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?

The description is complete for the tool's complexity. It covers what, when, how it behaves, where it stores, parameter meanings, and important constraints—all without needing to explain return values because an output schema exists. An agent can call this tool correctly with the given information.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate. It does add meaningful semantics for 'label' (allowed characters, duplicate refusal) and 'path' (narrows only the stored text; copy is always whole file). However, it does not explicitly explain 'file' or 'note'. File is implicitly a .toe/.tox path from context, and note is optional, but leaving note entirely unexplained is a minor gap given zero schema descriptions.

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: 'Keep the current state of a .toe/.tox so it can be returned to and compared.' This clearly distinguishes it from sibling tools like td_variant_diff and td_variant_restore, which are referenced within the description. It tells the agent exactly what the tool does and why it exists.

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

Usage Guidelines4/5

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

The description provides concrete usage guidance: 'Take one before trying a direction, another after, and td_variant_diff says exactly what the direction changed.' It also states the intent of restore and compare, and names the specific sibling for diffing. It does not explicitly say when not to use it or contrast it with every alternative (e.g., td_snapshot), but the context is clear enough for an agent to select it appropriately.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

41 tool updatesv0.1.0Sep 7, 2026
- First observedtd_annotate
- First observedtd_annotations
- First observedtd_build
- First observedtd_claim_scope
- First observedtd_docs
- First observedtd_doctor
- First observedtd_errors
- First observedtd_example
- First observedtd_exec
- First observedtd_expression_help
- First observedtd_extension_add
- First observedtd_flags
- First observedtd_glossary
- First observedtd_health
- First observedtd_instances
- First observedtd_log
- First observedtd_network
- First observedtd_op_info
- First observedtd_operator_schema
- First observedtd_palette
- First observedtd_palette_load
- First observedtd_project_diff
- First observedtd_project_grep
- First observedtd_project_read
- First observedtd_project_text
- First observedtd_project_write
- First observedtd_python_api
- First observedtd_release_scope
- First observedtd_render
- First observedtd_scopes
- First observedtd_search_operators
- First observedtd_search_parameters
- First observedtd_set_flags
- First observedtd_set_params
- First observedtd_snapshot
- First observedtd_status
- First observedtd_undo
- First observedtd_variant_diff
- First observedtd_variant_list
- First observedtd_variant_restore
- First observedtd_variant_save

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0

Disambiguation4/5

Each tool has a specific target, and the detailed descriptions clearly separate live vs offline, read vs write, and whole-file vs component operations. A few pairs (td_snapshot/td_variant_save, td_project_diff/td_variant_diff, td_errors/td_health) could be confused, but their descriptions draw clear boundaries.

Naming Consistency3/5

All tools share the td_ prefix and snake_case, but the verb/noun order is inconsistent: td_variant_list vs td_search_operators vs td_palette_load vs td_set_params. The names are readable and loosely grouped, but they do not follow one predictable pattern.

Tool Count2/5

41 tools is a very large surface for an agent to navigate, even for a broad TouchDesigner integration. The many reference, search, and diagnostic tools overlap in purpose and inflate the count, making the set feel heavier than necessary.

Completeness4/5

The server covers the core domain well: project read/write/diff, live operator inspection and editing, atomic batches with undo, variants, claims, palette loading, and diagnostics. Minor gaps like variant deletion/renaming and standalone open/close project operations are workable rather than blocking.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

mcp-serverOAuth
com.make
Give your AI agents the tools to build, manage, and run automation workflows.
App Automation Developer Tools Workplace & Productivity
2
Anagent A
io.github.jaytahir
A registry of AI agent tools — MCP servers, APIs, CLIs, SDKs — kept current by automated ingestion.
Agent Orchestration Developer Tools
21
Frenchie A
io.github.Lab94
OCR, transcription, file extraction, and image generation for AI agents via MCP.
AI & Machine Learning Image & Video Processing Speech Processing
72
studioOAuth
io.kaitoi
Build and run visual creative-production workflows from your AI agent.
AI & Machine Learning Design Tools App Automation
2

Related MCP Servers

TouchDesigner MCP
Developer Tools App Automation
8beeeaaat
A
license
B
quality
A
maintenance
A Model Context Protocol server that enables AI agents to control and operate TouchDesigner projects through creation, modification, and querying of nodes and project structures.
Updated a month ago (2026-08-08 04:11 UTC)
14
664
514
MIT
TDPilot
Multimedia Processing Image & Video Processing
dreamrec
A
license
B
quality
B
maintenance
An MCP server for TouchDesigner that lets AI agents inspect, build, wire, optimize, and stabilize live TD networks with 106 tools, plus a technique memory system for reusable patterns.
Updated 2 months ago (2026-07-23 16:01 UTC)
100
11
MIT
TouchDesigner MCP Server
Design Tools Multimedia Processing
superdwayne
A
license
Not graded
quality
C
maintenance
Enables natural language control of TouchDesigner via AI, allowing operator creation, parameter setting, Python execution, and node graph building.
Updated 5 months ago (2026-03-28 10:02 UTC)
7
MIT
touchdesigner-agent-mcp
Multimedia Processing Design Tools
axysar
A
license
A
quality
B
maintenance
Enables LLMs to directly control, introspect, and build TouchDesigner networks in real-time through a Model Context Protocol server.
Updated a month ago (2026-08-08 19:47 UTC)
25
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/grigabyte/td-atlas'

If you have feedback or need assistance with the MCP directory API, please join our Discord server