Skip to content
LOPS Docs

Tool Monitor

v1.2.0
🔧 GetTool Enabled 2 tools

This operator exposes 2 tools that allow Agent and Gemini Live LOPs to retrieve recent user activity in the TouchDesigner network and capture screenshots of the current network view.

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

The Tool Monitor tracks what you’re doing in your TouchDesigner network — which operators you select, what parameters you change, what errors appear — and exposes this information as tools that agents can call. This gives agents real-time awareness of your current workflow context.

Key Features

Section titled “Key Features”
  • Activity tracking: Captures operator selections, parameter changes, hover targets, errors, and context
  • Change deduplication: Only logs meaningful changes by comparing against the previous activity
  • Network screenshots: Captures and sends the current TouchDesigner window to vision-capable models
  • Granular data control: Toggle exactly which data fields are collected and sent to the agent
  • Heavy viewer management: Automatically hides viewers on operators with large content to prevent slowdowns

Input/Output

Section titled “Input/Output”

Inputs

Section titled “Inputs”

None — the operator monitors TouchDesigner’s built-in state variables (CURRENT, OP_SELECT, OP_ROLLOVER).

Outputs

Section titled “Outputs”
  • ActivityLog: Table of all captured activity events with timestamps and change summaries
  • CurrentState: The most recent activity snapshot
  • Headers: Column header reference table

Tools

Section titled “Tools”

get_recent_activity

Section titled “get_recent_activity”

Returns the most recent user activities as structured JSON. The agent receives a filtered subset of the activity log based on your data collection settings.

The response includes:

  • Activity entries (filtered by your toggle settings)
  • A data summary with character counts, field counts, and which filters are enabled/disabled

capture_network_screenshot

Section titled “capture_network_screenshot”

Captures a screenshot of the current TouchDesigner window and returns it as a base64-encoded PNG. Requires a vision-capable model (e.g., GPT-4o, Claude with vision). The operator automatically finds the TouchDesigner window and handles resizing.

Usage Examples

Section titled “Usage Examples”

Basic Activity Monitoring

Section titled “Basic Activity Monitoring”
  1. Create a tool_monitor operator in your network.
  2. On the Activity page, the default data collection toggles are already configured for typical use.
  3. Connect the tool_monitor to an agent operator via the External Op Tools parameter on the agent’s Tools page.
  4. Ask the agent something like “What am I working on?” — the agent calls get_recent_activity and sees your recent selections, parameter changes, and any errors.

Giving an Agent Visual Context

Section titled “Giving an Agent Visual Context”
  1. On the Activity page under Screenshot Settings, ensure Enable Screenshots is On.
  2. Set Screenshot Width and Screenshot Height to control the resolution (default 1280x720).
  3. When the agent calls capture_network_screenshot, it receives a PNG of your current TouchDesigner window.
  4. Use this with vision-capable models so the agent can see your network layout and provide more context-aware help.

Tuning Data Collection

Section titled “Tuning Data Collection”

The Data Collection toggles on the Activity page control what information is captured and sent to the agent:

ToggleWhat It Includes
Include Basic InfoTimestamp, activity type, operator path, type, and family
Include Hover InfoWhich operator the mouse is hovering over
Include ParametersAll non-default parameters on the selected operator
Include DetailsDetailed operator info (name, type, valid state, etc.)
Include ContextNode position, parent path, and content preview for DATs
Include ErrorsScript errors, warnings, operator errors, and recursive errors
Include ChangesSummary of what changed since the last capture

Start with Basic Info and Errors enabled, then add more as needed. More toggles means more tokens per tool call.

Reducing Noise

Section titled “Reducing Noise”
  • Set Min Capture Delay to a higher value (e.g., 0.5 seconds) to avoid logging rapid-fire selections.
  • Set Recent Count to control how many activities the agent receives per tool call (default 5).
  • Set Max Characters to limit how much text each field can contain before truncation.
  • Poll Timer Length controls how often the operator captures activity (default 10 seconds).

Heavy Viewer Management

Section titled “Heavy Viewer Management”

Toggle Hide Heavy Viewers on the Activity page to automatically disable the viewer on any sibling operator whose content exceeds Max Characters (the viewer threshold, not the tool field limit). This prevents TouchDesigner from rendering massive DAT viewers that can cause frame drops.

Troubleshooting

Section titled “Troubleshooting”
  • Agent doesn’t see the activity tool: Check that Enable Activity Tool is On under Tool Settings on the Activity page.
  • Agent doesn’t see the screenshot tool: Check that Enable Screenshots is On under Screenshot Settings.
  • Screenshot returns an error: The screengrab TOP needs to find the TouchDesigner window by name. If your project name has changed since the operator was created, the operator will attempt fuzzy matching automatically.
  • Too much data in tool responses: Reduce the data collection toggles, lower Recent Count, or lower Max Characters under Tool Settings.
  • Frame drops: Increase Poll Timer Length or Min Capture Delay, and enable Hide Heavy Viewers.

Parameters

Section titled “Parameters”

Activity

