td-atlas

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the behavioral burden and does well: it discloses main-thread blocking, the return convention (trailing expression or `result`), and that printed output is preserved even when the script raises. It does not mention that arbitrary Python may mutate the TD scene or describe timeout/security constraints, which are relevant for an execution tool.

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

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

Three short paragraphs each earn their place: purpose, usage warning, and error behavior. The most important information is front-loaded in the first sentence, and there is no filler or repetition.

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

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

Given a single required parameter and an output schema, the description is nearly complete: it covers namespace, return semantics, error behavior, and a crucial performance warning. Minor gaps remain around side effects of arbitrary code execution and possible time limits, but nothing essential for a first correct call is missing.

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

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

The schema has 0% description coverage for the single `code` parameter, so the description must compensate. It does by explaining the Python execution context, the full `td` namespace in scope, and what value is returned. It stops short of giving a concrete example or clarifying exact formatting expectations, but for a one-parameter tool this is strong compensation.

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

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

The opening sentence states a concrete action and resource: 'Run Python inside TouchDesigner and return its output.' The description also separates this from the surrounding structured helpers via 'Reach for the structured tools first,' though it does not name a specific sibling tool as the alternative.

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

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

The description gives explicit routing advice: prefer the structured tools before falling back to this one, and it warns that this tool blocks TouchDesigner's main thread. It does not name which specific structured tools to prefer or state the positive condition for choosing td_exec beyond the general Python-purpose case.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

No annotations exist, so the description carries the full burden. It discloses substantial behavior: two-sample interval, sleep with cap, stale cook time handling, forced-cook caveats, and specific detection semantics. It does not explicitly state read-only/no side effects, but the diagnostic framing 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.

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

The description is long but well-structured with a clear opening and bulleted list of failure modes. Nearly every sentence adds concrete value; the density is justified by the tool's breadth, though it could be slightly tighter.

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

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 covers most relevant context: what it checks, when to run it, and the interval behavior. The output schema exists, so return details need not be described. The main gap is the undocumented `path` parameter, which prevents full completeness.

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

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 both parameters. It explains `interval` as the gap between two samples in seconds with a cap, but never defines `path`. With two parameters and one entirely undocumented, the description only partially compensates for the schema gap.

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

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

The description states a clear purpose: finding failures that nothing reports, and explicitly contrasts with td_errors. The list of specific failure categories makes the tool's scope concrete and distinguishable from the sibling td_errors.

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

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

Explicit guidance is given: run after building anything and whenever a composition looks fine but does nothing. It also names the alternative td_errors and explains the division of labor, so an agent can choose correctly.

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

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.

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.

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.

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.

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.

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.

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

No annotations are provided, and the description fully covers behavioral traits: it records only calls that reached the bridge, survives TouchDesigner restarts, lists changes with specific values (tx, ty, flags, code lines), and includes failure text and repair. It explicitly discloses the limitation that offline tools leave no trace, so an empty journal means no live work.

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

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

The description is lengthy but front-loaded and dense with unique information, organized into paragraphs for purpose, usage, content, failures, summary, and limitations. Every sentence adds operational value, and the length is justified by the tool's complexity.

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

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

Given the presence of an output schema, the description covers all necessary aspects: what is logged, how to filter, failure/repair info, summary mode, and limitations. An agent can decide when and how to call this tool without needing additional details.

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

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

Schema coverage is 0%, so the description compensates by explaining failures=True yields refusals with text and repairs, summary=True aggregates refusal/slow patterns, method filters to specific call types with examples (par_set, batch, exec), and limit is mentioned in context (a large limit for replaying). However, limit's precise behavior and default are not fully spelled out.

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

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

The description states a specific verb+resource: 'every bridge call this host has made, and how it went.' It explicitly contrasts with td_status, which shows only the last call and overwrites, so an agent can tell them apart.

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

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

It provides explicit when-to-use scenarios: 'when something is wrong and you do not know what you did', 'before repeating a call that failed', and for pattern detection via summary=True. It also names the alternative td_status and explains the gap regarding offline tools that leave no trace.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

