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

Beyond the sparse annotations (readOnlyHint=false, destructiveHint=false), the description discloses significant behavioral traits: enable=true reloads the deck page with ?audio=1, the piece is replayed, a.fft reads zeros until the user clicks Allow, and video out must be restarted after reload. It also exposes the non-obvious read-once freezing of parameter values outside a function. This is exactly the kind of side-effect context annotations cannot express.

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

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

The structure is exemplary: a one-line purpose up front, the no-argument behavior, a compact parameter list where each line is name + semantic, then a single-sentence caveat with a one-line code example. Despite covering six parameters and a complex reload flow, there is no filler — every sentence earns its place.

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

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

The definition covers the no-argument diagnostics behavior, all parameter semantics, the full side-effect chain of enable (reload, replay, permission prompt, video-out restart), and the in-function placement requirement — sufficient for correct invocation of a moderately complex tool. Minor gaps remain around failure modes (e.g., behavior when mic permission is permanently denied) and how state propagates to siblings like hydra_video_out, though the existing output schema covers return values.

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

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

Schema description coverage is 0%, so the description carries the full burden — and it succeeds. All six parameters (bins, smooth, cutoff, scale, show, enable) are individually defined with ranges, defaults, and behavioral effects: e.g., 'bins number of frequency bands in a.fft (1–64; default 4)' and 'smooth 0–1: how slowly band values fall (higher = smoother).' This fully compensates for the empty schema descriptions.

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

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

The opening line, 'Check and tune audio reactivity (Hydra's `a` object), or switch it on,' names a specific scope of actions (check, tune, switch on) on a specific resource (Hydra's `a` audio object). This clearly separates it from siblings like hydra_source (video sources) and hydra_transport (time controls), so an agent can discriminate the tool without opening other definitions.

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

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

The description gives substantial usage context: the no-argument call is framed as a diagnostics path, enable=true is explained as a reload that replays the piece and re-asks for mic permission, and the critical placement caveat ('use it in code inside a function, or it is read once and frozen') tells an agent when parameter changes take effect. However, it never explicitly names sibling alternatives or states when NOT to use this tool, stopping short of a full 5.

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

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.

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.

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.

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.

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.

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.

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

The description discloses the full internal flow: dry-run of new code, copy into a spare output, old chain continuing, a third output blending old and new, and finally switching the visible output and blanking borrowed outputs. It also explains blocking behavior ('The call returns when the fade has finished') and the refusal behavior with `no_spare_outputs`. This goes far beyond the annotations and gives the agent a precise mental model of side effects and safety.

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

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

The description is well-structured with labeled sections: a one-sentence purpose, a 'How' paragraph, a 'Needs' paragraph, and an example. Every sentence adds useful information, and the example is compact but illustrative. It is longer than average, but the complexity of the operation justifies the length; nothing feels redundant.

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

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

The description covers the tool's purpose, mechanics, prerequisites, error behavior, return behavior, and gives a working example, which is impressive for a complex operation. The only notable gap is that `take` and `validate` are not explained, leaving an agent uncertain about two parameters. Since an output schema exists, the lack of return-value detail is acceptable, but the missing parameter context keeps this from a perfect score.

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

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. It does add meaning for `seconds` by giving the allowed range '0.5–30' and demonstrates `name`, `code`, and `seconds` through the example. However, `take` and `validate` are never explained, leaving two of the five parameters semantically opaque. The description partially compensates for the empty schema but is not complete.

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

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

The description opens by comparing itself to hydra_block: 'Like hydra_block, but fade from what is on screen to the new code over seconds instead of cutting', which clearly states the verb, resource, and behavior. It also names the intended context, 'the move for a big change mid-set,' and differentiates from the sibling tool by contrasting fade vs. cut. An agent can confidently distinguish hydra_crossfade from hydra_block and other siblings.

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

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

The description explicitly frames when to use it: for a 'big change mid-set' when you want to fade rather than cut, and later notes that 'mirrors cut instead of fading.' It also provides concrete prerequisites: 'one visible output (not the 4-up grid), and two outputs that no other block draws into or reads,' plus the failure mode if those conditions are not met. This is clear, actionable guidance beyond anything in the schema or title.

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

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

