Create two-way control surface (OSC/MIDI with feedback guard)

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

The description goes far beyond the minimal annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false). It discloses the internal Script CHOP gate mechanism, epsilon delta and rate-limit throttling, the last_in cache, and the custom parameters (Bypass, Globaleps, Ratehz, Reseccache) exposed on the container. This gives the agent a detailed picture of side effects and configurability.

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 but information-dense. It front-loads the core purpose, then explains the guard mechanism and exposed custom parameters. Every sentence earns its place with no padding or redundancy.

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

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

Given the tool's complexity (9 params, no output schema), the description covers the construction purpose, bidirectional behavior, oscillation guard mechanics, and container-level custom parameters. This is sufficient for an agent to understand what the tool creates and how it behaves, especially with the rich schema descriptions for all parameters.

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

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

The input schema already has 100% coverage with descriptive parameter docs, so the baseline is 3. The description adds only a high-level nod to epsilon delta and rate limit, which are already defined in schema, and does not elaborate on individual parameter semantics beyond what schema provides. Thus it does not significantly augment the schema's information.

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

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

The description opens with a specific verb and resource: 'Build a bidirectional OSC or MIDI control surface that drives TouchDesigner params from a controller AND echoes outgoing changes back to it.' It clearly distinguishes from sibling tools like create_control_surface by emphasizing two-way communication and the feedback guard. The title reinforces the same, making the purpose unambiguous.

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

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

The description clearly establishes the use case: bidirectional control with echo, such as motor faders and RGB pads, and explains why the oscillation guard is necessary to prevent ping-pong. However, it does not explicitly name alternatives or state when not to use this tool, though the context strongly implies that unidirectional surfaces would be better handled by other tools.

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