tdmcp

Create 3D audio-reactive scene

create_3d_audio_reactive

Build a 3D scene that reacts to audio, generating a spectrum bar graph or bass-pulse geometry with camera, lighting, and render, driven by live mic, a file, or a test tone.

Instructions

Build a 3D scene that reacts to sound — the 3D counterpart of create_audio_reactive (use that for a 2D spectrum visual instead). Creates a new baseCOMP under parent_path. An FFT spectrum chain feeds geometry: 'instanced_bars' renders a row of bands boxes/spheres whose individual heights track each frequency bin (a 3D spectrum bar-graph), while 'bass_pulse' swells a single primitive with the low-frequency energy. Includes a Camera, Light, and Render TOP, output as a Null TOP. Exposes Sensitivity (audio gain), Zoom (camera distance), and Spin (whole-scene rotation) knobs. Source can be the live device (mic/line — may prompt for macOS permission), an audio file, a synthetic oscillator (for testing), or an existing CHOP. Returns a summary plus a JSON block with the container path, created node paths, the spectrum/geometry/camera/render/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_3d_audio_reactive"
  }
}

Input Schema

Name	Required	Description	Default
`mode`	No	'instanced_bars' = a row of `bands` boxes/spheres, each one's height driven by one frequency bin (a 3D spectrum bar-graph). 'bass_pulse' = a single primitive that swells with the low-frequency energy (the guaranteed-visible fallback).	instanced_bars
`spin`	No	Whole-scene rotation around Y in degrees/sec (0 = still). Spins the entire bar row / object over time.
`bands`	No	Number of bars in 'instanced_bars' mode — one per frequency bin.
`source`	No	Audio source. 'device' = live microphone/line in (the real-world default; creating it may pop a one-time macOS microphone-permission dialog — click Allow). 'file' = an audio file. 'oscillator' = a synthetic tone (white noise → energy in every band, handy for testing without any device permission). 'existing_chop' = reuse a CHOP you already have.	device
`primitive`	No	Geometry rendered for each bar / the pulsing object.	box
`parent_path`	No	Parent network where the scene container is created (default '/project1').	/project1
`audio_file_path`	No	Path to an audio file to play; used only when source='file'.
`expose_controls`	No	When true (default), expose live Sensitivity (audio gain), Zoom (camera distance), and Spin knobs.
`existing_chop_path`	No	Path of an existing audio CHOP to analyze; used only when source='existing_chop'.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.13.1Aug 2, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond annotations (readOnlyHint false, openWorldHint true, destructiveHint false), the description discloses specific behavioral traits: creates a baseCOMP under parent_path, includes Camera/Light/Render TOP and Null TOP output, exposes Sensitivity/Zoom/Spin controls, warns about a macOS microphone-permission prompt, and describes the return payload (summary + JSON block with paths, errors, warnings, preview image). No contradiction with annotations.

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

Conciseness5/5

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

The description is well-structured and front-loaded with the core purpose, then systematically explains modes, components, controls, sources, and return value. Every sentence adds information; there is no filler or repetition of schema field text. Despite its length, it remains appropriately concise for a complex build tool.

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?

This is a complex tool with 9 parameters, no output schema, and only basic annotations. The description fully compensates by covering the generated node structure, source options, permission caveat, exposed controls, return format, and fallback behavior. It provides enough context for an agent to invoke the tool correctly and interpret the result.

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?

Input schema covers 100% of parameters with detailed descriptions, so baseline is 3. The description adds extra semantic value beyond schema: 'bass_pulse' is described as the guaranteed-visible fallback, 'oscillator' is 'handy for testing without any device permission', and it explains the FFT spectrum mapping context. These nuances help parameter selection beyond what the schema already provides.

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 opens with a specific verb+resource ('Build a 3D scene that reacts to sound') and clearly distinguishes this from the sibling create_audio_reactive (2D counterpart). It also differentiates from other 3D creation tools like create_3d_scene by focusing on audio reactivity and FFT-driven geometry.

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?

The description explicitly names the alternative tool (create_audio_reactive) for 2D spectrum visuals and provides guidance on choosing between modes (instanced_bars vs bass_pulse fallback) and sources (device/file/oscillator/existing_chop), including when oscillator is handy for testing without device permission. This is clear when-to-use and alternative guidance.

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

Deploy Server