Server Quality Checklist

Tool Scores

• td_save_toxB
  3.3/5.0
  Behavior2/5

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

  Annotations indicate destructiveHint=false and readOnlyHint=false, but the description does not elaborate on side effects, authorization needs, or behavior on overwrite. It merely restates the save operation without adding transparency beyond the annotation defaults.

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

  Conciseness5/5

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

  A single sentence that is front-loaded with the action and resource. Every word is necessary; no redundancy or filler.

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

  Completeness3/5

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

  For a simple save operation, the description is adequate but lacks details on overwrite behavior, supported file paths (relative vs absolute), or error conditions. The presence of an output schema (not shown) compensates slightly, but overall context is minimal.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents both parameters. The description adds the context 'COMP operator' but does not provide additional meaning beyond the schema. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the action 'Save a Component (COMP) operator to an external .tox file', specifying the resource type (COMP operator) and output format (.tox file). It effectively distinguishes from sibling tools like td_load_tox and td_save_project.

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

  Usage Guidelines2/5

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

  No guidance is provided on when to use this tool versus alternatives. There are no mentions of prerequisites, exclusions, or when not to use it. The sibling list is extensive but no comparisons are made.

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

• td_load_toxA
  3.5/5.0
  Behavior3/5

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

  Annotations already provide destructiveHint=true and readOnlyHint=false. The description implies loading replaces content but does not specify side effects (e.g., overwrites, errors on missing file). It adds minimal behavioral context beyond the annotation.

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

  Conciseness5/5

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

  The description is a single, concise sentence with no wasted words. It is front-loaded with the core action and target.

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

  Completeness3/5

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

  The tool has an output schema (not shown) but the description does not mention return values. For a destructive tool, more complete context (e.g., success conditions, error behavior) would be helpful.

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

  Parameters3/5

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

  Schema coverage is 100% with clear parameter descriptions. The description adds no extra semantics beyond what the schema provides, so baseline score applies.

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

  Purpose5/5

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

  The description clearly states the verb 'Load', the resource 'external .tox file', and the target 'Component (COMP)'. This distinguishes it from sibling tools like td_save_tox (save) and create_td_node (create from scratch).

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. Given the large sibling list, explicit usage context would be beneficial.

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

• td_selectionA
  3.7/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the tool as safe and idempotent. The description adds value by specifying the return format (count and operators structure), but goes beyond annotations only slightly.

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

  Conciseness5/5

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

  The description is extremely concise, consisting of two short sentences that front-load the action and result. No extraneous information is included, and every word contributes to clarity.

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

  Completeness5/5

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

  Given the tool's simplicity (one optional parameter), the description fully covers its behavior and return value. The presence of an output schema (implied by the return description) means no additional details are needed for completeness.

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

  Parameters3/5

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

  Schema coverage is 100%, as the single optional parameter (response_format) is fully defined in the schema with an enum and description. The tool description does not add extra meaning beyond what the schema provides, so baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the verb 'Return' and the resource 'operators currently selected in the active pane,' making the tool's purpose immediately understandable. It also specifies the return structure, which distinguishes it from sibling tools like 'get_td_nodes' that list all nodes.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives (e.g., 'get_td_nodes') or when not to use it. There is no mention of context or prerequisites, leaving the agent to infer usage without additional cues.

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

• create_td_nodeA
  4/5.0
  Behavior4/5

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

  Annotations indicate non-destructive and non-idempotent. The description adds valuable behavioral context: auto-increments on collision and returns a summary. This goes beyond annotations but could mention more about side effects like overwriting or required permissions.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the main purpose, no wasted words. Very concise and easy to read.

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

  Completeness4/5

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

  Given 5 parameters, 2 required, and an output schema, the description covers the main action and return. It could mention the optional 'parameters' object or response_format, but the schema already does. The auto-increment behavior is a nice touch.

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

  Parameters3/5

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

  Schema has 100% description coverage for all 5 parameters. The description adds minimal extra beyond the schema (e.g., auto-increment already explained). Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the action ('Create') and the resource ('new operator under a parent'), and it distinguishes from siblings like delete_td_node and update_td_node_parameters. The annotation title 'Create Node' reinforces this.

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

  Usage Guidelines3/5

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

  The description implies when to use (to create a node) but does not explicitly state when not to use or compare to alternatives. The note about auto-increment is helpful but not usage guidance.

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

