tdmcp

Overview Schema Source Related Servers Discussions Admin

Manage custom parameters

add_custom_parameters

Destructive

Transactionally add, edit, delete, sort, and organize custom parameters on TouchDesigner COMPs, with rollback on failure.

Instructions

Transactionally add, edit, delete, sort, and organize a COMP's custom parameters through an authenticated structured TouchDesigner route. Legacy page+params calls remain valid. Supports Float, Int, Toggle, Str, Menu, Pulse, Header, OP, TOP, File, Folder, XYZW, RGBA, RGB, and XYZ; EXPRESSION and BIND are reversible and require TDMCP_RAW_PYTHON=on plus TDMCP_BRIDGE_ALLOW_EXEC=1 because their source is caller-supplied code. Constant and page-lifecycle operations remain available in restricted mode. EXPORT is explicitly HELD and returns an error without mutation. Built-ins are protected and failures roll back to the exact prior custom-page snapshot.

Input Schema

TableJSON Schema

Name	Required	Default
`page`	No	Custom
`params`	No
`comp_path`	Yes
`operations`	No
`idempotency_key`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed36 schema fields changedv0.13.2Aug 12, 2026

removedInput schema / properties / comp_path / description

Removed value: -"The COMP to add custom parameters to."

addedInput schema / properties / comp_path / maxLength
```
Added value: +1024
```
addedInput schema / properties / comp_path / minLength
```
Added value: +1
```
addedInput schema / properties / comp_path / pattern
```
Added value: +"^\\/.*"
```

addedInput schema / properties / idempotency_key

Added value: +{
+  "maxLength": 128,
+  "minLength": 16,
+  "pattern": "^[A-Za-z0-9_-]+$",
+  "type": "string"
+}

addedInput schema / properties / operations

