mcp_opendaw_set_note_cents

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so well: it states determinism, mode-specific behaviors (e.g., 'alternating' alternates +cents/-cents, 'gradient' linearly increases cents), the meaning of 'direction', and the return shape ('notes modified, per-mode details, and average cents applied'). The only gap is that it does not mention reversibility/undo implications or any preconditions for this mutation tool, which would be the natural next addition.

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 long but well-structured and justified: a front-loaded one-line summary, an alternative contrast, organized use-case bullets, clearly separated Modes and Args sections, and a return statement. Every section adds necessary value given the tool's complexity and zero schema coverage; it earns its length without being padded.

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 this tool's high complexity (11 parameters, 7 targeting modes, conditional parameter dependencies) and complete absence of annotations and schema descriptions, the description is remarkably complete. It covers purpose, alternatives, use cases, every parameter, every mode's behavior, direction semantics, and expected return content. Nothing essential is left unexplained for an agent to select and invoke this 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 fully compensate, and it does. All 11 parameters receive meaningful explanations with ranges ('-100 to +100'), defaults via schema, and examples ('0,4,8', '60 or C4', '3,7'). The mode-specific semantics of target_pitch, direction, and scale_degree are clarified beyond what the schema titles alone could ever convey.

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 'Set detune (cents) on notes — deterministic microtonal pitch control,' which states a specific verb, resource, and behavior. It explicitly distinguishes itself from sibling humanize_pitch by contrasting deterministic specific offsets with random cents, making selection 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 explicitly names and contrasts the sibling tool humanize_pitch ('Unlike humanize_pitch (random cents)'), providing a clear when-not-to-use signal. It also gives seven specific musical use cases (honky-tonk, quarter-tone scales, maqam, etc.) that illustrate exactly when this tool is appropriate.

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