The description discloses key behaviors beyond the annotations: it compiles the GLSL in a throwaway chain so errors surface as the compiler's own errors, and on success it stores the function as a block 'fn_<name>' at the top of the document for persistence across reloads. These details are not present in the annotations (which only flag readOnlyHint=false and destructiveHint=false) and are essential for the agent to predict side effects and failure modes.

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

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

The description is well-structured and front-loaded: it opens with the purpose, then provides a clear list of function types, explains parameter semantics, describes error and storage behavior, and ends with a concrete example. Every sentence contributes useful information, and the formatting with code blocks improves readability. It is appropriately sized for the complexity of the tool.

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

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

For a tool with this complexity (GLSL, multiple types, inputs, compilation, persistence), the description is nearly complete. It covers the core semantics, error handling, and storage. The only notable gap is the undocumented 'take' parameter, which could affect usage. An output schema is present, so return values are presumably covered there. Overall, an agent can call this tool correctly with the provided information, but the missing 'take' prevents a perfect score.

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

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. It thoroughly explains 'type' with a list of valid values and their behavior, 'glsl' as the body only, and 'inputs' with format and example. However, the 'take' parameter is not mentioned at all, leaving its semantics undocumented. The description adds significant meaning for most parameters but misses one, so it does not fully cover the schema gap.

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

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

The description states a specific action: 'Add a custom transform written in GLSL (Hydra's setFunction), usable in any chain afterwards like a built-in.' It clearly identifies the resource (a custom GLSL transform) and distinguishes it from sibling tools that handle other operations. The purpose is unambiguous and specific.

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

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

The description provides strong usage context: it explains the available function types (src, coord, color, combine, combineCoord) with their input/output contracts, and includes a complete example. It does not explicitly state when *not* to use it or name alternatives, but the sibling list and the unique nature of defining custom functions make the intended use clear. The example demonstrates exactly how to call it in a chain, which is effective guidance.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context by explaining what the returned document contains, that tab_editor is the authoritative editor text including hand-typed content, and that outputs o0–o3 may already be occupied. 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.

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

The description is concise at roughly 75 words and front-loads the core resource definition before adding usage context. Every sentence contributes: the composition structure, the tab_editor truth, and the instruction to read before writing.

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

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

Given the tool has no parameters, a read-only annotation, and an output schema, the description is nearly complete. It explains the document shape, the authoritative editor content, and the practical reason to call it. It could be slightly more explicit about what happens when there is no existing tab or primary, but this is a minor gap.

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

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

The tool has zero parameters, so the schema carries no burden and the description does not need to explain parameter semantics. Per the zero-parameter baseline, this is adequate since there is nothing to clarify.

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

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

The description clearly identifies the tool's resource as the shared composition: ordered named blocks with code, author, and block separators, plus the truth of the tab_editor when applicable. It implies retrieval through 'Read this before writing' and the annotation title 'Read The Composition', but it never uses an explicit verb like 'get' or 'return' and does not contrast itself with sibling tools.

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

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

The description gives explicit context for when to use the tool: 'Read this before writing, so you extend the piece instead of talking over it — and so you can see which outputs (o0–o3) are already taken.' This is clear usage guidance, though it does not name alternatives or explicitly state when not to use the tool.

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

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

Beyond the annotations' destructiveHint=true and readOnlyHint=false, the description explains a subtle Hydra behavior—outputs keep showing their last frame—and why blanking is necessary. It also discloses that the code is gone afterwards and describes the returned blanked and restored semantics. This is substantial behavioral context the structured annotations alone would not convey.

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

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

The description is dense but every sentence earns its place: it states the core action, explains the persistence rationale, defines the return values, and warns about destructiveness. The structure front-loads the main purpose and uses a dash to add essential context without padding.

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

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

For a destructive, non-read-only tool with only two parameters and an output schema, the description is fully adequate. It covers why blanking happens, what restored means, the take flag requirement, and the irreversible code loss. An agent has enough information to invoke it correctly and handle side effects.

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

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

With schema description coverage at 0%, the description takes on the burden of explaining parameters. It clearly defines take: 'Human-written blocks need take=true.' The name parameter is not explicitly described but is self-evident from context as the block to remove, so the gap is minor.

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

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