• delete_td_nodeA
  4/5.0
  Behavior4/5

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

  Annotations already mark destructiveHint=true, but the description adds valuable context: the action is not undoable through this tool and returns a specific structure. This goes beyond the annotations.

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

  Conciseness5/5

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

  The description is two sentences plus a code snippet, all front-loaded with the core action. Every sentence adds necessary information without redundancy.

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

  Completeness4/5

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

  For a simple tool with complete annotations and schema, the description covers the essential aspects: action, destructiveness, return format. Minor omission: no mention of error conditions or prerequisites like path existence, but overall adequate.

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

  Parameters3/5

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

  Schema coverage is 100%, so the description does not need to add much. It restates the path parameter as 'Operator path to delete,' which matches the schema. No additional semantic value beyond the schema.

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

  Purpose5/5

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

  The description explicitly states 'Delete an operator by path,' clearly indicating the verb (delete) and resource (operator). This distinguishes it from sibling tools like create_td_node or update_td_node_parameters.

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

  Usage Guidelines3/5

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

  The description warns that the operation is destructive and not undoable, implying careful use, but does not explicitly state when to use this tool versus alternatives or provide scenarios for non-use.

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

• exec_node_methodA
  4/5.0
  Behavior3/5

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

  Annotations already declare destructiveHint=true and readOnlyHint=false, so the description only adds that it returns a serialized result. It does not elaborate on side effects or potential risks beyond what annotations provide.

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

  Conciseness5/5

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

  Two concise sentences with no filler. Front-loaded with the core action and return type, then a clear usage hint.

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

  Completeness4/5

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

  Given that an output schema exists (context signal true), the description need not detail return values. It covers the essential usage context, though it could mention that methods are operator actions specific to TouchDesigner (inferred from siblings).

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

  Parameters3/5

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

  Schema coverage is 100%, so baseline is 3. The description mentions method examples but does not add significant meaning beyond the schema's descriptions for path, method, args, kwargs, and response_format.

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

  Purpose5/5

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

  The description clearly states it calls a method on an operator, with specific examples ('cook', 'pulse', 'reset'). It distinguishes itself from parameter writes, making its purpose unambiguous.

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

  Usage Guidelines4/5

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

  The description explicitly says 'Use for operator actions that are not parameter writes,' providing clear guidance on when to use this tool. However, it does not mention alternative sibling tools like td_cook that might be more specific for certain methods.

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

• get_td_class_detailsA
  4/5.0
  Behavior4/5

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

  Annotations declare it as read-only, idempotent, and non-destructive. The description adds the return structure ({name, type, description, methods, properties}), providing behavioral context beyond the annotations. No contradictions.

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

  Conciseness5/5

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

  The description is extremely concise with two sentences. The first sentence states the action and resource, the second details the return format. No superfluous text.

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

  Completeness4/5

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

  Given the tool's simplicity (2 params, output schema exists for return format), the description adequately covers the purpose and return values. It does not mention error behavior or limitations, but for a read-only tool, this is acceptable.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description does not add additional meaning beyond what the schema already provides for the parameters. It implicitly mentions the class name but does not detail the response_format parameter.

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

  Purpose5/5

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

  The description clearly states it retrieves methods, properties, and docstrings for a TouchDesigner class, with a specific return format. This distinguishes it from siblings like get_td_classes (list all classes) and get_td_module_help (module level help).

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

  Usage Guidelines3/5

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

  While the purpose is clear, the description does not explicitly guide when to use this tool versus alternatives (e.g., when to use get_td_module_help instead). Usage is implied but lacks explicit context or exclusion criteria.

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

