Sound Extract

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

With no annotations, the description carries the full behavioral burden and does well: it explains cross-correlation alignment, that identical repeats add up while everything else averages down, and that the tool reports consistency. It also clarifies the extracted hit is a target rather than a song part. The main gap is that it does not explicitly say whether a new sound asset is created or where the result is stored, which an agent may need to know before invoking.

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 mechanism and then moves to usage, with no filler sentences. It is dense and long, but every sentence contributes information. Minor density costs it a point rather than a larger penalty.

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 tool is complex and has 11 parameters, but the description explains the core algorithm, alignment behavior, filtering semantics, and the practical source constraint. Since an output schema exists, return values do not need explanation here. Some parameter-level and output-asset details remain missing, but the definition is nearly complete for correct invocation.

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 partially does by defining step as 0-based within the bar in 16ths, which as all|odd|even, every as a multi-bar stride, and bars as [a, b]. However, it leaves several parameters unexplained, including pre_ms, normalize, length_sec, steps_per_bar, name, and project, so the semantic coverage is meaningful but incomplete for 11 parameters.

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 precise verb and resource: build a clean one-shot by averaging every occurrence at a given grid position over specified bars. It also distinguishes itself from adjacent tools by naming analyze_kit's component wav as the source and warning against the full drum stem. An agent can identify exactly what this tool produces without opening the schema.

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 a concrete trigger: use it when a drum sounds dated or generic and the genre's hit is present in a reference. It also gives an explicit exclusion: extract from analyze_kit's component wav, not the full drum stem because that carries the kick. This is strong when-to-use and when-not-to-use guidance.

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