The description opens with a specific verb and resource: 'Remove one block from the composition,' then clarifies the consequential behavior of blanking outputs. This cleanly distinguishes the action from sibling tools like hydra_save or hydra_hush by stating exactly what gets removed and what happens to the screen.

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

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

It gives clear operational guidance: human-written blocks need take=true, and hydra_save should be called first if the code might be needed again. It does not explicitly enumerate when-not-to-use alternatives, but the save-first warning and the destruction warning provide enough contextual guardrails for an agent to decide safely.

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

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

Annotations already declare destructiveHint=true, and the description reinforces the destructiveness by detailing what gets destroyed (all blocks, human-written ones, in every tab) and the archival safety net. It adds context on the archive behavior and the black screen, which is valuable beyond the annotation.

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

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

The description is concise, with a strong opening metaphor, followed by essential details about archiving and the alternative approach. Every sentence adds value, and the structure frontloads the critical destructive nature.

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

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

Given the zero parameters, the destructive scope is well-explained, and the archival behavior is disclosed. The output schema exists, so return values are covered. The only minor gap is not detailing what exactly the 'archived' path is used for, but it's not critical. Overall, complete for the tool's complexity.

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

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

The tool has zero parameters)Skip, so the description doesn't need to document any. It implicitly communicates that no parameters are required, which is sufficient. The coverage is 100% and there are no params to explain, so a baseline of 4 is appropriate.

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

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

The description is highly specific: it names the tool as a 'panic button' that blanks every output, clears update(), resets speed, and empties the entire document including human-written blocks across all tabs. It clearly distinguishes this from hydra_drop or hydra_block by emphasizing the global scope and inclusion of human content.

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

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

The description implies when to use it (as an emergency reset) and explicitly states that to change only one part, one should replace that block instead. It does not explicitly name alternative tools, but the guidance is clear enough to prevent misuse.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description doesn't contradict them nastead it adds valuable context: the refusal condition (human-written blocks unless take=true), the warning to save first, and the dry run/hush behavior. It also mentions that unknown names return a list of saved sketches, which is beyond the annotation coverage. This adds meaningful behavioral detail 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.

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

There are only four sentences, each carrying substantial information: the main action, the refusal condition, a caution to save, and behavior on unknown names. The description is front-loaded with the core purpose and then essential safety/edge-case info. No unnecessary fluff.

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

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

The description covers main purpose, refusal condition, safety tip, and edge case return. However, it doesn't describe the return value for successful loads or the content of the returned list for unknown names dozen. Given the output schema exists, the description needn't detail return values, but more clarity on the refusal outcome (does it error or return a message?) would complete the picture. Still, for a 3-param tool with annotations covering safety, it's reasonably complete.

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

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

Schema description coverage is 0%, meaning the schema provides no descriptions for any of the parameters. The description mentions 'take' in the context of overriding human-written blocks, and 'name' is implied, but 'validate' is not addressed at all. With zero coverage, the description should explain all parameters, especially 'validate' which has a default and is not self-explanatory.

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

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

The description clearly states the action (replace composition with a saved sketch) and the specific resource (saved sketch). It also mentions key behaviors like dry run, hush, and keeping author, which helps distinguish it from similar tools like hydra_sketch, though it doesn't explicitly name all siblings that might overlap.

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

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

It provides explicit conditions for when to use the tool (replacing composition with saved sketch, similar to hydra_sketch) and when it will be refused (if human-written blocks exist unless take=true). It also advises to save the current piece first if worth keeping, but doesn't explicitly mention alternatives beyond the implied hydra_sketch.

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

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

With readOnlyHint and destructiveHint annotations, the description goes beyond by explaining that it only reveals what render() shows (one output or a 4-up grid) and that hidden tabs cannot be captured. This adds valuable behavioral context 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.

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

The description is concise and well-structured, with the core purpose in the first line and essential usage guidance in subsequent sentences. Every sentence adds value, and the information is front-loaded for quick scanning.

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

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