Added value: +{
+  "items": {
+    "oneOf": [
+      {
+        "additionalProperties": false,
+        "properties": {
+          "action": {
+            "const": "add",
+            "type": "string"
+          },
+          "page": {
+            "default": "Custom",
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          },
+          "params": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "clamp": {
+                  "default": false,
+                  "type": "boolean"
+                },
+                "default": {
+                  "anyOf": [
+                    {
+                      "type": "number"
+                    },
+                    {
+                      "maxLength": 2048,
+                      "type": "string"
+                    },
+                    {
+                      "type": "boolean"
+                    },
+                    {
+                      "items": {
+                        "type": "number"
+                      },
+                      "maxItems": 4,
+                      "minItems": 1,
+                      "type": "array"
+                    }
+                  ]
+                },
+                "label": {
+                  "maxLength": 256,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "max": {
+                  "type": "number"
+                },
+                "menu_labels": {
+                  "items": {
+                    "maxLength": 256,
+                    "type": "string"
+                  },
+                  "maxItems": 64,
+                  "minItems": 1,
+                  "type": "array"
+                },
+                "menu_names": {
+                  "items": {
+                    "maxLength": 128,
+                    "minLength": 1,
+                    "type": "string"
+                  },
+                  "maxItems": 64,
+                  "minItems": 1,
+                  "type": "array"
+                },
+                "min": {
+                  "type": "number"
+                },
+                "name": {
+                  "maxLength": 128,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "size": {
+                  "maximum": 4,
+                  "minimum": 1,
+                  "type": "integer"
+                },
+                "type": {
+                  "enum": [
+                    "Float",
+                    "Int",
+                    "Toggle",
+                    "Menu",
+                    "Str",
+                    "Pulse",
+                    "Header",
+                    "OP",
+                    "TOP",
+                    "File",
+                    "Folder",
+                    "XYZW",
+                    "RGBA",
+                    "RGB",
+                    "XYZ"
+                  ],
+                  "type": "string"
+                }
+              },
+              "required": [
+                "name",
+                "type"
+              ],
+              "type": "object"
+            },
+            "maxItems": 64,
+            "minItems": 1,
+            "type": "array"
+          }
+        },
+        "required": [
+          "action",
+          "params"
+        ],
+        "type": "object"
+      },
+      {
+        "additionalProperties": false,
+        "properties": {
+          "action": {
+            "const": "edit_parameter",
+            "type": "string"
+          },
+          "fields": {
+            "additionalProperties": false,
+            "properties": {
+              "bind_expression": {
+                "maxLength": 2048,
+                "minLength": 1,
+                "type": "string"
+              },
+              "clamp": {
+                "type": "boolean"
+              },
+              "default": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "maxLength": 2048,
+                    "type": "string"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "items": {
+                      "type": "number"
+                    },
+                    "maxItems": 4,
+                    "minItems": 1,
+                    "type": "array"
+                  }
+                ]
+              },
+              "expression": {
+                "maxLength": 2048,
+                "minLength": 1,
+                "type": "string"
+              },
+              "label": {
+                "maxLength": 256,
+                "minLength": 1,
+                "type": "string"
+              },
+              "max": {
+                "type": "number"
+              },
+              "menu_labels": {
+                "items": {
+                  "maxLength": 256,
+                  "type": "string"
+                },
+                "maxItems": 64,
+                "minItems": 1,
+                "type": "array"
+              },
+              "menu_names": {
+                "items": {
+                  "maxLength": 128,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "maxItems": 64,
+                "minItems": 1,
+                "type": "array"
+              },
+              "min": {
+                "type": "number"
+              },
+              "mode": {
+                "enum": [
+                  "CONSTANT",
+                  "EXPRESSION",
+                  "BIND",
+                  "EXPORT"
+                ],
+                "type": "string"
+              },
+              "value": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "maxLength": 2048,
+                    "type": "string"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "items": {
+                      "type": "number"
+                    },
+                    "maxItems": 4,
+                    "minItems": 1,
+                    "type": "array"
+                  }
+                ]
+              }
+            },
+            "type": "object"
+          },
+          "name": {
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "action",
+          "name",
+          "fields"
+        ],
+        "type": "object"
+      },
+      {
+        "additionalProperties": false,
+        "properties": {
+          "action": {
+            "const": "delete_parameter",
+            "type": "string"
+          },
+          "name": {
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "action",
+          "name"
+        ],
+        "type": "object"
+      },
+      {
+        "additionalProperties": false,
+        "properties": {
+          "action": {
+            "const": "sort_page",
+            "type": "string"
+          },
+          "order": {
+            "items": {
+              "maxLength": 128,
+              "minLength": 1,
+              "type": "string"
+            },
+            "maxItems": 64,
+            "minItems": 1,
+            "type": "array"
+          },
+          "page": {
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "action",
+          "page",
+          "order"
+        ],
+        "type": "object"
+      },
+      {
+        "additionalProperties": false,
+        "properties": {
+          "action": {
+            "const": "rename_page",
+            "type": "string"
+          },
+          "new_name": {
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          },
+          "page": {
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "action",
+          "page",
+          "new_name"
+        ],
+        "type": "object"
+      },
+      {
+        "additionalProperties": false,
+        "properties": {
+          "action": {
+            "const": "delete_page",
+            "type": "string"
+          },
+          "page": {
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "action",
+          "page"
+        ],
+        "type": "object"
+      }
+    ]
+  },
+  "maxItems": 64,
+  "minItems": 1,
+  "type": "array"
+}

removedInput schema / properties / page / description

Removed value: -"Custom-parameter page name (auto-capitalized; created if missing)."

addedInput schema / properties / page / maxLength
```
Added value: +128
```
addedInput schema / properties / page / minLength
```
Added value: +1
```

removedInput schema / properties / params / description

Removed value: -"The parameters (knobs/menus/toggles/pulses) to append."

addedInput schema / properties / params / items / additionalProperties
```
Added value: +false
```

removedInput schema / properties / params / items / properties / clamp / description

Removed value: -"Hard-clamp the value to [min,max] (sets min/max + clampMin/clampMax)."

changedInput schema / properties / params / items / properties / default / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "boolean"
-  },
-  {
-    "items": {
-      "type": "number"
-    },
-    "type": "array"
-  }
-]New value: +[
+  {
+    "type": "number"
+  },
+  {
+    "maxLength": 2048,
+    "type": "string"
+  },
+  {
+    "type": "boolean"
+  },
+  {
+    "items": {
+      "type": "number"
+    },
+    "maxItems": 4,
+    "minItems": 1,
+    "type": "array"
+  }
+]

removedInput schema / properties / params / items / properties / default / description

Removed value: -"Initial value: a number; a string for Str/Menu (or '#rrggbb' for RGB); a bool for Toggle; or a number array for RGB/XYZ or a multi-component (size > 1) Float/Int."

