Tool Monitor Operator

The Tool Monitor operator (formerly Activity Monitor) is an advanced LLM operator that monitors and logs activity within TouchDesigner projects while providing AI tool integration capabilities. It captures comprehensive information about operator selections, network navigation, parameter modifications, and errors, creating a detailed history of project development and usage. The operator now includes GetTool functionality, enabling AI agents and systems like Gemini Live to access structured activity data for intelligent assistance and workflow analysis.

This operator is essential for debugging, understanding workflow patterns, documenting project changes, and enabling AI-powered development assistance within the TouchDesigner environment.

Agent Tool Integration

🔧 GetTool Enabled 1 tool

This operator exposes 1 tool that allow Agent and Gemini Live LOPs to access structured activity data for intelligent workflow analysis and debugging assistance.

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

The Tool Monitor operator provides the get_recent_activity tool for AI agents and Gemini Live integration, allowing them to understand current TouchDesigner workflow patterns and provide intelligent assistance based on user activity.

Requirements

• No additional Python packages required
• No additional setup required
• Compatible with AI agents and Gemini Live integration

Input/Output

Inputs

None

Outputs

• Activity Log (DAT): Main activity log table with comprehensive columns:
  • Timestamp, ActivityType, Path, OpType, OpFamily
  • HoverPath, HoverType, ModifiedPars, Details
  • Context, Changes, Error
• Current State (DAT): Real-time current state information with same columns
• Headers (DAT): Column headers reference table

Parameters

Activity Settings

Note: This operator should be fast - 100% 60 fps Header

if project is dropping FPS, check for data loops Header

Maximum Lines (Maxlines) op('tool_monitor').par.Maxlines Integer

Specifies the maximum number of rows to keep in the activity log table. Older entries are automatically removed when the log exceeds this limit.

Default:

10

Poll Timer Length (Length) op('tool_monitor').par.Length Float

Sets the frequency (in seconds) at which the operator checks for new activity. A shorter interval provides more real-time updates, but may increase processing load.

Default:

10.0

Hide Heavy Viewers (Hideheavyviewer) op('tool_monitor').par.Hideheavyviewer Toggle

When enabled, the operator automatically disables viewers for operators containing large amounts of text data (DATs) to improve performance. This is particularly useful when working with large datasets or complex networks.

Default:

false

Max Characters (Maxchars) op('tool_monitor').par.Maxchars Integer

Defines the threshold for considering a DAT 'heavy' based on the number of characters it contains. If a DAT's character count exceeds this value, its viewer will be automatically disabled when Hide Heavy Viewers is enabled.

Default:

0

Tracking Settings

Set Tracking Header

Track Selection (Trackselection) op('tool_monitor').par.Trackselection Toggle

When enabled, tracks selected/current operator changes and logs them to the activity table.

Default:

false

Track Hover (Trackhover) op('tool_monitor').par.Trackhover Toggle

When enabled, tracks operator hover events and mouse-over interactions in the network editor.

Default:

false

Track Parameters (Trackparameters) op('tool_monitor').par.Trackparameters Toggle

When enabled, tracks parameter modifications and captures detailed information about changed values.

Default:

false

Track Context (Trackcontext) op('tool_monitor').par.Trackcontext Toggle

When enabled, tracks additional context information including pane selection, node positions, and content previews.

Default:

false

GetTool Settings

GetTool Header

Recent Count (Recentcount) op('tool_monitor').par.Recentcount Integer

Number of recent activity entries to return when AI agents call the get_recent_activity tool. Range: 1-50. Higher values provide more context but may impact performance.

Default:

0

Max Characters (Maxcharacters) op('tool_monitor').par.Maxcharacters Integer

Maximum number of characters to include in each field when returning data to AI agents. Range: 100-10000. Helps prevent oversized responses and maintains performance.

Default:

0

About

Bypass (Bypass) op('tool_monitor').par.Bypass Toggle

When enabled, the operator is bypassed, effectively disabling its functionality without removing it from the network.

Default:

false

Show Built-in Parameters (Showbuiltin) op('tool_monitor').par.Showbuiltin Toggle

When enabled, the operator displays all built-in TouchDesigner parameters in addition to the custom parameters.

Default:

false

Version (Version) op('tool_monitor').par.Version String

Displays the version number of the Tool Monitor operator.

Default:

"" (Empty String)

Last Updated (Lastupdated) op('tool_monitor').par.Lastupdated String

Shows the date of the last update to the Tool Monitor operator.

Default:

"" (Empty String)

Creator (Creator) op('tool_monitor').par.Creator String

Indicates the creator of the Tool Monitor operator.

Default:

"" (Empty String)

Website (Website) op('tool_monitor').par.Website String

Provides a link to the creator's website.

Default:

"" (Empty String)

ChatTD Operator (Chattd) op('tool_monitor').par.Chattd OP

Specifies the path to the ChatTD operator used by the Tool Monitor.

Default:

"" (Empty String)

AI Tool Integration

The Tool Monitor operator provides the get_recent_activity tool for AI agents and Gemini Live integration:

Tool Definition

{
  "type": "function",
  "function": {
    "name": "get_recent_activity",
    "description": "Retrieve recent user activity in the TouchDesigner network, including selected operators, parameters, and changes. Returns structured JSON data of the last N activities.",
    "parameters": {
      "type": "object",
      "properties": {},
      "required": []
    }
  }
}

