tdmcp

Create kinetic text

create_kinetic_text

Create animated kinetic typography with flash, pulse, or slide effects for live VJ text overlays. Automatically builds a TouchDesigner network with Text and LFO nodes, compositing over any input or transparent background.

Instructions

Build a self-contained animated / kinetic typography layer — a word or line that flashes, pulses, or slides, the signature live-VJ lyric-flash effect. A Text TOP renders the text; an LFO CHOP at the given Rate (Hz) drives the animation: 'flash' gates a Level TOP's alpha/opacity hard on/off (a square wave — the text vanishes between flashes rather than turning black, so it pops cleanly in and out over a background), 'pulse' drives a Transform TOP's scale plus a Level TOP alpha fade (a sine, the text breathes), and 'slide' scrolls the Transform TOP's translate-X. Creates a new baseCOMP under parent_path holding the Text TOP, the LFO, the per-mode Transform/Level nodes, an optional Composite, and a Null output. With an input_path the text is composited OVER that source (pulled in by a Select TOP, so it can live in another container); without one it animates on a transparent frame. Rate is free-running for v1 — bind the LFO's frequency to a beat CHOP (or a Trigger to a detect_onsets channel) to lock the flashes to the tempo. This is for a single animated word/line; for a static caption or title use create_text_overlay, and for multi-line scrolling tickers/credits rolls/typewriter reveals use create_text_crawl. Returns a summary plus a JSON block with the container path, created node paths, the text/lfo/output paths, exposed controls, any node errors, warnings, and an inline preview image.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "create_kinetic_text"
  }
}

Input Schema

Name	Required	Description	Default
`mode`	No	Animation style: 'flash' = hard on/off blink (a square LFO gates the alpha/opacity — the classic lyric-flash, the text vanishes between flashes rather than going black); 'pulse' = breathing scale-up + alpha fade driven by a sine LFO; 'slide' = the text scrolls horizontally across the frame.	flash
`size`	No	Font size in pixels (drives the Text TOP's fontsizex / fontsizey).
`text`	No	The word or line to animate (the lyric flash). Rendered by a Text TOP. For multiple lines use \n.	DUQUESA
`color`	No	Text colour as a hex string ('#ffffff' = white). Sets the Text TOP's fontcolorr/g/b.	#ffffff
`rate_hz`	No	Animation rate in cycles per second (Hz) — the LFO frequency. Free-running for v1; bind it to a beat CHOP to fire on the actual beat.
`input_path`	No	Optional absolute path of a source TOP to lay the text OVER. Pulled in via a Select TOP (TD wires don't cross containers) and composited under the text. If omitted, the text animates on a transparent frame.
`parent_path`	No	Parent network where the kinetic-text container is created (default '/project1').	/project1
`expose_controls`	No	When true (default), expose live Text / Size / Color / Rate controls bound to the right node parameters.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.13.1Aug 2, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Even though annotations already declare non-read-only and non-destructive, the description adds substantial behavioral detail: node hierarchy (Text TOP, LFO CHOP, Transform/Level nodes, Composite, Null), per-mode animation mechanics (flash vanishes rather than black, pulse breathes, slide scrolls), input compositing behavior with Select TOP, and rate binding to beat CHOP. This goes well beyond the annotations.

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 lengthy but each sentence carries useful information—alternatives, mode mechanics, input handling, and return format. It is a single dense paragraph rather than structured bullets, but it is not padded or redundant.

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

Completeness5/5

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

Despite no output schema, the description fully explains what the tool returns (summary, JSON block with paths/controls/errors/warnings/preview). It covers node creation, source compositing, rate binding, alternative tools, and edge cases (no input_path), leaving no obvious gaps.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3; description adds practical guidance beyond the schema, such as binding rate to a beat CHOP for tempo sync, and clarifies mode behavior in prose. This elevates it above the baseline, though much of the detail is already present in the schema.

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 states a specific verb ('Build') and resource ('self-contained animated / kinetic typography layer'), and clearly distinguishes itself from siblings by naming create_text_overlay for static captions and create_text_crawl for multi-line scrolling text.

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

Usage Guidelines5/5

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

Explicitly provides when-to-use context (live-VJ lyric-flash effect) and names exact alternatives with conditions: 'for a static caption or title use create_text_overlay, and for multi-line scrolling tickers/credits rolls/typewriter reveals use create_text_crawl.' This gives clear guidance on choosing the correct tool.

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

Deploy Server