• td_save_projectA
  4/5.0
  Behavior3/5

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

  Annotations already indicate mutability (readOnlyHint=false) and non-destructiveness (destructiveHint=false). Description adds minimal context ('checkpoint your work') but no new behavioral details (e.g., overwriting behavior, autocook).

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

  Conciseness5/5

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

  Two sentences with no wasted words. Front-loaded with the key action, immediately useful for an agent.

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

  Completeness4/5

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

  Given the output schema exists (though not provided), the description is adequate for a simple save operation. It covers purpose and basic usage, though it could mention return values or error conditions.

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

  Parameters3/5

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

  Schema covers the parameter with full description (100% coverage). Description repeats schema info, adding no additional meaning. Baseline of 3 applies due to high schema coverage.

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

  Purpose5/5

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

  Description clearly states the action: 'Save the TouchDesigner project (.toe).' It specifies the resource (project file) and file extension, distinguishing it from sibling tools like td_save_tox which save components.

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

  Usage Guidelines4/5

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

  The phrase 'Use this to checkpoint your work' implies periodic saves, but does not explicitly exclude scenarios or mention alternatives like td_save_tox for components. Context is clear but lacks explicit 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.

• update_td_node_parametersA
  4/5.0
  Behavior4/5

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

  Annotations indicate readOnlyHint=false, destructiveHint=false, so mutating but not destructive. The description adds valuable behavioral details: return structure {path, updated, failed: [{name, reason}], message}, and that unknown names go to failed rather than raising an error. This clarifies error handling beyond annotations.

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

  Conciseness5/5

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

  The description is two sentences: first sentence states purpose, second explains return value and behavior. It is front-loaded and contains no superfluous text. Every sentence adds value.

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

  Completeness4/5

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

  Given the presence of an output schema and annotations covering safety, the description is fairly complete. It explains the return structure, failure mode, and hints at prerequisite verification. It effectively sets expectations for the tool's behavior.

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

  Parameters3/5

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

  Schema description coverage is 100%; all parameters have descriptions. The description adds only minimal parameter-related info (failure mode). Baseline is 3, and the description does not significantly enhance parameter understanding beyond the schema.

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

  Purpose5/5

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

  The description clearly states 'Set parameter values on an operator.' The verb 'set' and resource 'parameter values on an operator' are specific. This distinguishes from sibling tools like get_td_node_parameters (read) and other manipulation tools.

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

  Usage Guidelines3/5

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

  The description implies usage by stating 'Verify names first with get_td_node_parameters' but does not explicitly state when to use or not use this tool, nor does it provide alternatives. It offers a hint but lacks comprehensive usage guidance.

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

• describe_td_toolsA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, indicating no side effects. The description adds behavioral context: 'does not contact TouchDesigner', which confirms no network effects, and specifies the return structure. This adds value beyond annotations without contradiction.

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

  Conciseness5/5

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

  The description uses only three sentences, each serving a distinct purpose: stating functionality, providing context, and specifying return format. No redundant or extraneous information. It is appropriately front-loaded with the core action.

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

  Completeness5/5

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

  Given the existence of an output schema (implied by the return structure in the description) and high parameter coverage, the description is complete. It explains what the tool returns and its behavioral characteristics. The tool's simplicity (listing its own tools) means no additional context is necessary.

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

  Parameters3/5

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

  Schema coverage is 100% with individual parameter descriptions (e.g., filter is case-insensitive substring, detail_level and response_format are enums with defaults). The description does not add much beyond the schema; it mentions the return structure but that relates to output, not parameters. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'List the tools this server exposes, with names, descriptions, and schemas.' This distinguishes it from sibling tools like 'get_td_info' or 'get_td_nodes', which operate on different resources. It also provides context as a manifest for code-execution agents, making the purpose explicit and specific.

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

  Usage Guidelines3/5

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

  The description indicates it is safe ('Introspected locally; does not contact TouchDesigner') and implies use for discovering the tool surface. However, it does not explicitly tell the agent when to use this tool versus alternatives like 'get_td_info', nor does it provide when-not-to-use guidance. Usage is implied but not fully clarified.

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

• td_cookA
  4.1/5.0
  Behavior4/5

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

  Annotations indicate mutability (readOnlyHint=false) but non-destructive and idempotent. Description adds context about the stale buffer problem and return value structure, complementing annotations without contradiction.

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

  Conciseness4/5

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

  Concise and well-structured: action, context/usage, and return value in separate sentences. Efficient without redundancy.

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

  Completeness4/5

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

  For a simple 3-param tool with output schema, description adequately covers purpose, usage scenario, and return. No major gaps given the tool's simplicity.

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

  Parameters3/5

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

  Schema covers all parameters (100%), so description adds minimal param context. It implies path is for parent COMP and recurse defaults true, but relies on schema for details.

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

  Purpose5/5

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

  Clearly states the action (force-cook) and resource (operator/COMP). Distinguishes from sibling tools by addressing a specific TD issue with stale buffers.

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

  Usage Guidelines4/5

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

  Explicitly advises when to use (when results look stale) and prioritizes it over other debugging. Provides rationale for the need, but doesn't explicitly state when not to use or mention alternatives.

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

