Tool DAT

🔧 GetTool Enabled 1 tool

This operator exposes 1 tool that allow Agent and Gemini Live LOPs to read, create, append, insert, replace, delete, and find/replace content in Table and Text DATs with staged previews and undo support.

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

The Tool DAT gives agents safe, controlled access to edit Table and Text DATs inside your TouchDesigner project. Every mutating operation is staged first — the operator computes a preview and shows a unified diff before applying changes. A confirmation dialog lets you Apply, Always Allow, or Cancel each edit. All operations integrate with TouchDesigner’s undo system, so you can Ctrl+Z any agent-made change.

Key Features

• Staged editing with diffs: Every edit is previewed before applying, with a unified diff shown in a staging DAT
• Confirmation dialogs: Apply, Always Allow, or Cancel each change (or skip confirms entirely)
• Full undo support: All operations are wrapped in TD undo blocks with manual undo callbacks
• Dual mode: Works with both Table DATs (row/column/cell operations) and Text DATs (line-based and str_replace editing)
• Tool presets: One-click configurations for common use cases (Text Editing, Table Editing, Append Only, Read Only, All Enabled)
• Granular tool toggles: Enable/disable individual operations so the agent only sees the tools you want it to use
• Read-before-edit guard: Optionally require the agent to read content before making any changes

Input/Output

Inputs

None — the operator targets a DAT specified via the Target DAT parameter.

Outputs

• Output DAT: The last operation result
• Staging DAT: Preview of the next edit before it’s applied
• Diff DAT: Unified diff of the staged change
• Logger: Operation log with timestamps, status, and details (when logging is enabled)

Usage Examples

Quick Start: Let an Agent Edit a Table

1. Create a tool_dat operator and an agent operator.
2. On the tool_dat, set Tool Preset to Table Editing on the Tool DAT page.
3. Drag a Table DAT onto the Target DAT parameter.
4. On the agent’s Tools page, enable Use LOP Tools.
5. Drag the tool_dat onto an empty External Op Tools slot.
6. Ask the agent: “Add a row to the table with values Name, Age, City.”
7. A confirmation dialog appears showing the diff — click Apply to accept.

Quick Start: Agent-Driven Code Editing

1. Create a tool_dat operator.
2. Set Tool Preset to Text Editing — this enables str_replace, read_content, insert, and view_range, and turns on Require Read Before Edit.
3. Point Target DAT at a Text DAT containing code or config.
4. Connect to an agent via the Tools page.
5. The agent must call read_content first (the guard enforces this), then can use str_replace for precise edits — exactly like how Claude Code edits files.

Append-Only Logging

1. Set Tool Preset to Append Only.
2. Point Target DAT at an empty Table DAT.
3. The agent can only read and append rows — no deletes, no overwrites.
4. Useful for conversation logs, event tracking, or audit trails.

Auto-Confirm Mode

1. Toggle Skip Confirm (Always Allow) to On on the Tool DAT page.
2. All edits apply immediately without the confirmation dialog.
3. You can also click Always Allow on any confirmation dialog to enable this mid-session.

Skip Confirm

When Always Allow is on, the agent applies edits immediately with no confirmation. All changes still support undo (Ctrl+Z), but use this cautiously with destructive operations like Replace All or Delete Row.

Tool Presets

The Tool Preset menu on the Tool DAT page configures all tool toggles at once:

Preset	What’s Enabled	Best For
Text Editing	Read, str_replace, insert, view range + read-before-edit guard	Code editing, config files
Table Editing	All table operations (read, append, insert, replace, delete, update cell, find/replace)	Full table manipulation
Append Only	Read + append only	Logging, data collection
Read Only	Read + view range only	Inspection without modification
All Enabled	Everything	Development and testing
Custom	Manual toggle control	Fine-tuned permissions

After selecting a preset, you can still toggle individual tools. If the current state differs from the preset, the label shows Tool Preset (custom).

Table vs Text Mode