The description is complete for a simple single-parameter tool. It covers what the tool does, when to use it, limitations, and parameter specifics. The output (a screenshot) is self-evident, so no output schema is needed.

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

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

The schema has no description for the max_width parameter, but the description explains it's a downscale target in pixels with a 64–1920 range. This compensates perfectly for the 0% schema coverage, giving the agent full understanding of the parameter's purpose and constraints.

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

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

The description precisely states the tool captures a screenshot of the primary tab's canvas, downscaled to a specified width. It clearly distinguishes this from other hydra tools (which are about rendering, state, or source management) by focusing on visual evidence capture.

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

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

The description explicitly instructs when to use it: 'look after writing and before describing anything,' and explains why it's necessary (a block can be black, blown out, or static). It doesn't name alternative tools, but the context of when to use it is clear. It also notes limitations with hidden tabs, which guides appropriate usage.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses that the listing is read live from the running engine, includes setFunction additions, and supports fuzzy matching for name lookups. It also documents grouping behavior and the type taxonomy. No statement contradicts 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.

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

The description is front-loaded with the core behavior and usage modes, then uses compact bullets for the type taxonomy and closes with a practical precaution. Despite its length, every line contributes a distinct fact or example and avoids filler.

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

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

For a two-optional-parameter read-only reference with an output schema, the description covers invocation modes, parameter semantics, valid type values, and example queries. It even warns about the consequence of an invented function. Nothing material is missing for an agent to call it correctly.

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

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

Schema coverage is 0%, but the description fully compensates: it defines name as a function lookup returning inputs and defaults, notes fuzzy matching, and defines type as a filter returning every function of one type, enumerating the valid type values. This is far more useful than the bare string properties in the schema.

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

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

The description opens with a concrete verb and resource: it reads Hydra's transform functions live from the running engine and lists them, making it a lookup tool rather than a mutation tool. The title annotation 'Look Up A Function' and the modal breakdown (no arguments, name, type) further distinguish it from sibling tools like hydra_define or hydra_drop.

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

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

It explicitly says to check a name here before using an unverified function and contrasts this with the dry run, calling it 'cheaper'. The bullet list gives clear when-to-use modes for no arguments, name, and type. This gives an agent both the condition and the comparison needed to select the tool.

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

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

Beyond the annotations, the description discloses crucial runtime behavior: all outputs keep rendering regardless of visibility, so chains can still feed hidden outputs. It also states clearly that the tool does not change the document, which is important for an operation where readOnlyHint is false and destructiveHint is false. This prevents the agent from assuming the choice persists.

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

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

Three compact sentences deliver the action, parameter values, runtime implications, and the permanence boundary with zero filler. The most important information appears first, and the example of chaining o1 to o0 earns its place by illustrating why continued rendering matters.

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

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

For a single-parameter display tool, the description is complete: every accepted value, the behavioral nuance of continued rendering, and the distinction between transient and permanent are all covered. The presence of an output schema means return-value details need not be restated in the description.

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

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

The input schema provides only a bare `output` string with no enum and no description (0% coverage), so the description carries the full burden. It fully compensates by listing every valid value and explaining the visual result for each, including the "all" grid case. This is exactly what the schema lacks.

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

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

The description opens with a specific action and target: showing an output full-screen or all four outputs in a grid. It enumerates the exact accepted values ("o0", "o1", "o2", "o3", "all"), which distinguishes this display-routing tool from the broader hydra sibling set. Nothing about it is vague or tautological.

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

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

The description gives clear when-to-use context: this is for choosing what is visible while rendering continues, not for making a permanent document change. It explicitly names the alternative path for permanence by writing `render(o1)` in a block, which tells the agent when this transient tool is appropriate versus a persistent block-based approach.

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

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

The description discloses concrete behaviors beyond annotations: the exact file destination, the inclusion of every block with its author, the 480-px thumbnail, naming constraints, and the guard that an existing name is refused unless overwrite=true. This is rich, accurate behavioral context and does not contradict 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.

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

Three dense sentences cover the main behavior, constraints, and examples without waste. The most important action is front-loaded, and the details about naming and overwrite earn their place.

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

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

For a save operation with an output schema available, the description is complete: it states what is saved, where, how naming works, how tags work, and how overwriting is handled. Nothing an agent needs to invoke the tool correctly is missing.

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

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

