sound_selection_apply

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

The annotations already mark the tool as destructive and non-idempotent. The description adds value beyond that by guaranteeing deterministic order and a hard stop on unknown/unverified outcomes, which is useful context. It does not disclose what the stop means (e.g., no partial application), or authorization or rollback behavior, but it adds some meaningful context beyond the raw 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?

A single sentence that immediately states the core action and the critical safety behavior. There is no fluff or redundancy, and the key caveat ('stop on unknown or unverified') is 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 destructive mutation tool with a required authorization flag, the description fails to convey that the tool should be invoked only after a planning step and with an explicit user authorization. It does not mention that the palette argument is a plan, nor the session-fingerprint concurrency requirement. The presence of an output schema reduces the need for return-value documentation, but the operational preconditions are left entirely to the structural schema.

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 71%, the description adds no parameter-level semantics. It does not explain settle_tick_limit or max_navigation_steps, and it doesn't reinforce that the palette must be a validated plan or that session fingerprint is a concurrency guard rather than a durable identity. The schema provides some descriptions, but the description contributes no added value there.

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 clear action: 'apply exact presets in deterministic order' and adds a safety condition 'stop on unknown or unverified outcomes'. It clearly differentiates this from planning (e.g., sound_selection_plan) and feedback recording (sound_selection_record_feedback) by its execution focus, though it doesn't explicitly say 'palette'.

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 no guidance about when this tool should be used in a workflow, or when to prefer sibling tools like sound_selection_plan or sound_selection_get. It does not mention the need for a recent session fingerprint or explicit user authorization, which would help an agent know it is safe to call.

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