The operator auto-detects the DAT type when you set a Target DAT. The available tools change based on whether the target is a Table or Text DAT:

Table DAT tools: read_content, append_row, insert_row, replace_row, replace_column, replace_all_table, update_cell, delete_row, delete_column, insert_column, find_replace

Text DAT tools: read_content (with line numbers and optional view range), str_replace (exact match, must match exactly once), insert (at line position), append_text, replace_all_text, find_replace

Response Verbosity

The Response Verbosity menu controls how much data the agent receives after an operation:

• Minimal: Just success/error status
• Include Diff: Status + the unified diff of what changed
• Full Content: Status + diff + the full current content after the operation

Advanced Features

Require Read Before Edit

When enabled on the Tool DAT page, the agent must call read_content before any mutating operation. This prevents blind edits and ensures the agent works with current content. The Content Read indicator shows whether a read has occurred. The read state resets automatically when the target DAT changes.

Table Bias

The Table Bias menu adjusts tool descriptions to hint whether row 0 or column 0 contains headers. This doesn’t enforce anything at runtime — it just guides the agent’s understanding of the table structure.

DAT Creation

When Enable DAT Creation is on (in the Tool Toggles page), the agent can create brand new Table or Text DATs. Created DATs are positioned near the tool_dat operator and automatically become the new target. File extensions in the name (e.g., “config.json”) are detected and set the appropriate language mode.

Max Limits

Max Rows, Max Columns, and Max Characters (Text) on the Tool DAT page prevent the agent from creating excessively large content. Set to 0 for unlimited.

Troubleshooting

• Agent can’t see any tools: Check the Tool Toggles page — all operations default to Off in Custom preset. Use a preset like Table Editing or All Enabled.
• “Read required before edit” error: The agent needs to call read_content first. This is by design when Require Read Before Edit is on.
• Confirmation dialog not appearing: Skip Confirm (Always Allow) may be enabled. Toggle it off on the Tool DAT page.
• Agent tries to create a DAT instead of editing: The create_dat tool description warns against this, but some models still confuse “create” with “add data.” Disable Enable DAT Creation if this is a problem.

Parameters

Tool DAT

Require Read Before Next Edit (Requirereadbeforeedit) op('tool_dat').par.Requirereadbeforeedit Toggle

If enabled, agent must call read_content before any mutating operation

Default:

False

Target DAT (Datselect) op('tool_dat').par.Datselect DAT

Target DAT to operate on

Default:

"" (Empty String)

DAT Type (Dattype) op('tool_dat').par.Dattype Menu

Default:

table

Options:

table, text

Auto-create Missing DATs (Createifmissing) op('tool_dat').par.Createifmissing Toggle

Automatically create DAT if target is missing

Default:

False

Clear Target on GetTool (Cleartargetongettool) op('tool_dat').par.Cleartargetongettool Toggle

Clear the target DAT content when GetTool is called by agent

Default:

False

Response Verbosity (Responseverbosity) op('tool_dat').par.Responseverbosity Menu

Control how much data is returned after operations

Default:

minimal

Options:

minimal, diff, full

Skip Confirm (Always Allow) (Alwaysallow) op('tool_dat').par.Alwaysallow Toggle

If enabled, edits apply immediately without asking

Default:

False

Tool Name (Toolname) op('tool_dat').par.Toolname Str

Default:

"" (Empty String)

Max Rows (Maxrows) op('tool_dat').par.Maxrows Int

Default:

0

Range:

0 to 1

Slider Range:

0 to 1

Max Columns (Maxcolumns) op('tool_dat').par.Maxcolumns Int

Default:

0

Range:

0 to 1

Slider Range:

0 to 1

Content Read (Contentread) op('tool_dat').par.Contentread Toggle

Display: has content been read this session? (read-only)

Default:

False

Max Characters (Text) (Maxchars) op('tool_dat').par.Maxchars Int

Default:

0

Range:

0 to 1

Slider Range:

0 to 1

