mcp_opendaw_set_time_stretch_cents

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

With no annotations, the description carries the burden and does well: it discloses clamping ('Range: -1200 to +1200 cents (clamped)'), the need for prior time-stretch creation, and the return value ('Returns new playback rate and cents, or error'). It doesn't mention reversibility or side effects beyond the set operation, but the core behavior is transparent.

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 tightly organized: a one-sentence purpose, a units/range sentence, a prerequisite line, a labeled parameter list, and a return-value line. No wasted words; every sentence adds value and key details are front-loaded.

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 4-parameter mutating tool with no annotations, the description covers purpose, prerequisite, parameter semantics, range, and return value. It could go deeper on error scenarios (e.g., what exactly fails) or whether prior values are overwritten, but these are minor gaps. The presence of an output schema (not shown) likely covers return formatting details.

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 provides no description coverage, so the description fully compensates by explaining each parameter: 'unit_index: AU index', 'track_index: Track index within the AU', 'region_index: Audio region index', and 'cents: Pitch shift in cents (-1200 to +1200)'. This adds critical meaning well beyond the bare schema types.

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 ('Set the pitch shift') and identifies the target resource ('time-stretched audio region'), distinguishing it from siblings like set_note_cents or create_pitch_stretched_region. The phrase 'pitch shift (in cents)' is precise and semantically clear.

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 states a prerequisite ('Only works on time-stretched regions') and references the creating tool ('created with create_time_stretched_region'), which indirectly warns against using it on other region types. It also gives the valid range and clamping behavior. However, it does not name specific alternative tools for non-time-stretched regions, so it stops short of full comparative guidance.

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