td-atlas

Overview Schema Source Related Servers Discussions Admin

td_trace

Trace image signal loss in TouchDesigner TOP networks to find the node causing black or dim output. Walks input wires, reports where and why the signal fails.

Instructions

Why is this TOP black, or darker than its parameters say? Find the node.

Reach for it when td_render shows black, a washed-out or a dimmed image and every parameter looks right. Starting at the TOP at path, it walks up every wired input (breadth first, depth hops, at most 40 nodes), reads each image's min / mean / max over R, G, B and the alpha mean, and marks the node where the signal was lost, with the reason when the node's own settings show it:

dropped here — the image goes black while an input still carried something (opacity 0, a bypassed source, an empty input, an error), or an Add / Composite add is fed a negative input and so subtracts it
negative values start here — a float image gone below zero, typically a Level TOP with contrast above 1, inlow above 0 or outlow below 0 and no clamp: invisible on its own tile, it darkens whatever it is added to. A black level above 0 cuts to 0, not below, and is named under dropped here
alpha goes to 0 here — colour still there under an alpha of 0, which vanishes once composited
NaN/Inf start here — usually a shader dividing by zero

A ? on a mark means an input could not be read, and the loss may have come from there. No cook is forced to take a reading, but reading an image that is out of date makes TouchDesigner cook that node once, as any read would (measured on a Noise TOP: each read after a seed change added one cook). On a Feedback TOP that cook is a step of the loop. A node that never cooked is not read and says so instead of reporting zeros, and so does a non-TOP input, a node past the time or download budget, and an image the read failed on. Wires only: an image a Select TOP or a Render TOP reaches through a parameter is not followed — trace from that operator next.

Input Schema

TableJSON Schema

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

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.2.0Sep 24, 2026

TDQS

A4.9/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, and it delivers richly. It discloses that reading an image may cook a node, explains the impact on Feedback TOPs, notes that never-cooked nodes are not read, and clarifies limitations (non-TOP inputs, time/download budgets). It also details the exact marking reasons (dropped here, negative values, alpha, NaN/Inf). This is exemplary transparency.

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, starting with the use case and then breaking down behavior into bullet-like points. Every sentence adds meaningful information about failure modes, side effects, or edge cases. It could be slightly more concise, but the complexity of the tool justifies the length, and the front-loading of 'when to use' makes it effective.

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 and the presence of an output schema (not shown), the description covers all necessary context: input parameters, behavior, side effects, limitations, and output meaning. It explains the marks and reasons, what '?' means, and how to proceed when tracing is incomplete. Nothing an agent needs to call it correctly is missing.

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

Parameters5/5

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

Schema coverage is 0%, so the description must explain the parameters, and it does. It states that 'path' is the starting TOP at the top of the trace, and it clarifies 'depth' as the number of hops (with an implicit cap of 40 nodes). The description also gives constraints on depth and behavior, making the parameters fully understandable without a schema.

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

Purpose5/5

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

The description begins with a specific diagnostic question ('Why is this TOP black...?') and states the tool's action: find the node where the signal was lost. It clearly identifies the resource (TOP) and the process (walk up wired inputs), and the purpose is unmistakably distinct from sibling tools like td_render (which renders) or td_health (which checks health).

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 tells when to use it: when td_render shows black, washed-out, or dimmed images and parameters look correct. It also states what it does not follow (parameter-based connections) and instructs the user to trace from that operator next, effectively naming a fallback. This gives an 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.