Reset Read State (Resetreadstate) op('tool_dat').par.Resetreadstate Pulse

Reset the read state flag

Default:

False

Table Bias (Tablebias) op('tool_dat').par.Tablebias Menu

Adjusts tool descriptions to suggest headers in row 0 or column 0. Does not enforce at runtime.

Default:

none

Options:

none, row_headers, column_headers

Tool Toggles

Enable Set Target (Enablesettarget) op('tool_dat').par.Enablesettarget Toggle

Allow agent to change target DAT

Default:

True

Enable Check Target (Enablechecktarget) op('tool_dat').par.Enablechecktarget Toggle

Allow agent to check current target

Default:

False

Enable DAT Creation (Enablecreation) op('tool_dat').par.Enablecreation Toggle

Allow agent to create new DATs

Default:

False

Tool Preset (Toolpreset) op('tool_dat').par.Toolpreset Menu

Preset configurations for common use cases

Default:

custom

Options:

custom, text_editing, table_editing, append_only, read_only, all_enabled

Enable Read (Enableread) op('tool_dat').par.Enableread Toggle

Enable read_content tool

Default:

False

Enable Append (Enableappend) op('tool_dat').par.Enableappend Toggle

Enable append tool (append_row for tables, append_text for text)

Default:

False

Enable Insert (Enableinsert) op('tool_dat').par.Enableinsert Toggle

Enable insert at position (insert_row for tables, insert for text)

Default:

False

Enable Replace All (Enablereplaceall) op('tool_dat').par.Enablereplaceall Toggle

Enable replacing entire content

Default:

False

Enable Find/Replace (Enablefindreplace) op('tool_dat').par.Enablefindreplace Toggle

Enable find and replace operations

Default:

False

Enable Replace Row (Enablereplacerow) op('tool_dat').par.Enablereplacerow Toggle

[Table] Replace a specific row

Default:

False

Enable Replace Column (Enablereplacecolumn) op('tool_dat').par.Enablereplacecolumn Toggle

[Table] Replace a specific column

Default:

False

Enable Update Cell (Enableupdatecell) op('tool_dat').par.Enableupdatecell Toggle

[Table] Update a single cell

Default:

False

Enable Delete Row (Enabledeleterow) op('tool_dat').par.Enabledeleterow Toggle

[Table] Delete a row

Default:

False

Enable Delete Column (Enabledeletecolumn) op('tool_dat').par.Enabledeletecolumn Toggle

[Table] Delete a column

Default:

False

Enable Insert Column (Enableinsertcolumn) op('tool_dat').par.Enableinsertcolumn Toggle

[Table] Insert a column at position

Default:

False

Enable str_replace (Enablestrreplace) op('tool_dat').par.Enablestrreplace Toggle

[Text] Exact match text replacement (recommended for code editing)

Default:

False

Enable View Range (Enableviewrange) op('tool_dat').par.Enableviewrange Toggle

[Text] Enable line_start/line_end in read_content for partial reads

Default:

False

Changelog

v2.3.02026-02-06

• Add str_replace tool for exact match text replacement - Add insert tool for line-based text insertion - Add view_range support with line_start/line_end for partial reads - Add line numbers to text read output - Add require-read-before-edit gate with state tracking - Add tool presets system (text_editing, table_editing, append_only, read_only, all_enabled) - Reorganize tool toggles to separate page with unified append/insert toggles - Add file extension detection and language setting for created text DATs - Add name sanitization for created DATs - Add JSON parse error handling in HandleToolCall

v2.2.02025-12-06

## Changes from v2.1.1

New Features

• Added append_row operation - Simplest way to add data to a table by appending rows to the end
• Added Enable Append Row parameter toggle to control tool availability
• Agents can now append rows without needing to specify insert positions

Improvements

• Streamlined workflow for common table population use cases
• Reduced agent cognitive load when simply adding new data rows

Impact

• Most common DAT editing pattern (adding rows) is now the easiest to execute
• Agents no longer need to calculate row indices for simple append operations
• Cleaner agent tool descriptions for basic table building tasks

