Tool Parameter Operator

The Tool Parameter operator dynamically creates parameter adjustment tools that allow AI models to directly control TouchDesigner operator parameters in real-time. This operator is essential for building interactive AI workflows where the AI can modify operator settings, adjust visual parameters, and control system behavior based on user requests or automated processes.

The operator uses a sequence-based configuration system to define which operators and parameters should be controllable, with flexible filtering options for pages and specific parameters. It provides immediate feedback and logging capabilities for all parameter adjustments.

Agent Tool Integration

🔧 GetTool Enabled 1 tool

This operator exposes 1 tool that allow Agent and Gemini Live LOPs to dynamically adjust TouchDesigner operator parameters in real-time based on AI analysis and user requests.

Use the Tool Debugger operator to inspect exact tool definitions, schemas, and parameters.

The Tool Parameter operator dynamically creates parameter adjustment tools that allow AI models to directly control TouchDesigner operator parameters, enabling intelligent parameter automation and real-time system control.

Key Features

• Dynamic Tool Generation: Automatically creates parameter adjustment tools based on operator configuration
• Real-time Control: Parameter changes are applied immediately to TouchDesigner operators
• Flexible Filtering: Control which parameters and pages are accessible through pattern matching
• Multiple Operator Support: Manage parameters across multiple operators from a single tool
• Intelligent Descriptions: Includes current values, defaults, and help text in tool descriptions
• Error Handling: Provides detailed error messages for invalid parameter values
• Logging System: Optional logging of all parameter adjustments for debugging and analysis

Requirements

• ChatTD Operator: Required for AI workflow integration and logging
• Target Operators: TouchDesigner operators to be controlled must be accessible
• No additional Python packages required

Input/Output

Inputs

• No direct inputs required - operates through the GetTool interface

Outputs

• Parameter Tools: Provides dynamically generated parameter adjustment tools to AI models
• Operations Log: Optional logging of parameter adjustments to operationsTable

Parameters

Page: Settings

Tool Name (Toolname) op('tool_parameter').par.Toolname String

Default:

"" (Empty String)

Enable Operations (Enableoperations) op('tool_parameter').par.Enableoperations Toggle

Default:

Off

Tool Prefix (Toolprefix) op('tool_parameter').par.Toolprefix String

Default:

"" (Empty String)

Include Help Text (Includehelp) op('tool_parameter').par.Includehelp Toggle

Default:

Off

Include Current Values (Includecurrent) op('tool_parameter').par.Includecurrent Toggle

Default:

Off

Include Default Values (Includedefault) op('tool_parameter').par.Includedefault Toggle

Default:

Off

Require Explanation (Requireexplanation) op('tool_parameter').par.Requireexplanation Toggle

Default:

Off

Silent Mode Available (Silentmode) op('tool_parameter').par.Silentmode Toggle

Default:

Off

Enable Logging (Enablelogging) op('tool_parameter').par.Enablelogging Toggle

Default:

Off

Add / Remove Controls (Optool) op('tool_parameter').par.Optool Sequence

Default:

0

Select Target Operator (Optool0ops) op('tool_parameter').par.Optool0ops Operator

Default:

"" (Empty String)

Parameters (Optool0parameters) op('tool_parameter').par.Optool0parameters String Menu

Default:

*

Pages (Optool0pages) op('tool_parameter').par.Optool0pages String Menu

Default:

*

Mode (Optool0mode) op('tool_parameter').par.Optool0mode Menu

Default:

disabled

Options:

disabled, monitor, control, forced

Info [ optional ] (Optool0info) op('tool_parameter').par.Optool0info String

Default:

"" (Empty String)

Usage Examples

Basic Parameter Control

1. Setup Single Operator Control:

   • Add the Tool Parameter operator to your network
   • Enable “Enable Operations”
   • Set “Tool Prefix” to “adjust”
   • Configure the first Optool block:
     • Select target operator in “Select Target Operator”
     • Set mode to “control”
     • Leave parameters and pages as ”*” for full access

2. AI Integration:

   • The operator automatically provides parameter adjustment tools
   • AI models can call adjust_operatorname_parameters functions
   • Changes are applied immediately to the target operator

Multiple Operator Control

# Configure multiple operators
# Block 0: Ramp operator for color control
# Block 1: Transform operator for position control
# Block 2: Blur operator for effect control

# AI can then call:
{
  "operator_name": "ramp1",
  "color1r": 0.8,
  "color1g": 0.2,
  "color1b": 0.1
}

Parameter Filtering