Schema coverage is 0%, so the description fully compensates. It explains name character rules and length, the purpose of tags with examples, and the overwrite behavior explicitly. Each of the three parameters is given meaningful semantics beyond the raw schema.

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

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

The description states a specific action and resource: 'Save the current composition — every block, with its author — to the sketch library (hydra-mcp/sketches/<name>.json), plus a 480-px thumbnail.' This is far more specific than the title and clearly distinguishes saving from sibling operations like hydra_load or hydra_sketches.

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

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

The description clearly implies the tool is used to persist the current sketch, but it does not explicitly explain when to choose it over alternatives such as hydra_load, hydra_sketches, or hydra_share_url. There are no exclusions or alternative conditions, only the implied save-vs-load distinction.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds valuable behavioral context: the code is embedded in the link (base64 of URI-encoded code), nothing is uploaded, and very long pieces produce very long links. This goes beyond the annotations and helps the agent understand side effects and constraints.

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

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

The description is concise and well-structured. It front-loads the core purpose in the first sentence, then provides necessary technical details (base64 format, verification) and a key constraint (nothing uploaded, long links) in a compact second paragraph. Every sentence adds value without redundancy.

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

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

Given the tool has no parameters and an output schema exists, the description covers the essential context: what the link contains, how it's built, and what it does NOT do (upload to gallery). The only minor gap is that it doesn't explicitly describe the output format (the link itself), but the output schema likely covers that, and the description's mention of 'link' is sufficient.

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

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

The tool has zero parameters, so the schema provides no parameter semantics. The description compensates by explaining what the tool does with the current document/editor state, which is the implicit input. Since there are no parameters to document, the description's explanation of the implicit input (current piece/editor text) is sufficient.

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

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

The description clearly states the tool's purpose: it creates a hydra.ojack.xyz link that opens the current piece in the official Hydra editor. It specifies the resource (Hydra editor link), the action (share/open), and distinguishes it from gallery uploads. The title 'Share Link' and sibling context further reinforce this.

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

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

The description explains when this tool is used: to share the current piece via a link, and explicitly notes that nothing is uploaded to the gallery. It also mentions that when the primary is an existing Hydra tab, its own editor text is used. However, it doesn't explicitly name alternative tools or state when NOT to use this tool, though the gallery-upload exclusion is a useful contrast.

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

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

Annotations already flag destructiveness, and the description adds valuable behavior beyond that: the tool is refused for human-written blocks to prevent erasure, it dry-runs, hushes, then runs, and it replaces the entire composition. This is exactly the kind of consequence disclosure an agent needs before invoking a destructive tool. 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.

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

The description is longer than average but every sentence earns its place: action, sibling distinction, block syntax with example, fallback behavior, refusal rationale, and override condition. It is front-loaded with the core action and does not pad with filler.

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

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

For a destructive, complex tool with many siblings, the description is remarkably complete: purpose, alternatives, block conventions, refusal semantics, and take override are all covered. The only notable gap is the undocumented `validate` parameter; otherwise an agent has enough context to call and interpret the tool correctly.

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

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

Schema description coverage is 0%, so the description must carry the load. It richly explains `code` with a concrete block-marker example and explains `take` with a clear policy. However, the `validate` parameter is never mentioned, and although 'dry-run all of it' hints at it, the agent is left guessing whether validate can be disabled and what that does.

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

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

The description opens with a strong verb and resource: 'Replace the entire composition with a new sketch'. It makes the tool's scope unmistakable ('start a fresh idea, not to add to one') and explicitly contrasts it with hydra_block. An agent can distinguish this tool from its siblings without reading schemas.

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

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

Usage is explicitly stated: use to start fresh, do not use to add, and use hydra_block instead for additions. The refusal condition (human-written blocks) and the exact condition for passing take=true ('only if the person playing asked for a fresh start') are also given, leaving little to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds the query filtering behavior and the kind of content returned, but does not disclose extra behavioral details such as pagination, ordering, or access requirements.

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

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

Two short sentences front-load the core purpose and returned fields, then clarify the filter. There is no filler or repetition of the schema.

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

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