v2.1.12025-10-29

New Features

• Added check_target tool to verify which DAT is currently selected
• Added set_target tool to allow agents to change the target DAT by path
• Added Enable Check Target parameter to toggle check_target tool availability
• Added Enable Set Target parameter to toggle set_target tool availability

Bug Fixes

• CRITICAL: Fixed tool descriptions causing agents to create new DATs instead of editing existing ones
• Fixed create_dat description to explicitly state "ONLY use this to create a brand NEW separate data container"
• Fixed all editing operations to clearly state "Works on existing target, does NOT create new"
• Fixed read_content description to explicitly state "target is ALREADY SELECTED - you do not need to search for it"
• Added current target path dynamically to read_content tool description
• Fixed agents incorrectly thinking they need to "locate" or "find" the target DAT

Impact

• Agents now correctly understand when to use create_dat vs editing operations
• Reduced confusion about target DAT selection (agents know it's pre-selected)
• Agents can now verify and change targets when needed
• Dramatically improved agent workflow reliability with DAT manipulation

v2.1.02025-09-24

add clearongettool parameter to clear the target DAT on gettool - probably some other changes.

v2.0.02025-08-17

Major Architecture Changes

• Complete rewrite as StagedDatToolEXT with staged editing workflow
• Explicit operation enum - one tool per operation instead of single multi-purpose tool
• No side effects in GetTool() - all mutations happen in the handler
• Staged preview system with dedicated staging and diff DATs
• Confirmation workflow with Apply/Always Allow/Cancel options via UI messageBox
• Undo/Redo support with proper TouchDesigner undo blocks and manual callbacks

Tool Schema Improvements

• Separate tools per operation instead of single complex tool with mode switching
• Clearer parameter names and descriptions for better AI model understanding
• Table bias system with hints for header placement (row 0 vs column 0)
• Better validation with proper min/max constraints and type checking
• Enhanced error messages with specific bounds checking and helpful guidance

New Operations

• create_dat - Create new table or text DATs with optional initial content
• insert_row - Insert rows at specific positions (other rows shift down)
• insert_column - Insert columns at specific positions (other columns shift right)
• Enhanced find_replace - Now supports regex patterns and case sensitivity options

Parameter Reorganization

• Individual enable toggles for each operation type (read, replace_row, replace_column, etc.)
• Response verbosity control (minimal, diff, full) to control output detail
• Table bias setting to suggest header conventions without enforcement
• Always Allow parameter to bypass confirmations after user approval
• Separate creation controls (Enable DAT Creation, Auto-create Missing DATs)

User Experience Improvements

• Visual staging - Operations are previewed in staging DATs before applying
• Unified diff display - Clear before/after comparisons in dedicated diff DAT
• Better error handling with operation-specific validation messages
• Confirmation dialogs prevent accidental data loss
• Improved logging with operation tracking and status reporting
• Auto-positioning of created DATs near the tool component

Technical Enhancements

• Robust argument normalization - Handles various input formats gracefully
• Proper limit enforcement with configurable max rows/columns/characters
• Memory-safe operations with preview validation before applying changes
• Better type coercion - Handles string/int conversions and list normalization
• Enhanced CSV support for table operations
• 1-based line numbering for text operations (more intuitive for users)

Removed/Deprecated

• Context injection system - Simplified tool focuses purely on DAT operations
• Single multi-mode tool - Replaced with explicit operation-specific tools
• Automatic clearing - Operations now preserve existing data unless explicitly replacing
• Complex parameter dependencies - Simplified to independent operation toggles

Developer Experience

• Cleaner code organization with separate methods for each operation type
• Better separation of concerns between preview and apply logic
• Comprehensive error handling with try/catch blocks and proper logging
• Extensible architecture for adding new operations in the future

v1.0.02024-11-06

Initial release

Related Operators

• Agent
• Tool Parameter
• Tool Vfs
• Tool Monitor