• td_paneA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing the return structure (path, tx, ty, zoom, viewportSize) and the possibility of a null pane. This additional context helps the agent understand what to expect.

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

  Conciseness5/5

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

  The description is extremely concise with two well-structured sentences. The first sentence states the purpose, and the second provides a usage guideline and return format. No wasteful words.

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

  Completeness5/5

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

  Given the tool's simplicity (one optional parameter, no nested objects), the description is complete. It covers the purpose, usage, return format, and the output schema is already present. No additional information is needed.

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

  Parameters3/5

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

  The tool has one optional parameter (response_format) with 100% schema description coverage. The description does not mention the parameter, but the schema already fully documents it. Thus, the description adds no extra meaning beyond the schema.

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

  Purpose4/5

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

  The description clearly states it returns the current network-editor pane with fields like path, pan, zoom, and viewport size. It is specific about the resource and action, but does not explicitly differentiate from sibling tools like td_layout or td_viewport.

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

  Usage Guidelines4/5

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

  The description provides a clear use case: 'Use this to learn where the user is looking before editing there.' This tells the agent when to invoke the tool. No exclusions or alternatives are mentioned, but the context is sufficient given its read-only nature.

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

• get_td_node_errorsA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds context about caching boundaries, which is useful beyond annotations.

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

  Conciseness5/5

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

  Two sentences plus return format line. Front-loaded with the action and resource. Every sentence adds value, no redundant information.

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

  Completeness4/5

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

  With annotations and output schema-like return description, the tool is adequately described. The caching nuance is helpful. Could mention if errors are cleared after retrieval, but overall sufficient.

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

  Parameters3/5

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

  Schema covers both parameters fully (100% coverage). Description adds no additional parameter meaning beyond the schema, so baseline 3 is appropriate.

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

  Purpose5/5

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

  Description clearly states it collects error messages for an operator and its descendants, with explicit return structure. Distinguishes from sibling tools that focus on other operations.

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

  Usage Guidelines4/5

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

  Provides guidance to prefer checking errors in a separate request due to caching behavior, which helps in proper usage. Does not explicitly list alternatives or when not to use.

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

• td_connectA
  4.2/5.0
  Behavior4/5

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

  Description adds behavioral context about compatibility validation and error handling beyond the annotations, which already indicate non-destructive and idempotent nature.

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

  Conciseness5/5

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

  Two concise sentences front-loading the core action and key behavior with no extraneous information.

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

  Completeness4/5

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

  Given full schema and annotations, the description provides enough context about validation and error behavior for correct tool selection and usage.

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

  Parameters3/5

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

  Schema coverage is 100% with parameter descriptions, so the tool description doesn't add extra parameter meaning beyond the schema.

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

  Purpose5/5

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

  The description clearly states the action 'Wire one operator's outlet to another's inlet' with validation, and distinguishes from sibling tools that create/delete/update nodes.

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

  Usage Guidelines4/5

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

  The description explains that only same-family operators can be connected and cross-family attempts return a descriptive error, providing clear context but no explicit alternatives.

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

• td_layoutA
  4.2/5.0
  Behavior4/5

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

  Annotations provide readOnlyHint=false, etc., but description adds concrete return values ({x,y}, {overlaps: bool}) and action-specific behavior. Sufficient for agent to understand side-effects beyond annotations.

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

  Conciseness5/5

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

  Description is extremely concise: two paragraphs with clear bullet points for each action. No redundant information, every sentence adds value.

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

  Completeness4/5

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

  Covers all three actions, required parameters, and return values. With output schema present, description is largely complete. Minor gap: no error handling or limits mentioned.

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

  Parameters4/5

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

  Schema coverage is 100%, description groups parameters by action (e.g., [chain] ops, spacing) adding context beyond schema descriptions. Provides meaningful orientation for parameter use.

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

  Purpose5/5

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

  The description clearly states the tool provides layout intelligence: find empty area, test overlap, or chain operators. Each action is distinctly listed with brief purpose, differentiating from siblings.

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

  Usage Guidelines3/5

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

  The description implies usage by listing required arguments for each action, but does not explicitly state when to use this tool over alternatives or when not to use it. No mention of prerequisites or exclusions.

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