This is a simple read-only list tool with one optional parameter and an output schema. The description covers what the tool lists and how the query affects results; nothing essential is missing for invoking it correctly.

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

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

The input schema gives only the parameter name and default, with 0% schema description coverage. The description compensates by explicitly explaining that `query` filters by a word in the name or tags, which is meaningful semantic guidance.

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

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

The description starts with a specific verb and resource: 'List saved sketches', and then enumerates the returned fields (name, tags, when saved, block names, thumbnail path). This clearly distinguishes it from siblings like hydra_sketch, hydra_save, and hydra_load.

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

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

The description implies usage for browsing or listing saved sketches and explains the optional query filter. It does not explicitly name sibling alternatives or state when not to use it, so it misses full exclusion guidance.

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

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

The description goes well beyond the annotations: it discloses that the tool is not read-only (it loads streams and can prompt for permissions), details the return state ('live', 'pending_permission', errors), specifies a four-second timeout, and explains mirror behavior (images/videos load on mirrors; cameras/screen do not). This adds significant behavioral context that annotations do not provide. It fully informs the agent about side effects, such as permission prompts, which is critical for correct usage.

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

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

The description is detailed, which is necessary given the tool's complexity)Skip. It front-loads the key action ('Load an external image stream... src(s0)') and then organizes kind-specific details in a clear list. It does include a redundant example chain at the end ('Then: src(s0).kaleid(4).out(o1)') that largely repeats the opening usage pattern, adding little value-laden content. Overall it is structured and readable, but the trailing example slightly bloats it without new information.

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

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

Given the tool's complexity (multiple kinds, permission prompts, CORS constraints) and the minimal schema (3 params, 2 required, no enums), the description is remarkably complete. It covers all critical behaviors: return states, timeouts, mirror limitations, error scenarios, and usage patterns. The output schema exists, so return details are partly covered, but the description still explains the state values. There are no significant gaps that would prevent an agent from using the tool correctly.

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

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

The input schema is minimal (only names: kind, slot, target) with 0% description coverage. The description compensates by explaining the kind values ('image', 'video', 'cam', 'screen', 'clear') and their target formats (URL, camera index, or empty for clear). However, it does not explicitly explain the 'slot' parameter semantics beyond the s0–s3 reference in the opening line, and 'target' is explained mainly through kind. Since kind and target are well-clarified, but slot is thinner, it scores a 4 rather than 5.

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

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

The description opens with a clear, specific statement: 'Load an external image stream into s0–s3, then read it in any chain with src(s0).' This names the exact resource (external image stream), the slot mechanism (s0–s3), and the usage pattern (src(s0)), distinguishing it from generic load tools. It also enumerates the kind field with concrete targets ('image', 'video', 'cam', 'screen', 'clear'), which makes the purpose unmistakable. It clearly differentiates from siblings like hydra_load by focusing on source slots and stream loading.

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

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

The description provides explicit usage guidance per kind, stating when to use each (e.g., for 'screen', it notes browsers require a click, so remote calls likely fail; for 'cam', it warns to expect pending_permission and check hydra_state rather than assuming). It also explains the CORS requirement for image and video, which is a critical condition. While it doesn't name sibling alternatives, it gives concrete operational constraints that help an agent decide when to call this function and how to handle outcomes. This is more actionable than typical sibling-based exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial non-obvious behavior beyond that: visible=false means the browser throttles frames and screenshots may be stale; mic='prompt' means audio-reactive code reads zeros until permission is granted. It also clarifies role semantics ('exactly one primary answers; mirrors just follow'). This is exactly the kind of transparency that prevents misinterpretation.

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

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

The description is efficiently structured: a one-sentence purpose, a compact summary of returned fields, then two field-specific warnings that earn their length because they materially affect how an agent should act. No sentence is filler, and the most decision-relevant caveats are highlighted.

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

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

Given zero parameters, an existing output schema, and read-only annotations, the description covers everything needed to invoke and interpret the tool correctly. It explains non-schema behavioral edge cases (tab throttling, mic prompt) and gives concrete course-of-action guidance, so no critical context is missing.

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

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

