Save / load component (.tox)

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

Beyond annotations (readOnlyHint, destructiveHint), the description discloses critical behavioral details: save uses a deferred, verified same-directory temporary export, refuses overwrite by default, and supports an 'ask' policy for native consent. It also explains the load legacy behavior and notes that paths are on the machine running TouchDesigner. This goes far beyond the basic annotations and provides agent-critical safety and execution context.

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

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

The description is three sentences long and front-loaded with the core purpose. Each sentence adds essential information: the overall function, save-specific safety and overwrite behavior, and load/path notes. No redundant or filler content exists, making it efficient and well-structured.

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

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

Given the 11 parameters, complete schema coverage, and presence of annotations, the description sufficiently covers the tool's complexity. It explains the key behavioral nuances (deferred save, overwrite policy, legacy load, path location) without needing to reiterate parameter details already in the schema. The absence of an output schema is acceptable as the primary return value is implied (the file operation), and the description delivers a complete operational picture.

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

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

The schema already provides 100% description coverage for all parameters, with detailed comments for each. The description itself adds only a small amount of parameter-related context, such as the behavior of overwrite_policy and the relationship between file_path and parent_path. This aligns with the baseline score of 3 for high schema coverage, as the description does not substantially add semantic value beyond the structured data.

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

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

The description clearly states the tool's purpose as moving COMPs to/from .tox files on disk to build a reusable component library, which is a specific verb+resource combination. It also distinguishes between the 'save' and 'load' actions. However, it does not explicitly mention or differentiate from sibling tools like manage_component_storage or make_portable_tox, so it misses the full sibling differentiation criterion.

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

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

The description provides clear context on when to use the tool: for building a component library by moving COMPs to/from .tox files. It also gives detailed behavior for each action (save/load) and mentions the overwrite policy context, which helps the agent decide. It does not explicitly list alternatives or when-not-to-use cases, but the context is unambiguous and free of exclusions.

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