With no annotations provided, the description carries the full burden of disclosing behavior. It thoroughly explains what the diff reports (operators, DAT code lines, moves), how parameter changes are presented (constant vs expression/bind text, with no marker), and the semantics of + and - signs relative to defaults. It also explains how to recover a value via td_project_text. This goes well beyond a basic 'compares files' statement and gives the agent a precise mental model of the tool's output.

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

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

The description is efficiently organized: a one-sentence purpose statement, a list of report types, a note on moves, a usage example, and then a detailed explanation of parameter-line semantics. Every sentence adds value, and the most important information (what it does and what it reports) is front-loaded. It is long but not verbose; each paragraph serves a distinct purpose.

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

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

For a diff tool with nuanced output, the description covers the main functionality comprehensively: what is compared, what kinds of changes are reported, how moves are handled, how to interpret parameter changes, and how to revert values. The only missing details are the two boolean parameters, but the core behavior is fully explained. The presence of an output schema (indicated in context signals) likely fills any remaining gaps about return structure.

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

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

Schema coverage is 0%, so the description must explain parameters. It clarifies that 'before' and 'after' should be td_snapshot files, which is helpful. However, it never mentions the 'show_moves' and 'include_text' parameters or their effect on output, even though the description discusses moves and text diffs in other contexts. The partial coverage of the required parameters is useful but leaves two booleans undocumented, so the description does not fully compensate for the schema gap.

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

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

The description opens with a clear verb ('Compare') and resource ('two .toe/.tox files') and immediately states the tool's core function: reporting what actually changed. It lists specific change types (added, removed, retyped, rewired, re-parameterised) and even distinguishes moves from real changes, making its purpose unambiguous and distinct from any sibling tool.

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

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

The description gives a concrete usage scenario: comparing a live branch by passing two td_snapshot files of the same COMP. It explains how to interpret parameter lines and how to restore values. However, it does not explicitly mention when not to use this tool or name alternative tools (e.g., td_variant_diff), so it stops short of full exclusionary guidance.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 delivers rich disclosure: default behaviors (height preserves aspect ratio, width=0 keeps TOP resolution), the side effect of save_to writing a file and switching response mode to text, the refusal of existing files unless overwrite=True, the stale-frame risk when rendering immediately after edits, and even that the tool will state when TouchDesigner stopped drawing. This goes well beyond the schema's bare defaults.

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

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

Three paragraphs, front-loaded with purpose and usage philosophy before diving into parameters. Every sentence adds value — no filler — and the paragraph-per-parameter-group structure makes it scannable. It is on the longer side, but for a 6-parameter tool with zero schema coverage, the density of unique information justifies the length.

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

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