• td_scaffoldA
  4.2/5.0
  Behavior4/5

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

  Describes what the template handles: creation, connector compatibility, naming, layout, first force-cook. Also specifies return structure. Annotations are minimal, so description adds substantial behavioral context.

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

  Conciseness5/5

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

  Two well-structured sentences: first states purpose, second adds usage guidance and return info. No wasted words.

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

  Completeness4/5

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

  Covers purpose, return value, and usage context. With openWorldHint=true and destructiveHint=false, description is sufficient for a scaffold tool. Could mention side effects on existing network, but not critical.

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

  Parameters3/5

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

  Schema coverage is 100% with good parameter descriptions. Description mentions template options but doesn't add meaning beyond schema for parameters like name_prefix or response_format. Baseline 3 appropriate.

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

  Purpose5/5

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

  Description clearly states verb 'Create' and resource 'complete, pre-wired network from a template'. Distinct from siblings like create_td_node which creates individual nodes.

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

  Usage Guidelines4/5

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

  Explicitly says 'Prefer this over hand-wiring common setups', giving when-to-use guidance. Could mention when not to use (e.g., custom wiring not in templates).

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

• get_td_classesA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read operations. The description adds the return format '{classes: [{name, description}]}' and the pairing suggestion, providing useful behavioral context beyond the annotations.

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

  Conciseness5/5

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

  The description is two sentences: one for purpose, one for return format and usage hint. No extraneous information; every word earns its place.

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

  Completeness5/5

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

  The tool is simple with one optional parameter, no required params, and a provided output schema. The description covers the purpose, return format, and workflow pairing. Given the richness of annotations and schema, the description is complete.

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

  Parameters3/5

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

  The input schema has 100% coverage with a clear description for the single 'response_format' parameter. The description does not add parameter details, but the schema already handles it, so baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states 'List the Python classes and modules available in the `td` module' with a specific verb and resource. It distinguishes itself from the sibling 'get_td_class_details' which is for drill-down details.

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

  Usage Guidelines4/5

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

  The description advises to 'Pair with get_td_class_details to drill in,' providing clear context for when to use this tool. While it doesn't explicitly state when not to use it, the guidance is sufficient.

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

• get_td_module_helpA
  4.3/5.0
  Behavior4/5

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

  Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by disclosing that terminal control codes are stripped from the output, which is a behavioral trait not captured by annotations.

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

  Conciseness5/5

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

  The description is two sentences with no wasted words. It front-loads the purpose and immediately explains the return format, making it easy for an AI agent to parse quickly.

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

  Completeness5/5

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

  Given the tool has an output schema (as per context signals), the description need not detail return values further. It already mentions the return shape and the stripping of control codes. Parameter descriptions are sufficient. The description is complete for the tool's simplicity.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline is 3. The description provides concrete examples for module_name (e.g., 'td.noiseCHOP', 'tdu'), adding meaning beyond the schema's field description. response_format is explained in schema and default value is noted.

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

  Purpose5/5

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

  The description clearly states the tool captures Python help() output for a TouchDesigner module or class, specifying the return shape {moduleName, helpText} with control codes stripped. This distinguishes it from siblings like get_td_class_details (detailed attributes) and execute_python_script (generic execution).

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

  Usage Guidelines3/5

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

  The description implies use when help text is needed but provides no explicit guidance on when to use this versus alternatives like get_td_class_details. No when-not-to-use or exclusion criteria are mentioned.

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

