add_audio_warp_marker

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

Annotations only indicate non-read-only and non-destructive. The description adds valuable behavioral context: 'Live enforces sample bounds, neighbor ordering, and segment BPM limits' and 'Omit sampleTime to preserve playback timing.' These details inform the agent about constraints and side effects beyond the annotations, though it does not mention auth, rate limits, or the exact mutation outcome.

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 concise sentences with no fluff. The main purpose is front-loaded, followed by key behavioral notes. Every sentence earns its place, and the description is appropriately sized for the tool's complexity.

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?

Despite the concise format, the description omits the critical two-step plan/apply workflow: it does not explain that you must first call with dryRun=true to get planHash and confirmationToken, then call with dryRun=false. It also does not mention the importance of expectedStateVersion or how these fields interact. For a mutating tool with 8 parameters and no output schema, this is a significant gap that could lead to incorrect usage.

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 100%, so the schema already documents all parameters. The description adds meaning by explaining that sampleTime is in seconds and that omitting it preserves timing, which is beyond the schema's 'Optional source position in seconds.' It also hints at the plan/apply pattern by mentioning 'Plan or apply,' though it does not detail the dryRun/confirmationToken flow. Overall, it adds marginal value over 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 clearly states the tool's purpose: 'Plan or apply an audio warp anchor.' It names the specific resource (audio warp anchor) and the action (add/apply), and distinguishes it from siblings like move_audio_warp_marker and remove_audio_warp_marker by the term 'anchor' and the plan/apply duality. It also adds specificity with the sampleTime omission behavior, making the purpose unmistakable.

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 by stating it is for adding a warp marker, which contrasts with move/remove siblings, and explains the plan/apply workflow. However, it does not explicitly mention alternatives or provide exclusions (e.g., 'use move_audio_warp_marker for moving existing markers'). The context is clear but not exhaustive.

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