Tool Response Format

{
  "status": "success",
  "activities": [
    {
      "Timestamp": "2025-01-14 10:30:15.123456",
      "ActivityType": "SELECTED",
      "Path": "/project/noise1",
      "OpType": "noise/TOP",
      "OpFamily": "TOP",
      "HoverPath": "/project/level1",
      "HoverType": "level/TOP",
      "ModifiedPars": "['seed=42', 'amplitude=0.5']",
      "Details": "{'name': 'noise1', 'type': 'noise', ...}",
      "Context": "{'pane': 'networkeditor1', 'node_pos': {'x': 100, 'y': 200}}",
      "Changes": "Parameters changed: ['seed=42', 'amplitude=0.5']",
      "Error": ""
    }
  ]
}

Performance Considerations

The Tool Monitor is designed to maintain 60 FPS performance while providing comprehensive activity tracking:

• Lightweight Operation: Optimized polling and data structures minimize performance impact
• Configurable Tracking: Individual tracking toggles allow fine-tuning of monitoring scope
• Viewer Management: Automatic heavy viewer control prevents performance degradation
• Data Limiting: Configurable limits on log size and character counts maintain responsiveness

Performance Optimization Tips

• Use longer polling intervals (Length parameter) for better performance
• Enable Hide Heavy Viewers for projects with large DATs
• Adjust Maxchars threshold based on your project’s data size
• Disable unnecessary tracking toggles to reduce overhead
• Monitor Recent Count and Max Characters for AI tool calls

Usage Examples

Basic Activity Monitoring

# Access activity monitor outputs
activity_log = op('tool_monitor/ActivityLog')
current_state = op('tool_monitor/CurrentState')

# Configure basic logging
op('tool_monitor').par.Maxlines = 50
op('tool_monitor').par.Length = 1.0  # Check every second
op('tool_monitor').par.Trackselection = True
op('tool_monitor').par.Trackparameters = True

AI Tool Integration Setup

# Configure for AI agent integration
monitor = op('tool_monitor')
monitor.par.Recentcount = 10  # Return last 10 activities
monitor.par.Maxcharacters = 2000  # Limit response size
monitor.par.Trackselection = True
monitor.par.Trackparameters = True
monitor.par.Trackcontext = True

# Enable all tracking for comprehensive AI context
monitor.par.Trackhover = True

Performance Optimization

# Optimize for large projects
monitor = op('tool_monitor')
monitor.par.Hideheavyviewer = True
monitor.par.Maxchars = 50000  # Lower threshold for heavy DATs
monitor.par.Length = 2.0  # Slower polling for better performance
monitor.par.Maxlines = 25  # Keep fewer history entries

Debugging and Analysis

# Access detailed activity data
activity_log = op('tool_monitor/ActivityLog')

# Find recent errors
error_rows = []
for row in range(1, activity_log.numRows):
    if activity_log[row, 'Error'].val:
        error_rows.append(row)

# Track parameter modifications
param_changes = []
for row in range(1, activity_log.numRows):
    if activity_log[row, 'ModifiedPars'].val:
        param_changes.append({
            'timestamp': activity_log[row, 'Timestamp'].val,
            'operator': activity_log[row, 'Path'].val,
            'parameters': activity_log[row, 'ModifiedPars'].val
        })

# Clear log for fresh analysis
op('tool_monitor').clear_log()

Integration Examples

With Agent Operator

# Connect Tool Monitor to Agent for context awareness
monitor = op('tool_monitor')
monitor.par.Recentcount = 5
monitor.par.Trackselection = True
monitor.par.Trackparameters = True

With Chat Systems

# Connect to ChatTD for enhanced chat context
monitor = op('tool_monitor')
monitor.par.Chattd = op('ChatTD')
monitor.par.Trackcontext = True
monitor.par.Maxcharacters = 1500

Best Practices

• Start Conservative: Begin with basic tracking enabled, add features as needed
• Monitor Performance: Watch for FPS drops and adjust polling frequency accordingly
• Optimize for Use Case: Configure tracking toggles based on your specific monitoring needs
• AI Integration: Set appropriate Recent Count and Max Characters for AI responses
• Performance Management: Enable heavy viewer control for projects with large DATs

Troubleshooting

Performance Issues

• FPS Drops: Increase Length parameter, reduce tracking scope, check for data loops
• Memory Usage: Reduce Maxlines and Maxchars parameters
• Heavy Viewers: Enable Hide Heavy Viewers and adjust threshold

AI Tool Integration

• Empty Responses: Check Recent Count parameter and ensure tracking is enabled
• Oversized Responses: Reduce Max Characters parameter
• Missing Context: Enable appropriate tracking toggles
• Tool Not Available: Verify GetTool functionality is enabled

Common Issues

• Log Not Updating: Check if operator is bypassed, verify polling timer is running
• Context Missing: Ensure context tracking is enabled and functioning
• AI Integration Failures: Verify ChatTD connection and tool configuration

Note

The Tool Monitor operator is designed to maintain 60 FPS performance. If you experience issues, start by adjusting the polling frequency and enabling heavy viewer management.