• td_list_media_assetsA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety profile is clear. Description adds that it scans a directory and returns paths usable with specific node types, which provides context beyond annotations.

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

  Conciseness5/5

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

  Two sentences, each adding value. First sentence states the action and resources, second clarifies the output format and usage. No wasted words.

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

  Completeness5/5

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

  Simple tool with one optional parameter and clear purpose. Description covers what it does, what it returns, and default behavior. Output schema exists (though not detailed here) but description suffices for correct invocation.

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

  Parameters4/5

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

  Schema coverage is 100% with description for the 'folder' parameter. Description adds valuable context: optional, defaults to current .toe folder, and clarifies the scanning scope. No hidden parameters or ambiguity.

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

  Purpose5/5

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

  Specific verb 'Scan a directory' and resource 'usable TouchDesigner media files' with explicit file types (video, audio, images, geometry). Returns relative paths for use with specific operators (moviefileinTOP, fileinSOP, audiofileinCHOP), distinguishing it from sibling tools that create, delete, or manipulate nodes.

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

  Usage Guidelines3/5

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

  Description implies usage for discovering media files in a directory, but lacks explicit when-to-use or when-not-to-use guidance compared to siblings. No mention of alternative tools for more complex asset management or filtering.

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

• get_td_infoA
  4.4/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds specific return fields and connectivity check behavior, going beyond annotations.

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

  Conciseness5/5

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

  Two concise sentences with no redundant information. Front-loads the action and resources, then provides usage guidance and return structure.

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

  Completeness4/5

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

  Given the simple nature of the tool, the description is complete: it covers purpose, usage, return structure. Could potentially mention error handling or guarantee of idempotency, but annotations already cover safety.

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

  Parameters3/5

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

  Schema coverage is 100% and the parameter has its own description. The tool description does not add any additional details about the parameter, so baseline 3 is appropriate.

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

  Purpose5/5

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

  Clearly states the verb 'Get' and the resources: TouchDesigner build, version, OS, and API version. Distinguishes from sibling get_* tools by providing a high-level overview of the environment.

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

  Usage Guidelines4/5

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

  Explicitly recommends using this tool first to confirm connectivity, providing clear usage guidance. Lacks explicit when-not-to-use but the context implies it as a preliminary check.

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

• td_viewportA
  4.4/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds value by explaining that small captures are returned as viewable images while large captures (or return_as='path') return a temp-file path. No contradictions.

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

  Conciseness5/5

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

  The description is four sentences, front-loaded with purpose, then usage guidance, then parameter details. Every sentence adds value, no filler.

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

  Completeness4/5

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

  For a tool with 6 parameters and no output schema, the description covers output behavior (inline vs file path) and key parameter constraints. It could mention fallback defaults for width/height, but overall it is complete enough for an agent to invoke correctly.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the target parameter as 'TOP/COMP path, or the literal ''pane''' and that JPG quality is ignored for PNG. This helps the agent understand parameter behavior.

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

  Purpose5/5

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

  The description clearly states the tool captures a TOP/COMP viewer or network editor pane as an image. This is a specific verb+resource pair, and the sibling tools (node creation, deletion, parameter updates) are all distinct, so the tool is well-differentiated.

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

  Usage Guidelines4/5

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

  The description gives clear usage context: 'Use this to actually see the result of edits instead of guessing.' It explains the target parameter and return options. However, it does not explicitly state when not to use this tool or suggest alternatives.

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

• get_td_node_parametersA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the behavioral safety profile. The description adds value by stating the return format (id, name, path, opType, properties) and the usage tip about name-label mismatch, which is not in annotations.

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

  Conciseness5/5

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

  The description is extremely concise (three sentences), front-loaded with the purpose, and every sentence adds distinct value: purpose and output, usage guidance, and return fields. No unnecessary words.

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

  Completeness5/5

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

  Given that output schema exists (context indicates true) and annotations are present, the description is complete. It covers the tool's function, when to use it, and what it returns, leaving no ambiguity for the agent.

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

  Parameters3/5

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

  Input schema has 100% coverage with descriptions for both parameters. The description does not add new parameter semantics beyond what the schema provides, so the baseline score of 3 applies.

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

  Purpose5/5

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

  The description clearly states 'Get an operator's parameters and current values,' using a specific verb and resource. It distinguishes itself from the sibling tool 'update_td_node_parameters' by noting that this tool should be called before updating, making its purpose unmistakable.

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

  Usage Guidelines5/5

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

  The description explicitly advises 'Call this before updating parameters — TD names rarely match labels,' providing clear when-to-use guidance and a rationale. This differentiates it from the update tool and helps the agent select the correct tool.

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