removedInput schema / properties / params / items / properties / label / description
```
Removed value: -"Display label (defaults to `name`)."
```
addedInput schema / properties / params / items / properties / label / maxLength
```
Added value: +256
```
addedInput schema / properties / params / items / properties / label / minLength
```
Added value: +1
```
removedInput schema / properties / params / items / properties / max / description
```
Removed value: -"Slider upper bound (Float/Int) — sets normMax."
```
removedInput schema / properties / params / items / properties / menu_labels / description
```
Removed value: -"(Menu) display labels (defaults to names)."
```
addedInput schema / properties / params / items / properties / menu_labels / items / maxLength
```
Added value: +256
```
addedInput schema / properties / params / items / properties / menu_labels / maxItems
```
Added value: +64
```
addedInput schema / properties / params / items / properties / menu_labels / minItems
```
Added value: +1
```
removedInput schema / properties / params / items / properties / menu_names / description
```
Removed value: -"(Menu) stored option keys."
```
addedInput schema / properties / params / items / properties / menu_names / items / maxLength
```
Added value: +128
```
addedInput schema / properties / params / items / properties / menu_names / items / minLength
```
Added value: +1
```
addedInput schema / properties / params / items / properties / menu_names / maxItems
```
Added value: +64
```
addedInput schema / properties / params / items / properties / menu_names / minItems
```
Added value: +1
```
removedInput schema / properties / params / items / properties / min / description
```
Removed value: -"Slider lower bound (Float/Int) — sets normMin."
```

removedInput schema / properties / params / items / properties / name / description

Removed value: -"Parameter name; sanitized to a valid TD custom-par name (e.g. 'blur amount')."

addedInput schema / properties / params / items / properties / name / maxLength
```
Added value: +128
```
addedInput schema / properties / params / items / properties / name / minLength
```
Added value: +1
```

removedInput schema / properties / params / items / properties / size / description

Removed value: -"(Float/Int) number of components for a multi-value parameter (1–4)."

removedInput schema / properties / params / items / properties / type / description

Removed value: -"Widget kind. TD's append* picks the underlying parameter family."

changedInput schema / properties / params / items / properties / type / enum

Previous value: -[
-  "Float",
-  "Int",
-  "Toggle",
-  "Menu",
-  "Str",
-  "Pulse",
-  "RGB",
-  "XYZ"
-]New value: +[
+  "Float",
+  "Int",
+  "Toggle",
+  "Menu",
+  "Str",
+  "Pulse",
+  "Header",
+  "OP",
+  "TOP",
+  "File",
+  "Folder",
+  "XYZW",
+  "RGBA",
+  "RGB",
+  "XYZ"
+]

addedInput schema / properties / params / maxItems
```
Added value: +64
```

changedInput schema / required

Previous value: -[
-  "comp_path",
-  "params"
-]New value: +[
+  "comp_path"
+]

Addedv0.5.0May 29, 2026

TDQS

A4.1/5.0

Behavior5/5

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

The description provides rich behavioral detail beyond the annotations: it discloses transactional rollback, built-in protection, EXPORT being held with error, and EXPRESSION/BIND requiring specific settings. This significantly enhances the destructiveHint and openWorldHint annotations with concrete safety and failure semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but efficient, with each sentence adding unique value about transactionality, types, restrictions, and rollback. It is slightly long but the complexity justifies the length. The main purpose is front-loaded, making the tool's role immediately clear.

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

Completeness4/5

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

The description covers transactionality, restrictions, supported types, and failure behavior comprehensively, which is essential for a complex tool with 5 parameters and no output schema. It does not mention return values, but the operational focus makes this acceptable. Overall, it provides enough context for correct invocation.

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

Parameters3/5

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

With 0% schema description coverage, the description partially compensates by listing supported parameter types and explaining modes like EXPRESSION, BIND, and EXPORT. However, it does not elaborate on comp_path, page, operations, or idempotency_key, relying on their self-explanatory names. This is adequate but not thorough.

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

Purpose5/5

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

The description clearly states the tool's purpose: transactionally add, edit, delete, sort, and organize a COMP's custom parameters. This specific verb+resource combination distinguishes it from siblings like edit_td_node_metadata or set_parameters_batch, which focus on other parameter management tasks.

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

Usage Guidelines3/5

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

The description implies usage for managing custom parameters but does not explicitly state when to use this tool over alternatives. It mentions 'Legacy page+params calls remain valid' but does not contrast them with this route, and there is no explicit when-not guidance. Some context is given about restricted mode and required settings, but not enough to clearly guide tool selection.

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

Deploy Server

Manage custom parameters

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools