td-atlas
Server Quality Checklist
Latest release: v0.1.0
- Disambiguation4/5
Each tool has a specific target, and the detailed descriptions clearly separate live vs offline, read vs write, and whole-file vs component operations. A few pairs (td_snapshot/td_variant_save, td_project_diff/td_variant_diff, td_errors/td_health) could be confused, but their descriptions draw clear boundaries.
Naming Consistency3/5All tools share the td_ prefix and snake_case, but the verb/noun order is inconsistent: td_variant_list vs td_search_operators vs td_palette_load vs td_set_params. The names are readable and loosely grouped, but they do not follow one predictable pattern.
Tool Count2/541 tools is a very large surface for an agent to navigate, even for a broad TouchDesigner integration. The many reference, search, and diagnostic tools overlap in purpose and inflate the count, making the set feel heavier than necessary.
Completeness4/5The server covers the core domain well: project read/write/diff, live operator inspection and editing, atomic batches with undo, variants, claims, palette loading, and diagnostics. Minor gaps like variant deletion/renaming and standalone open/close project operations are workable rather than blocking.
Average 4.2/5 across 41 of 41 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 121 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only states the lookup purpose. It does not explain matching behavior, result format, syntax expectations, or any other operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, scannable sentence with no filler words, and the core action is front-loaded. It is concise at the cost of missing useful context, but it is not verbose or poorly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of an output schema reduces the need to describe return values, but the description still leaves usage context and parameter semantics unresolved. Given the large number of documentation-related sibling tools, this one-liner is not enough for an agent to confidently select and invoke the right tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description does not clarify what 'query' should contain (e.g., operator names, exact expressions, partial syntax) or how 'limit' affects results. The parameter names are self-explanatory at a basic level, but the description adds no semantic value beyond them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Look up') and names a distinct resource ('TouchDesigner expression and command syntax'), so an agent can clearly see what the tool targets. It does not explicitly contrast with documentation/glossary siblings like td_docs or td_glossary, so sibling differentiation is lacking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose side effects or behaviors, but it only states the basic check. It does not mention whether this is a read-only operation, potential errors, or any impact on the TouchDesigner session.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the core purpose. No extraneous information is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential purpose but omits details about the output format or any error conditions. Given the simplicity of a status check, it is adequate but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is complete and there is nothing to explain. The baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: checking TouchDesigner reachability and retrieving the open project. It is specific enough to distinguish from siblings like td_python_api or td_exec, though it lacks an explicit verb like 'check' or 'return'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as td_health or td_project_read. The context is implied but not stated, leaving the agent without clear usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool reads 'offline' and describes a .tox example, implying a read-only, non-destructive operation. It doesn't mention what happens if no example exists for the given op_type, whether the output is textual or structured, or any failure modes. However, 'reads one offline' does provide some behavioral signal that this is a safe, local lookup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: a one-line purpose followed by a two-sentence elaboration explaining the source (.tox) and the value proposition (real usage reference vs parameter list). Every sentence earns its place — no fluff, no repeated tool name, and the key distinction is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is an output schema (not shown, but flagged as present), so the return structure may already be documented elsewhere. However, the description omits the depth parameter entirely, no failure-mode information, and no guidance on how to interpret the example. For a tool with only 2 parameters and an output schema, it is mostly usable but leaves a noticeable semantic hole around depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the two parameters (op_type and depth). It explains op_type implicitly as the operator for which the example is shown, but it never mentions the depth parameter at all. An agent cannot know from the description what 'depth' controls (likely traversal depth or recursion into the example network). The description adds minimal value beyond the schema for op_type and none for depth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Show a working example network for an operator.' It explains the resource (a .tox example file for TouchDesigner operators) and what it does with it (reads it offline and describes wiring/config). While it doesn't explicitly contrast with a sibling tool, the verb 'Show' plus the specific focus on example networks distinguishes it from the many other td_* tools listed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. 'List' implies a read-only operation and the description conveys the basic scope, but it does not mention whether depth controls recursion, whether path must point to a component, or any caveats about how the network is represented. The safe behavior is implied but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded and free of fluff. Every word adds meaning, and it is appropriately sized for the tool's simple parameter set.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives a clear mental model but omits practical details such as depth semantics, path scope, and any interaction with sibling project tools. Since an output schema exists, return values do not need explanation, but the description still leaves invocation details under-specified for a 0%-coverage schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It gives partial context: 'inside a component' hints that `path` refers to a component, and 'wired' hints at the purpose of `depth`. However, it does not explain what depth values mean, how path resolution works, or how defaults behave.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and specifies the resource ('operators inside a component') plus the relation ('how they are wired'). This clearly differentiates it from siblings like td_search_operators and td_operator_schema, which are about finding or describing operators rather than showing a network.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the burden of disclosing behavior. 'Inspect' and 'live parameter values' suggest a read-only query of current runtime state, which is useful. However, it does not explicitly state that no side effects occur, whether permissions are needed, or what happens if the path is invalid. The 'live' qualifier adds some context beyond the tool name, but more transparency would be possible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. Every word earns its place: 'Inspect one operator in the running project' defines scope, and 'type, wiring, live parameter values' enumerates details. This is an exemplary length for a 1-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, output schema present), the description adequately covers the tool's purpose and the main context ('running project'). The output schema handles return-value documentation, so that is not a gap. It would be more complete if it included a hint about path formatting or mentioned that no mutation occurs, but for a simple inspection tool the current state is nearly sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only defines 'path' as a required string with no description (0% coverage). The description says 'Inspect one operator in the running project,' which strongly implies that 'path' is the path to that operator, adding meaning beyond the bare schema. Still, it does not explain the expected format, whether it is a relative or absolute path, or provide any examples, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Inspect') with a clear resource ('one operator in the running project') and enumerates what will be observed: 'type, wiring, live parameter values.' This is immediately distinguishable from sibling tools that search for operators or describe schemas, and it is not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool mutates state by undoing or redoing the last change and that it can affect entire td_build batches, but it doesn't mention persistence, irreversibility, success/failure behavior, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence with the action and scope front-loaded. There is no redundant or filler wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, with one optional boolean parameter and an output schema, so the description covers the core invocation shape. The main missing piece is behavioral context around when an undo is possible and what exactly is affected, but low complexity keeps this from being a major gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a single boolean 'redo' with 0% description coverage. The phrase 'Undo (or redo)' hints at the parameter's purpose, but it doesn't explicitly state that true means redo while false/default means undo.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific action, 'Undo (or redo)', and a clear target, 'the last change', with an added scope note about whole td_build batches. This is distinct from siblings like td_variant_restore, though it doesn't explicitly name an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It discloses that inherited members are included and that signatures/return types come from the shipped TouchDesigner reference. However, it does not clarify query matching behavior, invalid-name handling, or whether the result is a flat list or grouped structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-line summary of the tool's purpose followed by parameter semantics. Every sentence adds useful information and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a query/listing tool, the description covers the main purpose, input semantics, and data source. An output schema exists, so return values need not be described in text. Missing details such as query syntax, case sensitivity, or example usage are minor but would round out the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does this well for `name` by giving concrete examples ('noiseTOP', 'TOP', 'OP', 'Par', 'UI') and explaining `query` as a filter. The exact syntax or matching rule for `query` is not specified, which prevents a perfect score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource: Python members and methods available on a class, including inherited ones. It also specifies the input type (`name` is an operator type or class) and the action of filtering with `query`. It does not explicitly distinguish itself from sibling tools like `td_docs` or `td_operator_schema`, but the focus on Python API members/methods is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the safety burden. 'Look up' clearly implies a non-mutating, read-only operation, and the 185-entry count sets scope. However, it does not disclose matching behavior (exact/partial/case-sensitive), what the limit does, or any response details beyond what an output schema might cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the action and resource. The example list of representative glossary entries is not wasted; it concretely communicates the tool's scope and vocabulary domain.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter lookup tool with an output schema, the description supplies enough context: what it does, its scope, and sample terms. It does not explicitly explain parameter semantics, but the clearly named schema parameters and available output schema make the tool usable without major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It partially does by providing example term values ('Cook', 'CHOP', 'Time Slice'), which clarify the 'term' parameter. However, it does not explain the 'limit' parameter's effect or the matching semantics, leaving some burden on the schema names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Look up') and resource ('TouchDesigner terminology' / 'glossary entries'), and the 185 entries with examples make the tool's purpose clear. It does not explicitly name or contrast a sibling tool, but the glossary scope is distinct enough from the doc/operator/expression tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses that the searched code lives inside the .toe container and that pattern is a regular expression. It does not mention return format, limit behavior, or side effects, but the output schema partially covers return expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the action, followed by a useful one-sentence rationale about the .toe container. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description captures the search scope and the unusual container situation, which is the core context an agent needs. However, the required file parameter is ambiguous and limit's effect is not explained, leaving meaningful gaps for a 3-parameter tool with no annotation support.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. Only pattern is clarified as a regular expression; file and limit are left undefined, forcing the agent to infer their meaning from parameter names and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Search the Python and GLSL held inside a project's DATs.' It also differentiates from ordinary file search by explaining the .toe container limitation, making the tool's unique purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool returns an image and that 'height defaults to preserving the TOP's aspect ratio', which is useful. However, it does not state whether the operation is read-only or has any side effects, and it does not mention potential errors or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff. The main purpose is front-loaded, followed by a rationale and a key parameter detail. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter tool, the description covers the core purpose, return type, and an important parameter behavior. However, it omits the meaning/format of the required `path`, does not explain `width`, and does not clarify whether rendering is safe/read-only. This leaves meaningful gaps for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only adds meaning for the `height` parameter (aspect ratio preservation), leaving `path` and `width` essentially unexplained. The required `path` parameter is ambiguous, and `width` depends on schema defaults alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Render'), a specific resource ('a TOP'), and the outcome ('return the image, so you can see what you built'). This distinguishes it from all sibling tools, none of which mention rendering or returning an image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: 'check your work with this rather than inferring it from parameter values', telling the agent when to use this tool instead of analyzing parameters. It does not explicitly name alternatives, but the guidance is actionable and contextually sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the burden of behavioral disclosure. It reveals an ownership requirement and urgency around timing, which is useful. However, it does not describe failure behavior, idempotency, or side effects of releasing a claim—details an agent might need for a state-mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with no filler: first sentence states the purpose, second provides timing guidance, third sets the ownership restriction. It is front-loaded and every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema, the description covers the core lifecycle—releasing a claim, when to release, and who may release. Minor gaps remain around error conditions and behavior for non-owners, but overall the definition is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needed to compensate by explaining the `path` and `owner` parameters. It only indirectly hints that `path` is the claimed subtree and `owner` is the claim owner in the ownership sentence, without explicitly defining their meaning, format, or expected values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb phrase 'Give a claimed subtree back' followed by the condition 'before its claim expires,' clearly identifying both the action and the resource. This distinguishes it from sibling tools like td_claim_scope, which handles the claiming side.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of explaining behavior. It conveys that the tool is a non-mutating lookup ('check this before editing') and exposes claim ownership and expiry. However, it does not explicitly state that the tool has no side effects, does not edit anything, or describe any caveats such as staleness or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first line defines exactly what the tool reports, and the second line gives actionable guidance. Every sentence earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only lookup with an output schema, the description provides enough context: what is returned in substance, when to call it, and why it matters. It does not deeply discuss related scope-management tools or edge cases, but those are not necessary for basic correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema already reflects that with an empty properties object. There is no parameter semantics for the description to add, so the baseline of 4 applies. The description appropriately focuses on output meaning rather than input details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool reports which subtrees other agents have claimed and until when, which is a specific and identifiable purpose. It implies a read-only listing operation and differentiates itself from sibling claim-management tools by focusing on viewing existing claims, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It does this well by explaining index checks, local validation with `op_type`, the owner-claim requirement, and that a write can be refused. It does not describe side effects or permissions beyond owner checks, but the output schema covers return value expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action. Each subsequent sentence adds distinct behavioral or parameter guidance without repetition or fluff. The line breaks make the value-format and usage notes easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity, no annotations, and zero schema descriptions, so the description needs to cover a lot. It handles value formats, owner requirements, and local validation well. But it omits any explanation of what `path` refers to and how parameter names in `pars` map to the operator schema, so an agent may struggle to construct a correct call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains value formats for `pars` (constant, expr, bind, pulse) and gives meaning to `op_type` and `owner`. However, the main parameters `path` and the structure of `pars` keys are not explicitly described, leaving a meaningful gap for agents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Set parameters on an existing operator'. It also adds operational context ('checked against the index first'), which clarifies what this tool actually does beyond the name. This is distinct from sibling tools like td_set_flags or td_annotate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful invocation guidance: pass `op_type` for local validation and pass the correct `owner` to avoid a refused write. However, it does not explain when to choose this tool over an alternative, such as td_set_flags or td_annotate. Usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does well by explaining that notes are returned with the nodes their boxes cover and that membership is geometric based on tile centers. The read-only nature is implied by 'Read,' but it stops short of stating permission needs or any error/edge-case behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then adds usage guidance and a subtle geometric nuance. Each paragraph earns its place: what the tool does, when to use it, and what the returned node list actually means. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The behavioral and output aspects are well covered, and the output schema exists, so return structure is not the issue. However, the two parameters are entirely undocumented: the agent can call with defaults but cannot reason about non-default path or depth values. That is a significant gap for a tool meant to be invoked, not just understood at a high level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description never explains what 'path' or 'depth' mean, nor what effect they have on the results. The defaults /project1 and 8 are present, but the agent has no way to know how to intentionally target another network or adjust depth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and object: 'Read the notes in a network.' It also clarifies scope ('including the ones a person left for you') and establishes differentiation by noting these notes are 'completely invisible to every other tool here,' so an agent can clearly tell this from siblings like td_annotate or project readers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool checks the entire chain, separates distinct failure states ('not running', 'registered but silent', 'answering but refusing the token'), and emits lines that 'name the command that fixes it.' This strongly implies a read-only diagnostic that produces repair guidance. It does not explicitly state permissions or side effects, but the framing is behaviorally informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description opens with a one-line purpose, then the key usage trigger, then the motivating failure mode and state distinctions. It is longer than strictly necessary, but every sentence contributes meaningful diagnostic context rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless diagnostic tool with an output schema, the description provides the when, why, what it checks, what states it separates, and what the output conveys. It is sufficiently complete for an agent to decide when to invoke it and what to expect, though it could be slightly stronger with an explicit statement about whether it makes changes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, and schema description coverage is 100%, so there is nothing for the description to add about inputs. The zero-parameter baseline applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's mission: 'Check the whole chain — install, index, probe pass, bridge, this server.' It is specific about the resource and the diagnostic nature of the tool, and its scope ('whole chain') implies a distinction from per-component siblings like td_status or td_log, though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It does make the read-only nature of the operation reasonably clear through 'Search' and provides useful context (277 finished tools), but it does not explicitly address side effects, output behavior, or limitations beyond noting what it is not for.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. It gives the core purpose in the first sentence, adds useful examples and scale in the second, and closes with actionable next-step guidance. No sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core workflow is covered, and the output schema supplies return-shape information, but the missing parameter semantics are a real gap for a tool with no annotations and 0% schema coverage. It is a useful description for basic usage, yet not fully complete for correct invocation with filters or categories.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain query, category, or limit. The parameter names are somewhat self-explanatory, but the agent gets no guidance on how queries match, what category values look like, or how limit behaves, and the description does not compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Search the ready-made components TouchDesigner ships in its palette.' It distinguishes itself from the sibling td_palette_load by framing one as search and the other as install, and the concrete examples make the resource unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. 'Find' implies a read-only lookup, and the description explains the matching concept, but it does not explicitly state side-effect-free behavior, matching semantics, or query interpretation beyond examples.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action. The second sentence adds useful context and concrete examples without any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter search tool, the description provides enough context to understand its purpose and invocation. The output schema is present, so return details are not required. The only minor gap is the lack of any mention of limit behavior or result set scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds useful query semantics by giving examples like 'feedback amount', 'sample rate', and 'instancing', clarifying that query is a natural-language effect description. However, it does not explain the limit parameter or how results are ordered or constrained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Find which operators have a parameter matching a description.' This clearly distinguishes it from sibling tools like td_search_operators, which likely search by operator name, by focusing on parameter descriptions as the search target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the full burden and does well: it states this is a read operation, explains how to interpret unavailable (absence of flag vs off), and clarifies clone master vs cloneImmune. This gives an agent the exact semantics needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded and each paragraph adds specific value: use case, silent-failure explanation, and output semantics. The 'costs an hour' phrasing is slightly rhetorical but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with an output schema, the description provides enough usage context and return-semantics detail. The main gap is explicit path format guidance, which is minor given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter, path, with no schema description and 0% coverage. The description refers to 'node' and 'operator' but never states that path is the operator path or what format is expected, so the parameter semantics are left largely to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence, 'Read the flags that decide whether a node runs and what is visible,' names a specific verb and resource and immediately tells an agent what td_flags is for. It also implicitly distinguishes the tool from write-oriented siblings like td_set_flags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses useful behavioral nuances: it returns member parameters rather than groups, and it notes that TouchDesigner's own documentation describes groups while this tool returns the actual settable names. It also mentions the page filter. It leaves some ambiguity about hidden parameters, but overall the behavior is well conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose in the first line. The subsequent sentences add necessary context about the group/member distinction and the page filter without redundancy. Every sentence serves a clear informational purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool returns, when to use it, and a key semantic trap. An output schema exists, so the return structure does not need to be described. The main gap is the undocumented `include_hidden` parameter, but overall the description is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the input schema. It explicitly explains the `page` parameter, and `op_type` is minimally implied by 'operator.' However, `include_hidden` is not described at all, and no details are given about expected values or usage for the main parameter. This is insufficient for a 3-param schema with no schema-level descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this tool returns the exact parameters of an operator, including names, defaults, menu options, and ranges. It also distinguishes itself from TouchDesigner's group-level documentation by explicitly returning the settable member parameters, making it distinct from sibling tools like td_op_info or td_set_params.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It communicates that the tool is a non-mutating read/search operation, that the documentation is 'mirrored offline', and that query results are 'matching excerpts' while page reads return full articles. This goes beyond the schema and covers the essential behavioral traits an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. The first sentence states the core purpose, and the following sentences provide necessary mode details and scope. Every sentence adds value without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only documentation tool, the description covers the main functionality, both usage modes, the scope, and gives examples. It omits the `limit` parameter and doesn't explicitly compare with sibling tools, but those are minor gaps, especially since the output schema exists to cover return shapes. Overall it is sufficient for an agent to invoke the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all parameters. It clearly explains `page` and `query` with examples, but does not mention `limit` at all. This leaves the agent to guess that `limit` controls result count. The description compensates well for the two main parameters but not completely for all three.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Search or read TouchDesigner's documentation') and immediately clarifies the two modes: passing `page` reads one article in full while `query` searches all pages and returns excerpts. It also distinguishes itself from operator-specific siblings by noting it 'covers concepts and guides, not just operators.' This is clear and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It goes beyond a vague summary by specifying output categories, the special handling of moved nodes, and the inclusion of DAT code line diffs. It does not explicitly state whether the operation is read-only, but the wording strongly implies an inspection tool, and the additional behavioral details are substantive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff: the first states the core purpose, the second lists the types of changes reported, and the third clarifies a key behavioral nuance. Every sentence adds value and it remains highly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema is present, so explaining the return structure is unnecessary. The description covers the main operations and edge cases (moves, DAT code). It does not elaborate on parameter meanings or potential limitations, but these are partially inferable and the overall behavior is well conveyed. A minor gap remains for a tool with four parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for missing parameter documentation. It indirectly describes 'before' and 'after' via 'Compare two .toe/.tox files', and the behaviors related to show_moves and include_text are implied ('Nodes that were only dragged... counted separately', 'line diff of any changed DAT code'). However, it never explicitly maps these behaviors to parameter names, leaving room for ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb ('compare') and a concrete resource ('.toe/.tox files') and enumerates what is reported: added, removed, retyped, rewired, re-parameterised operators, and DAT code diffs. This clearly distinguishes it from sibling tools like td_variant_diff, which focus on variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool when you need to compare two TouchDesigner project files and see actual changes. It does not explicitly mention alternatives or when-not-to-use, but the domain is narrow enough that an agent can infer appropriate usage. Lacks explicit exclusions but is not misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It clearly discloses the file destination (~/.td-atlas/snapshots) and explains that a component is written rather than the session, avoiding a subtle Save As side effect. It does not cover overwrite or naming behavior, but the key side effects are stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short paragraphs, each with a distinct job: purpose, usage pattern, and rationale. The most important information is front-loaded, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The workflow and file location are covered, and the existing output schema means return values need not be described. However, with no annotations and no parameter explanation, the exact role of path and label remains a meaningful gap for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description never explains what 'path' or 'label' mean or how they affect the snapshot. The defaults give hints, but the description adds no direct parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a precise verb and resource: 'Save a component to a file'. It also states the intended purpose ('so it can be diffed later') and explicitly connects to td_project_diff, distinguishing it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit workflow: take a snapshot before edits, another after, then pass both to td_project_diff. It also explains why saving the whole session is inappropriate, providing a clear boundary for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It details the exact categories of comparison (added, removed, retyped, rewired, re-parameterised operators, plus DAT line diff) and notes that moved nodes are counted separately so they cannot hide a real change. A small gap is that it does not explicitly state the operation is read-only, though 'compare' strongly implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler. The main purpose is front-loaded, the next sentence adds useful comparison detail, and the final sentence clarifies an important behavioral nuance about move handling. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists, so return structure is covered. The description does a good job conveying comparison semantics, but the absence of parameter guidance is significant given zero schema descriptions and no annotations. The optional booleans in particular remain underspecified for an agent attempting a correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain individual parameters. file, before, after, show_moves, and include_text are left to their names and defaults. The move-counting behavior hints at show_moves, and the DAT line diff hints at include_text, but this is indirect and does not compensate for a 5-parameter tool with zero schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Compare two saved variants of the same project.' It also differentiates itself from the sibling td_project_diff by specifying that this tool targets two saved states rather than two files, so an agent can tell them apart without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavior disclosure. It meaningfully discloses that execution blocks the main thread, that the full td namespace is available, and that the return value is a trailing expression or a variable named result. It does not mention that arbitrary Python could mutate the scene, but the blocking warning and execution semantics provide solid transparency beyond the raw schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core purpose, and every sentence adds useful information: the execution environment, return semantics, and the blocking caution. No filler or repetition is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-parameter exec tool, the description captures the essentials: what runs, what is available, what is returned, and what side effect to expect. It is complete enough for an agent to decide when to call it and how to shape the code input, though it could be more explicit about error behavior or the risk of scene mutation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only says the code parameter is a string, so semantic guidance must come from the description. It explains evaluation conventions, such as using a trailing expression or a result variable, and clarifies that the full td namespace is in scope. This materially helps an agent construct valid input despite the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Run Python inside TouchDesigner and return its output." It clearly identifies what the tool does and how it differs from the structured sibling tools by presenting it as a general execution escape hatch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly advises "Reach for the structured tools first," which tells the agent to prefer siblings when possible. It also warns that this tool blocks TouchDesigner's main thread, a clear condition for when to avoid it. It does not name specific sibling tools or enumerate exact alternative conditions, so it stops slightly short of full 5-level guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does so reasonably well by disclosing what fields are searched, that plain-language queries are expected, and that family optionally filters results. It does not mention limit behavior or output ordering, but the core search behavior is clearly characterized.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with the main purpose front-loaded, followed by concrete examples and the one optional filter. Every sentence contributes useful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with an output schema, the description covers the key decisions: what to query, when to use it, and how to narrow by family. The only notable omission is `limit` semantics, which is minor given its default.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 0%, the description compensates by explaining query semantics through examples and enumerating valid family values (TOP, CHOP, SOP, DAT, MAT, COMP, POP). The `limit` parameter is not described, but its default and integer type reduce ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Find TouchDesigner operators by what they do.' It further clarifies the search surface ('names, labels, summaries and full documentation'), making it easy to distinguish from sibling tools like td_search_parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly explains that the write is a byte copy, toecollapse never runs, no .bkp1 file is created, output must not exist, and a directory output keeps the original saved filename. This is unusually transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense. It front-loads the core purpose and then adds only essential behavioral constraints, with no redundant filler. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers critical behavior and output semantics well, and an output schema exists so return values need not be explained. However, with no annotations and no schema descriptions, the meaning of `file` and `label` is still under-specified, leaving a meaningful gap in what the agent needs to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for any of the three parameters. The description thoroughly clarifies the `output` parameter, but `file` and `label` are left to inference from the tool name and sibling context. For a 0% schema-description coverage, the description should compensate for all parameters but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: write a saved variant back out as a .toe/.tox file. It also distinguishes this from related operations by emphasizing that it is a byte copy, not a repack, and by referencing comparison with td_project_diff rather than in-place replacement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It explains the output ('operator tree with wiring'), the offline/read-only nature implied by 'Read' and 'without TouchDesigner running', and clarifies the subtle behavior of `params` (only values differing from defaults, which is exactly what a saved project records). It doesn't mention error handling or side effects, but the read-only safety profile is adequately conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three well-ordered sentences: the first states the core action, the second states the return shape, and the third maps each optional parameter to its meaning. The final clause about saved project records is illustrative, not redundant, and the whole description is compact with every sentence earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives the tool's purpose, usage context, parameter semantics, and return concept. The output schema covers detailed return structure, so it need not list return fields. Minor gaps remain around path format or error behavior, but for a read-only project inspection tool with a solid output schema, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate fully—and it does. `file` is implicit as the .toe/.tox path, `path` is described as narrowing to a subtree with an example, `depth` is defined as child levels, and `params` is explained with an important semantic nuance about saved non-default values. This goes well beyond the bare schema and gives an agent enough to set each parameter correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read'), a clear resource ('.toe or .tox from disk'), and a concrete result ('operator tree with wiring'). It also differentiates itself from live-session tools by explicitly noting it works 'without TouchDesigner running'. This is sufficient for an agent to distinguish the tool from siblings like td_project_write or td_network.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so well: it explains the output line fields (save time, size, changed-file indicator) and clarifies the changed-original flag is informational, not a warning, because restore reads the variant's own copy. This prevents a likely misinterpretation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs with no filler. The core action and scope come first, and the second paragraph adds essential output and nuance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-optional-parameter list tool with an output schema present, the description is complete: it explains the parameter's optionality, lists the output attributes, and disambiguates a subtle behavioral point. Nothing critical is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does by indicating that a single .toe/.tox can be targeted, while omitting the parameter means listing across every project that has variants. It does not explicitly name the 'file' parameter or specify path format, but the semantic is clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('saved variants') and immediately scopes the operation to one .toe/.tox file or every project that has variants. This makes it distinguishable from sibling tools like td_variant_save, td_variant_restore, and td_variant_diff by naming the list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it reveals that TouchDesigner ignores the name at creation, that the reply always returns the actual path, that omitted position avoids covering other items, and that size determines which nodes td_annotations reports as covered. It also explains the behavior of the three mode variants and the rewrite-vs-add distinction between path and parent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The prose is dense and front-loaded, starting with purpose before diving into parameter nuances. Every paragraph contributes non-obvious operational details, and the backtick parameter references keep the structure scannable despite its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with no annotations and an empty schema description, the description covers nearly every behavioral trap (name handling, placement, defaults, rewrite semantics). Small gaps remain around color, font_size, owner, and the empty-string default for mode, but an agent has enough to invoke it correctly in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 0%, the description gives meaningful semantics to most parameters: text, title, position, size, path, parent, name, and mode. It omits color, owner, and font_size, but those are largely self-explanatory from their names; still, the description does not fully compensate for the schema's complete lack of per-parameter docs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Leave a note in the network saying what you built and why') and further defines an Annotate as a colored box with text placed beside nodes. It clearly separates this tool from its read-side sibling by noting that td_annotations will report the nodes a note covers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it delivers: path-scope semantics with examples, automatic TTL expiry, crash-safety implications, the fact that it is an agreement rather than a lock, and the requirement that write calls carry the same owner. This is unusually transparent and actionable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then organized into coherent paragraphs covering usage, path semantics, expiry, and enforcement. Every sentence adds useful information for correct invocation; there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a coordination tool with no annotations and no parameter descriptions in the schema, this description covers why to use it, how claims work, how to refresh them, what happens on expiry, and how ownership is enforced on writes. The output schema exists, so not restating return values is acceptable. Nothing necessary for correct use is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters. It does: 'path' is clarified with subtree boundary examples, 'owner' is explained as any identifying string shown in refusal messages, and 'ttl_seconds' is tied to expiry and renewal. This fully compensates for the bare input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening line states a specific action and resource: 'Announce one subtree of the network as yours while you work in it.' This clearly communicates it is a claiming/ownership tool for a scope subtree, though it does not explicitly name or contrast sibling tools like td_release_scope or td_scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so well: it discloses that the traversal is breadth-first and bounded, that the budget can run out before reaching user operators when starting from `/`, and that node errors are otherwise invisible. This is meaningful behavioral context beyond the raw schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and front-loaded: the purpose appears in the first sentence, followed by why the tool exists and how to choose the path. The longer budget explanation is directly relevant to avoiding a realistic failure mode, so every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single optional parameter and an output schema that can document return values, the description is complete for a diagnostic tool. It covers purpose, when to use it, path-selection pitfalls, and the bounded-walk behavior. No important operational context appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the `path` parameter, and it does thoroughly: the default is the project, `/` is usually the wrong target, the walk is bounded, and users should point at their built component. This adds substantial meaning beyond the schema's bare type/default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns every operator at or under `path` that is reporting an error or warning, and explains why this matters (errors shown as UI colours are otherwise invisible). It does not explicitly distinguish itself from sibling diagnostic tools such as td_status or td_health, so it stops short of a full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and meets it: it reveals the two-sample design, that interval is capped, and that 'this process sleeps through it and answers nothing else meanwhile' — an important blocking trait. It also discloses output behavior like tracebacks being kept apart from the error list and compiler-line quoting for GLSL.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every section earns its place: a scannable bullet list of failure categories, an explicit exclusion, and a note on blocking behavior. Purpose and usage guidance are front-loaded before the detailed taxonomy, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a diagnostic tool with no annotations and no schema descriptions, the description covers when to run it, what it checks, what it does not check, and the blocking interval behavior. The main gap is the undocumented path parameter and the unspecified cap value, though the existing output schema reduces the need to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The interval parameter gets a full semantic explanation as the gap between two samples with a cap and blocking behavior. However, the path parameter is never mentioned or explained; given 0% schema description coverage, the description only partially compensates for the schema's silence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete mission, 'Find what is quietly broken — the failures nothing reports', then lists specific failure classes it detects, from never-cooking branches to GLSL compile failures and callback tracebacks. It also explicitly distinguishes itself from td_errors, making it easy for an agent to pick the right sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit trigger conditions: 'Run this after building anything, and whenever a composition looks fine but does nothing'. It also states when not to expect coverage (e.g., a Script operator's onCook traceback is not caught) and names td_errors as the narrower alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries full responsibility and meets it well. It discloses that output must not exist, that the tool will not overwrite user files, that the original file is required because not all .toe content is represented in the dump, and that unsupported changes are listed rather than approximated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well structured, front-loading the core purpose and then using three clear bullet points for critical caveats. A small amount of redundancy exists around the no-overwrite and no-instance points, but every section earns its place for a tool with this much subtlety.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description is remarkably complete: it explains preconditions, what can be changed, what will not be written, how failures are reported, and that the built file may differ from the text. An output schema exists, so return-value details do not need to be repeated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It does: file must be the original source, text is the edited JSON dump, and output must not already exist. This adds meaningful constraints beyond the raw string type, though explicit path or format details are not given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a precise operation: writing an edited td_project_text dump back into a new .toe/.tox. It is clearly framed as the return leg of td_project_text, which distinguishes it from sibling tools like td_project_read or td_build.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of explaining behavior. It does so thoroughly: atomic rollback, single undo, owner requirement, supported operation methods, value encodings, and validation order are all disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The text is dense but organized: it opens with the core value proposition, then lists operation methods, expands op_create arguments, and closes with validation and owner requirements. Each sentence adds needed detail, though the nested format examples make it slightly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of batch editing with multiple operation types, the description covers the essential context: atomicity, undo behavior, operation syntax, parameter value forms, and ownership. It does not discuss return values, but an output schema appears to exist, so that is an acceptable omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial meaning for the central 'operations' parameter, enumerating methods like op_create and op_delete and detailing nested parameters such as pars, position, connect, and text. It also clarifies 'owner' by explaining it must be the claimed area. The 'undo_name' parameter is not explained, but the most complex parameter is richly documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise statement: 'Apply several edits to the project as one atomic, undoable block.' It clearly identifies the resource (project) and the core action (applying edits in a batch), leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it does this richly: it reveals persistence across TouchDesigner restarts, that only bridge-reaching calls are recorded, that offline tools leave no trace, and what failures=True/summary=True semantically return. There is no annotation contradiction to worry about.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, every sentence earns its place by adding a usage, behavioral, or caveat detail. The front-loaded summary gives an immediate mental model, and the short paragraph breaks keep it scannable despite the density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, four parameters, and an output schema, the description covers the core decision logic, persistence, recording limitations, and parameter behavior for the non-obvious flags. The only minor gaps—limit and method—are low-risk because their names and defaults make them self-explanatory, so nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needed to compensate. It strongly explains failures=True and summary=True, including what they return and what questions they answer. However, limit and method are never tied to their parameters; their semantics are left to inference from names and defaults, making the compensation partial rather than complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific definition: it is a trail of every bridge call this host has made and how it went. It explicitly contrasts with td_status, which shows only the last call, and with offline tools that leave no trace, so an agent can tell exactly what td_log is and is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete triggers: use it when something is wrong and you don't know what you did, when you are about to repeat a failed call, or when you need to spot method-level patterns via summary=True. It also names alternatives and caveats—td_status for last-call view and offline tools that never reach the bridge—so the decision boundary is explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It explains read-back verification before reporting success, TouchDesigner-specific flag/family restrictions, the guarantee that nothing is left half-set, and the requirement to pass the same owner. This is much richer than a generic write description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but every sentence adds necessary context: the lead states the action, the second sentence positions it against siblings, and the later paragraphs justify the read-back, error behavior, and owner requirement. The structure front-loads the core purpose and groups supporting details logically.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations and an open-ended `flags` object, so the description needs to explain safety, failure modes, and owner semantics. It does all of that, and even provides domain constraints (pickable on COMPs only, allowCooking refusal outside COMPs). The presence of an output schema means return values do not need to be detailed here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the primary semantic source. It explains `flags` with a concrete literal example (`{"bypass": true}`) and gives `owner` meaning via the claim-scope requirement. However, `path` is not explicitly described in the prose, leaving the agent to infer it from the parameter name and required status.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and object: 'Turn node flags on or off', followed by concrete examples (bypass, hide, stop cooking). It also explicitly positions itself as 'the write half of td_flags', clearly distinguishing it from the sibling read/list tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so impressively. It discloses storage location (~/.td-atlas/variants), grouping by project path, the byte-copy component, duplicate-label refusal, and the path parameter's scoping semantics. It even includes performance characteristics (median 19% overhead) and reassures that 'Nothing of the user's is touched.' This goes well beyond basic mutation disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but every sentence earns its place: front-loaded purpose, usage example, storage/behavior details, and parameter constraints. The structure flows logically from what to why to parameter-specific caveats. There is no filler or repetition that bloats the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for the tool's complexity. It covers what, when, how it behaves, where it stores, parameter meanings, and important constraints—all without needing to explain return values because an output schema exists. An agent can call this tool correctly with the given information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does add meaningful semantics for 'label' (allowed characters, duplicate refusal) and 'path' (narrows only the stored text; copy is always whole file). However, it does not explicitly explain 'file' or 'note'. File is implicitly a .toe/.tox path from context, and note is optional, but leaving note entirely unexplained is a minor gap given zero schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Keep the current state of a .toe/.tox so it can be returned to and compared.' This clearly distinguishes it from sibling tools like td_variant_diff and td_variant_restore, which are referenced within the description. It tells the agent exactly what the tool does and why it exists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does it well. It discloses that the .tox path is checked on disk before sending, stale indexes fail here rather than as a traceback, rename is stricter and rolls back on conflicts, final node names are reported rather than assumed, and loading has measured performance costs on TouchDesigner's main thread.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every sentence earns its place: purpose, usage alternatives, parameter behavior, edge cases, and performance are all covered in a structured, front-loaded way. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, usage, failure modes, naming behavior, and performance, which is strong context for a complex operation. Minor gaps remain around the owner and position parameters, and the description does not explicitly state how the reply is structured, though an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the meaning and behavior of 'name', 'category', and 'rename' in useful detail, including ambiguity handling and conflict behavior. However, 'owner', 'parent', and 'position' are not described, leaving some semantics to inference from their defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Install one of TouchDesigner's palette components into the project.' It also differentiates the tool from siblings by naming td_palette as the source and td_exec as the alternative, so an agent can immediately understand what this tool is for and what it is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden and meets it: it reveals that other tools may silently pick the wrong instance, that a successful result won't show this, and that this tool cannot retarget. It also notes the missing MCP equivalent of CLI flags, which is a meaningful limitation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core question and purpose, then each subsequent sentence earns its place by explaining when to use it, what it lists, and its limits. Despite its length, there is no filler; every sentence adds actionable context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-oriented listing tool with an output schema present, the description covers scope, return fields, and the actionable user guidance. No critical usage context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This tool has zero parameters, so the baseline is 4; the empty input schema already provides complete property coverage. The description adds no parameter-level details, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens by directly stating the tool's resource ('TouchDesigner instances') and its role ('which one these tools reach'), then explicitly says 'This lists all of them' with concrete fields. It clearly distinguishes this from sibling bridge tools that each target a single instance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well. It discloses that TouchDesigner need not be running, that DAT text is represented as an array of lines (not an escaped string), that joining the array with newline reconstructs the file byte-for-byte, and that oversized networks are refused rather than truncated to preserve parseable JSON.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then adds only necessary behavioral and usage details. Every sentence earns its place: purpose, when-to-use, DAT line encoding, and max_bytes/path semantics are all essential and efficiently worded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description does not need to enumerate return fields. It provides all essential context for successful invocation: what the tool does, when to use it, how DAT text is encoded, how size limits behave, and what path does. No critical operational detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explicitly explains max_bytes (refusal rather than truncation) and path (narrowing the dump to one component). The file parameter is not explicitly described, but the tool's opening sentence makes its role clear enough as the .toe/.tox file to dump.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Dump a whole .toe/.tox network as JSON, without TouchDesigner running.' It further differentiates the tool from td_project_read by explaining that this tool is for cases where the tree is not enough and every parameter, wiring, flags, and DAT code are needed at once.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden, and it does so thoroughly: it reveals the silent-failure failure mode, the read-back verification, local parsing, Python-version mismatch risks, the owner-claim requirement, and the extension-slot behavior. This far exceeds minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but dense and front-loaded: the first sentence states the core purpose, then the manual five-step pain point, targeting rules, naming mechanics, and failure modes follow in logical order. There is no filler; every paragraph earns its place for a 10-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutation tool with no annotations, the description covers when to use it, how to target a COMP or create one, parameter roles, error behavior, prerequisites, and version pitfalls. Nothing an agent needs to make a competent first call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates remarkably: it explains code/class_name, path vs parent/name, extension_name renaming, index slot selection, position coordinate semantics, promote behavior, and owner usage. Every ambiguous parameter receives meaningful context beyond its raw name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Attach a Python class to a COMP as an extension, in one call.' It immediately distinguishes the tool from td_exec by stating when this is the right choice. An agent can tell exactly what capability is being offered.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/grigabyte/td-atlas'
If you have feedback or need assistance with the MCP directory API, please join our Discord server