Section titled “Activity”
Note: This operator should be fast - 100% 60 fps Header
if project is dropping FPS, check for data loops Header
Poll Timer Length (Length) op('tool_monitor').par.Length Float
Default:
10.0
Range:
0 to 1
Slider Range:
0 to 10
Hide Heavy Viewers (Hideheavyviewer) op('tool_monitor').par.Hideheavyviewer Toggle

Automatically disable viewers for operators with large content

Default:
False
Max Characters (Maxchars) op('tool_monitor').par.Maxchars Int

Maximum number of characters to display in a viewer

Default:
0
Range:
10000 to 1000000
Slider Range:
10000 to 1000000
Data Collection Header
Include Basic Info (Includebasic) op('tool_monitor').par.Includebasic Toggle

Timestamp, ActivityType, Path, OpType, OpFamily (always logged & sent)

Default:
False
Include Hover Info (Includehover) op('tool_monitor').par.Includehover Toggle

Track and send hover information

Default:
False
Include Parameters (Includeparameters) op('tool_monitor').par.Includeparameters Toggle

Track and send modified parameters

Default:
False
Include Details (Includedetails) op('tool_monitor').par.Includedetails Toggle

Track and send detailed operator info

Default:
False
Include Context (Includecontext) op('tool_monitor').par.Includecontext Toggle

Track and send additional context (position, content preview)

Default:
False
Include Errors (Includeerrors) op('tool_monitor').par.Includeerrors Toggle

Track and send script errors, warnings, and operator errors

Default:
False
Include Changes (Includechanges) op('tool_monitor').par.Includechanges Toggle

Track and send changes summary

Default:
False
Tool Settings Header
Recent Count (Recentcount) op('tool_monitor').par.Recentcount Int

Number of recent activities to return to assistant (FIFO)

Default:
0
Range:
1 to 50
Slider Range:
1 to 50
Max Characters (Maxcharacters) op('tool_monitor').par.Maxcharacters Int

Maximum characters per field sent to assistant

Default:
0
Range:
100 to 10000
Slider Range:
100 to 10000
Min Capture Delay (sec) (Mincapturedelay) op('tool_monitor').par.Mincapturedelay Float

Minimum time between captures to reduce noise

Default:
0.0
Range:
0.1 to 5
Slider Range:
0.1 to 5
Debug Settings Header

Changelog

Section titled “Changelog”
v1.2.02025-08-18
  • Unified Parameter Structure: Simplified from 30+ parameters to 13 unified parameters. Single "Include X" parameters now control both table logging AND assistant sending for perfect transparency
  • Enhanced Error Detection: Added recursive error detection using errors(recurse=True) and scriptErrors(recurse=True) to catch nested script errors in child operators
  • Fixed Duplication Issues: Improved change detection to prevent duplicate entries and false change logging
  • Reduced Capture Delay: Lowered minimum capture delay from 0.5s to 0.1s for more responsive error detection
  • Character Count Logging: Added logging of total characters sent to assistant with detailed data volume reporting
  • Debug Mode: Added comprehensive error detection debugging with detailed logging of what methods return
v1.1.12025-07-24
  • Restored GetTool Functionality: Fixed a critical bug in the GetTool method that prevented it from returning a tool definition. The method was attempting to evaluate a header parameter (Gettool), which caused it to fail silently and return None. This made the get_recent_activity tool unavailable to any agent. The invalid logic has been removed, ensuring the tool is now correctly registered.
v1.1.02025-01-14

Major Enhancement: GetTool Integration

  • Added GetTool functionality - The tool_monitor is now GetTool enabled, allowing AI agents and Gemini Live to access recent user activity data
  • New tool: get_recent_activity - Returns structured JSON data of recent TouchDesigner user activities including operator selections, parameter changes, and navigation patterns

New Parameters - Tracking Controls

  • Track Selection - Toggle to control tracking of selected/current operators (default: On)
  • Track Hover - Toggle to control tracking of hovered operators (default: On)
  • Track Parameters - Toggle to control tracking of modified parameters (default: On)
  • Track Context - Toggle to control tracking of additional context data (default: On)

New Parameters - GetTool Configuration

  • Enable GetTool - Master toggle to enable/disable tool availability to agents (default: On)
  • Recent Count - Configure number of recent activity entries returned by tool (default: 5, range: 1-50)
  • Max Characters - Limit string field lengths in tool responses to prevent oversized data (default: 1000, range: 100-10000)

Enhanced Data Flow

  • Conditional data collection - Activity capture now respects tracking toggles, only collecting enabled data types
  • Response truncation - Tool responses automatically truncate long strings to prevent token overflow
  • Structured JSON output - Tool returns clean, structured activity data optimized for AI agent consumption

UI Improvements

  • Consolidated parameter organization - All parameters moved to single 'Activity' page with logical section headers
  • Comprehensive help text - Detailed multiline help documentation for all GetTool parameters explaining functionality and usage
  • Visual parameter grouping - Added section headers for "Tracking Settings" and "GetTool Settings"

Technical Enhancements

  • Error handling - Robust error handling in tool responses with status indicators
  • Performance optimization - Efficient data retrieval with configurable limits
  • Agent integration ready - Full compatibility with agent orchestrator and Gemini Live workflows
v1.0.02024-11-06

Initial release

Section titled “Related Operators”