• get_td_nodesA
  4.5/5.0
  Behavior5/5

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

  Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds a key behavioral insight: performance trade-off when setting include_properties=true. It also clarifies the return format. No contradictions.

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

  Conciseness5/5

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

  Only two sentences: concise, front-loaded with main purpose, then adds performance advice. Every word earns its place.

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

  Completeness5/5

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

  The description combined with annotations and schema provides a complete picture: purpose, return format, key parameter guidance, safety profile. With output schema available (not shown but indicated), no additional explanation of return values is needed.

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

  Parameters3/5

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

  Schema coverage is 100% with descriptions for all parameters. The description adds minimal extra context beyond the schema (performance note for include_properties). Baseline of 3 is appropriate since the schema already carries the burden.

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

  Purpose5/5

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

  The description clearly states the tool lists child operators under a path, with a specific verb ('List') and resource ('child operators'). It immediately distinguishes from sibling tools like create, delete, or execute.

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

  Usage Guidelines4/5

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

  The description implies usage for browsing operator hierarchy, but does not explicitly state when to use this tool over siblings like get_td_info or get_td_class_details. However, the combination of name and description makes the purpose clear enough.

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

• execute_python_scriptA
  4.8/5.0
  Behavior5/5

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

  The description discloses that the tool runs 'arbitrary, un-sandboxed code' and specifies the return format as '{result, stdout, stderr}'. Annotations already indicate destructiveHint=true and readOnlyHint=false, and the description adds valuable context beyond these annotations without contradiction.

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

  Conciseness5/5

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

  The description is three sentences long, no filler. The first sentence states the purpose, the second adds technical context, and the third provides usage guidance. Well-structured and front-loaded.

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

  Completeness4/5

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

  Given the tool's complexity and destructive nature, the description covers purpose, return format, scope of available APIs, and usage recommendations. It is sufficiently complete, though a brief mention of potential side effects or safety considerations would be beneficial.

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

  Parameters4/5

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

  Schema description coverage is 100%, but the description adds extra semantic value by explaining that a single expression returns its value and multi-line scripts can set 'result'. This goes beyond the schema's parameter descriptions.

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

  Purpose5/5

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

  The description clearly states 'Execute a Python script in TouchDesigner's interpreter and capture output', using a specific verb and resource. It distinguishes itself from sibling tools by advising to use dedicated node tools for routine edits and reserving this tool for logic not covered elsewhere.

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

  Usage Guidelines5/5

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

  The description explicitly provides when-to-use ('logic the other tools do not cover') and when-not-to ('prefer dedicated node tools for routine edits'), along with a caution that it runs arbitrary, un-sandboxed code.

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

• td_glslA
  4.8/5.0
  Behavior4/5

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

  Describes the docked DAT resolution, read/write behavior, and compile error handling via return_compiled. Returns {stage, docked_dat_path, code, errors}. Does not contradict annotations (destructiveHint=false, readOnlyHint=false). Could mention whether write replaces or appends code, but overall very transparent.

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

  Conciseness5/5

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

  Two concise sentences that front-load the core purpose. No wasted words; each phrase earns its place. The structure logically separates read vs. write and error handling.

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

  Completeness5/5

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

  The description covers all essential aspects: operation modes, parameter semantics, output structure, and error handling. No gaps remain; the tool's behavior is fully understandable without external references.

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

  Parameters5/5

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

  All 5 parameters are fully described in the schema (100% coverage). The description adds significant value by explaining the read/write duality of 'code,' the purpose of 'stage,' and the effect of 'return_compiled.' The schema alone would not convey this context.

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

  Purpose5/5

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

  The description clearly states 'Read or write a GLSL shader stage, resolving the correct docked DAT.' It specifies the action (read/write) and resource (GLSL shader stage), and distinguishes from siblings by highlighting the docked DAT resolution mechanism that no other tool mentions.

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

  Usage Guidelines5/5

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

  Explicit guidance: 'Omit code to read; pass code to write' and 'set return_compiled=true to re-cook and surface compile errors.' Also warns against guessing DAT names or setting .text directly. No alternatives needed as this is the only GLSL shader tool.

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