For a tool with 6 params, 0% schema coverage, no annotations, and no output schema, the description is unusually complete. It covers defaults, special values, failure modes (file refusal), timing (settle_frames), and return behavior (image vs. text with save_to) — the last of which compensates for the absent output schema. Nothing an agent needs to invoke it correctly is missing.

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

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 — and it does thoroughly. It explains the special-value semantics of height (0 preserves aspect ratio) and width (0 keeps the TOP's own resolution), the dual behavior of save_to, the overwrite guard, and the frame-waiting semantics of settle_frames. Five of six parameters receive meaningful explanation beyond their schema titles; only path is left implicit, which is acceptable given its self-evidence.

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

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

The description opens with a specific verb+resource: 'Render a TOP and return the image.' It clearly distinguishes the tool from siblings like td_set_params (which edits) and td_build (which constructs) by emphasizing the visual verification outcome — 'see what you built.' No ambiguity about what this tool does.

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

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

Gives explicit when-to-use guidance: 'check your work with this rather than inferring it from parameter values' directly tells the agent to render for visual verification instead of reasoning from parameters. It also provides targeted use cases for save_to (comparing two states pixel by pixel, keeping a frame without context cost) and timing guidance for settle_frames after td_set_params or td_build. It lacks a formal 'when not to use X instead' exclusion naming an alternative tool, but the context is clear and actionable.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

With no annotations, the description takes on the full behavioral burden and does it well: it discloses pre-send validation against the index, accepted value forms, the fallback bridge call when op_type is missing, and write refusal without the correct owner. This goes far beyond a generic mutation warning.

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

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

The description is front-loaded with the core operation and then adds supporting details in dense, purposeful sentences. Every sentence contributes: value grammar, validation behavior, fallback lookup, and ownership requirement. No filler or repetition.

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

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

Given the complexity of value forms, ownership requirements, and validation behavior, the description covers all essential guidance for calling the tool correctly. An output schema exists, so return-value documentation is not needed here.

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

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

Schema description coverage is 0%, but the description compensates thoroughly: it defines pars value shapes (constant, expr, bind, pulse), explains owner as the claimed-area owner, and explains op_type as an optional type hint that triggers a bridge lookup when absent. Even the path parameter is contextualized through 'existing operator' and index reference validation.

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

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

The description clearly states a specific verb ('Set'), a resource ('parameters'), and a target ('an existing operator'), so an agent can tell what the tool does. It does not explicitly name or contrast a sibling alternative like td_set_flags, which keeps it from a 5.

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

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

The description provides clear usage context: it is for setting operator parameters, requires an owner matching the claimed area, and explains when op_type is needed. It does not explicitly say when not to use this tool or mention alternatives, so it stops short of 5.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With no annotations provided, the description carries the full burden and excels: it explains that `abs` is absTime.frame not project frame, that stepping the timeline does not move it, that a paused root timeline stops it, and that `(!)` on the range indicates playback stops short of `end`. These are behavioral nuances an agent would otherwise not know.

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

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

The description is front-loaded with the core status purpose, followed by dense but purposeful caveats. Each sentence adds distinct operational value; it is somewhat long but justified given the interpretive warnings needed.

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

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

For a parameterless status tool with an output schema, the description completes the picture by explaining how to read the timeline line, what `abs` means, and how range warnings behave. Nothing critical is missing for correct invocation and interpretation.

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

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

The tool has zero parameters, so the baseline is 4. The description appropriately avoids inventing param details and instead focuses on output interpretation, which is the only meaningful semantic content for this tool.

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

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

The description clearly states the tool reports three status dimensions: TouchDesigner reachability, the open project, and timeline playing state. It is distinct from action-oriented siblings like td_timeline_run, though it does not explicitly contrast itself with close status siblings like td_timeline_status or td_health.

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

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

It gives actionable guidance on when to consult this tool: before trusting a live CHOP between two calls, and how to interpret playing/paused states. It does not explicitly state when to prefer an alternative tool, but the contextual advice is concrete and useful.

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

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

With no annotations, the description carries the behavioral disclosure burden and does so well: it says the stop is immediate, crop and play mode revert, already-written files persist, and the latest job is used if 'job' is omitted. It leaves failure behavior unstated, but the key side effects are covered.

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

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

Three short sentences with no filler; the main action is front-loaded, and the default behavior and side effects are stated compactly. The slightly awkward phrasing does not reduce clarity.

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

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

For a simple cancel operation with one optional parameter, the description covers the immediate effect, persistence of files, and default target. The output schema can handle return-value details. It never states what happens if no job is running, but overall it is fairly complete.

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

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

Schema coverage is 0%, so the description is the only source of parameter meaning. It explains that 'job' identifies the run and that omitting it targets the latest one, which is helpful. However, it does not specify the expected format of the job identifier or how to discover valid job values.

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

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

The description states a clear verb ('Stop') and resource ('a td_timeline_run job'), making the tool's purpose obvious. It also distinguishes itself from the sibling run/status/profile tools by focusing specifically on cancellation.

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

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

The use case is clearly implied: cancel a td_timeline_run job. However, there is no explicit comparison to alternatives like td_timeline_status or td_timeline_run, nor any guidance on when not 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.

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 timeline is paused and play mode restored, that every operator cooks once more per frame than it would, that side effects may run again, that the tool returns a job id immediately, and that it shares a slot with td_timeline_run. It also explains the meaning of special row markers. This is rich behavioral disclosure beyond the schema.

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

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

The description is long but every sentence earns its place: it front-loads the purpose, then gives exclusions, then parameter semantics, then behavioral caveats. It is dense and well-structured, though slightly verbose in the middle section about row markers.

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

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

Given the tool's complexity, the lack of annotations, and the bare schema, the description is remarkably complete. It covers when to use, what it measures, how it behaves, side effects, return behavior, and related tools. The output schema exists, so return values need not be described in detail. 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.

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 `frames` as the walk (e.g. '3000..3009') and `path` as the scope with `limit` as breadth-first depth. It does not explicitly explain `settle`, but the overall parameter semantics are substantially clarified. A 4 is appropriate because most parameters are given meaningful context despite the schema being bare.

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

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

The description states a specific verb and resource: it profiles what each operator costs per frame on real timeline frames, as a job. It clearly distinguishes itself from siblings like td_exec and td_health by explaining what it is not (not a hand-written cook loop, not last-cook time).

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

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

Explicitly says when to reach for it ('when the frame rate drops and you need to know who spends the frame') and gives explicit exclusions: do not time cook(force=True) in td_exec, do not trust td_health's cookTime alone. It also names sibling tools td_timeline_run and td_timeline_status for related workflow.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses that the call returns immediately with a job id, pauses the timeline, restores play mode at the end, walks frames consecutively, waits settle frames, prevents duplicate steps, resets crops, and preserves Feedback TOP state across tile passes.

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

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

The description is long but dense and well-structured, with short paragraphs, inline code examples, and scoping conditions front-loaded. Given the tool's complexity and complete lack of annotations or schema descriptions, the length is justified and every paragraph adds actionable information.

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

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

The definition covers the full job lifecycle, return behavior, timeline state management, frame-selection semantics, output templating, tile rendering caveats, and the no-output warm-up use case. It also names the sibling status/cancel tools. For a complex asynchronous tool with no annotations, this is unusually complete.

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

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

Since schema description coverage is 0%, the description must explain the parameters, and it does: frames, save, output, tiles, render/path, settle, and from_start are all given concrete syntax or behavior. However, the hold parameter is never explicitly explained, leaving one of the nine parameters ambiguous.

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

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: 'Walk the timeline frame by frame and save a TOP's frames — as a job.' It also differentiates itself from siblings by explicitly naming td_exec and td_render and explaining the job-based async behavior, so an agent can tell exactly what this tool is for.

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

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 instead of a td_exec loop whenever frames depend on what came before them.' It also names the alternatives for polling and cancellation (td_timeline_status, td_timeline_cancel) and explains when to use it as a warm-up step before td_render.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses that finished or unfinished jobs are reported, that a stalled walk is detected after several seconds without a step, and that actionable advice is included. This is strong for a status tool, though it does not mention auth or error behavior for invalid job IDs.

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

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

The description is tight and front-loaded, with the core output dimensions in the first sentence. The two additional short sentences add distinct modes and stalled behavior without repetition or filler.

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

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

For a single-optional-parameter status tool with an output schema present, the description is complete: it covers all invocation modes and key behaviors. The output schema handles return-value detail, so nothing essential is missing.

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

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

The schema provides no description for the job parameter, so the description must compensate. It does explain the meaning of providing a job, omitting it to get the latest one, and that it can refer to either a timeline_run or timeline_profile job. It stops short of specifying the expected string format, but the semantics are clear.

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

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

The description immediately states it reports progress of a td_timeline_run job and names the returned aspects: frame, pass, files saved, errors. It also clarifies the profile-job variant, making the tool's resource and behavior unambiguous and distinguishable from generic status siblings like td_status.

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

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

It gives clear invocation context: use for td_timeline_run jobs, td_timeline_profile jobs, or with no job to fetch the latest one. It does not explicitly name alternatives or when-not-to-use cases, but the usage boundaries are clear enough for an agent to choose this tool appropriately.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.