1. Page-Specific Control:

   • Set “Pages” to “Color Transform” to only expose color-related parameters
   • Use “Common” to limit to basic parameters

2. Parameter-Specific Control:

   • Set “Parameters” to “tx ty tz” for position-only control
   • Use “color*” to match all color-related parameters

Advanced Configuration

# Tool configuration example
{
  "operator_name": "blur1",
  "size": 5.0,
  "quality": "high",
  "enable": true
}

This provides:

• Immediate visual feedback in TouchDesigner
• Error handling for invalid values
• Detailed response about what changed

Integration Examples

With Agent Operator

Connect the Tool Parameter operator to an Agent workflow:

1. Agent Setup: Configure an Agent operator with parameter control capabilities
2. Tool Registration: The Tool Parameter operator automatically registers its tools
3. Interactive Control: Users can request parameter adjustments through natural language

With Visual Control Systems

Use for real-time visual parameter control:

1. Visual Effects: Control blur, color, transform parameters
2. Generative Art: Adjust noise, pattern, and animation parameters
3. Interactive Installations: Respond to user input through parameter changes

With Automation Workflows

Integrate with automated systems:

1. Scheduled Adjustments: Automatically adjust parameters based on time or data
2. Responsive Systems: Change parameters based on sensor input or external events
3. A/B Testing: Systematically test different parameter combinations

Best Practices

Parameter Configuration

• Start Simple: Begin with single operator control before adding multiple operators
• Use Filtering: Limit parameter access to prevent overwhelming AI models
• Clear Naming: Use descriptive tool names and prefixes for clarity
• Mode Selection: Use “control” for normal operation, “forced” for critical parameters

Error Prevention

• Parameter Validation: The operator automatically validates parameter types and ranges
• Menu Handling: Supports both string names and numeric indices for menu parameters
• Type Checking: Ensures parameter values match expected types (float, int, string, boolean)

Performance Optimization

• Selective Exposure: Only expose parameters that need AI control
• Batch Operations: Group related parameter changes in single tool calls
• Logging Control: Enable logging only during development and debugging

User Experience

• Explanations: Enable “Require Explanation” for transparency
• Help Text: Include help text to guide AI decision-making
• Current Values: Show current values to prevent unnecessary changes

Troubleshooting

Common Issues

No Tools Generated

• Check that “Enable Operations” is enabled
• Verify target operators are selected and accessible
• Ensure at least one Optool block is set to “control” or “forced” mode

Parameter Not Found

• Verify parameter names match exactly (case-sensitive)
• Check that parameter filters include the desired parameters
• Ensure the parameter exists on the target operator

Invalid Parameter Values

• Check parameter type (number, string, boolean, menu)
• Verify numeric values are within min/max ranges
• For menu parameters, use valid menu names or indices

Tool Not Responding

• Confirm “Enable Operations” is enabled
• Check that target operator is still valid and accessible
• Verify AI model is calling the correct tool name

Error Messages

“Parameter not found on operator”

• The specified parameter doesn’t exist on the target operator
• Check parameter spelling and case sensitivity
• Verify the operator has the expected parameters

“Invalid menu option”

• For menu parameters, use valid menu names or indices
• Check available options in the parameter’s menu
• Use case-insensitive matching for menu names

“Menu index out of range”

• Menu index values must be within 0 to (menu_length - 1)
• Check the number of available menu options
• Use menu names instead of indices for reliability

“operator_name is required”

• When multiple operators are configured, specify which operator to control
• Use the exact operator name as configured in the Optool blocks

Advanced Features

Control Modes

The operator supports four control modes:

• disabled: Operator is not included in tool generation
• monitor: Read-only access for monitoring parameter values
• control: Full read/write access for parameter adjustment
• forced: Parameters are marked as required in tool calls

Pattern Matching

Parameter and page filtering supports wildcards:

• *: Matches all parameters/pages
• color*: Matches all parameters starting with “color”
• tx ty tz: Matches specific parameter names
• Common Transform: Matches specific page names

Response Format

The operator provides structured responses:

{
  "status": "success",
  "operation": "parameter_adjustment",
  "target_operator": "ramp1",
  "adjusted": ["color1r: 0.5 → 0.8", "color1g: 0.5 → 0.2"],
  "error": null
}

Logging and Debugging

When logging is enabled, all operations are recorded with:

• Timestamp of the operation
• Operation type and target operator
• Success/failure status
• Detailed information about changes made

This operator is essential for creating responsive, AI-controlled TouchDesigner systems that can adapt and respond to user needs in real-time.