The tool takes zero parameters and the schema is empty, so there is no parameter burden for the description to carry. The baseline for zero-parameter tools is 4, and the description appropriately focuses on output semantics rather than inventing parameter-related details.

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

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

The description opens with a specific, actionable purpose: 'Which Hydra tabs are connected and whether they can be trusted right now.' It then enumerates exactly what is returned (role, adapter, fps, resolution, sources, blocks, warnings), making the tool's resource and scope unmistakable. It also clearly differentiates itself from mutation-oriented siblings by focusing on read-only state inspection.

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

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

The description gives clear context for when this tool matters — checking current trustworthiness, background-tab visibility, and mic permission. It also provides explicit behavioral guidance: 'Ask for it to be brought to the front rather than working blind' and 'Never assume the click happened.' It does not explicitly name alternative tools or exclusions, but the context is strong enough for safe selection.

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

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

The description discloses a critical side effect beyond the annotations: 'This changes the whole piece, human-written blocks included — say so if someone is playing along.' It also reveals performance implications ('Larger costs fps') and that video out sends the set size. These traits are not encoded in the annotations and substantially inform the agent's use.

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

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

The first sentence states purpose immediately, followed by a parameter list and a high-value global caveat. No redundant filler; each line contributes semantic or behavioral information that the schema and annotations do not provide.

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

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

Given the presence of an output schema and simple optional parameters, the description is complete: it covers all parameter semantics, global side effects, practical limits, and collaborative etiquette. An agent has everything needed to select and invoke the tool correctly without further inference.

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

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

Input schema has 0% description coverage, so the description carries full parameter burden. It does so thoroughly: speed's multiplier meaning and range, bpm's beat-stepping behavior with an example, and width/height's range and linked setting are all explained. Every parameter gains meaning absent from the schema.

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

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

Description opens with a specific verb and resource: 'Set the global clock and canvas size.' The four parameters are enumerated with concrete meanings, making the tool's scope unmistakable and distinct from render/output siblings. No ambiguity about what resource is being modified.

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

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

The instruction 'Pass only what you want to change' gives a clear usage pattern)Skip. The caveat about changing 'the whole piece, human-written blocks included' implies collaborative contexts. However, the description does not explicitly compare against sibling tools or state when not to use it, so the routing guidance remains implicit.

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

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

Beyond annotation's readOnlyHint=false, the description details the start/stop/status behavior, the two-second wait, the returned end-point objects, the fact that frames are dropped rather than queued when the receiver lags, and the consequence for a hidden tab. It also warns that plain 'Hydra' matches nothing in TouchDesigner, which is highly valuable behavioral insight not discoverable from annotations.

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

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

The text is organized into a flow from purpose to receiver integration to parameter semantics, prereqs, and returned values. It is somewhat dense but every sentence conveys operational knowledge. It is not as tight as a two-sentence definition but it earns its length with whole paragraphs containing non-redundant detail.

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

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

Given the simplicity of the schema and the lack of a clear output schema in the provided, the description is complete: it covers prerequisites, action semantics, fps meaning, output values, receiver behavior, failure modes, and a workaround (lower hydra_transport resolution/fps). The agent can call and interpret the result correctly without additional information.

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

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

Schema coverage is 0%, so the description carries the full burden of parameter explanation. It defines 'action' with allowed values start/stop/status and 'fps' with a 1–60 range and the meaning of the capture rate. It also tells the agent to report the returned fps rather than the requested fps, adding behavioral semantics to a parameter that otherwise has none in the schema.

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

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

The description opens with a specific verb and resource: 'Send the primary tab's canvas out of the browser as a native video source...' It clearly distinguishes itself by describing Syphon and NDI output, which none of the sibling tools (hydra_source, hydra_render, etc.) imply. The exact in-tool destination and the reason to pick 'Python:Hydra' over 'Hydra' makes the purpose unambiguous.

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

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

The description gives strong usage context: the external out/hydra_out.py must be running, Chromium is the only supported tab type, and the primary tab must remain visible (a hidden tab stops producing frames). It does not explicitly name alternatives or say when not to use it in favor of a sibling, but the prerequisites and operational constraints are clear enough to guide an agent correctly.

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