hydra-mcp

hydra_block

Write a named Hydra code block and run it while other blocks keep playing. Dry-run validation prevents broken shaders from touching the live canvas.

Instructions

Write one named block of Hydra code and run it, leaving every other block playing.

name: letters, digits, _ and -, starting with a letter (e.g. "base", "feedback"). Writing an existing name replaces that block — a hard cut; hydra_crossfade fades. code is ordinary Hydra JavaScript.

DRY RUN FIRST. With validate=true (the default) the code runs in a hidden second Hydra instance before it touches the live canvas. A misspelled function comes back as a ReferenceError; a broken shader comes back as the GPU's own compile log. Both are refused with live_untouched: true. Fix and call again — don't disable validation to get past an error. validate=false exists for code that loads extensions.

Human-written blocks are refused (error human_block) unless take=true, which you pass only when the person playing asked you to take that block over.

Things that trip people up:

Each output shows one chain: .out() means .out(o0). Four outputs, o0–o3; render(o1) shows one, render() shows all four.
Plain numbers are baked into the shader. For motion, pass a function — () => Math.sin(time) — or an array: [1, 2, 4].fast(0.5).
Feedback is reading an output back into itself: src(o0).
sum() does not compile in hydra-synth 1.4.0. Use add.

Examples: osc(20, 0.1, 0.8).kaleid(4).out() noise(3).modulate(osc(10), 0.2).color(0.9, 0.3, 1).out(o1) src(o0).scale(1.01).rotate(0.01).blend(osc(8), 0.1).out(o0) shape(4, () => 0.3 + a.fft[0] * 0.4).out(o2)

Input Schema

TableJSON Schema

Name	Required	Description	Default
`code`	Yes
`name`	Yes
`take`	No
`validate`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 14, 2026

TDQS

A5/5.0

Behavior5/5

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

Beyond the annotations, the description reveals important behavior: replacement is a hard cut, validation runs in a hidden second instance, errors return live_untouched: true, and human blocks are refused unless explicitly allowed. This gives the agent behavioral expectations that neither annotations nor schema provide.

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 dense but every sentence earns its place: objective first, common failure modes second, and concrete examples last. The structure is easy to scan and fronts the most safety-critical instruction (DRY RUN FIRST).

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?

For a tool with 0% schema description coverage and 4 parameters, the description is remarkably complete. It covers validation, error modes, replacement semantics, output handling, shading gotchas, and provides working examples.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate, and it does thoroughly. It explains name validation rules, what counts as valid code, the semantics and default of validate, and the meaning and allowed case for take.

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 ('Write'), a specific resource ('one named block of Hydra code'), and a clear side effect ('leaving every other block playing'). It also distinguishes itself from the sibling hydra_crossfade by explicitly noting that replacement is a hard cut rather than a fade.

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 gives explicit when-to-use and when-not-to-use guidance: validate=true is the default, validate=false is only for extensions, and human-written blocks are refused unless take=true. It contrasts with hydra_crossfade, making the selection between siblings actionable.

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