create_clip_automation

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

No annotations are provided, so the description carries the full burden and does so well. It discloses the destructive side effect ('clears and rewrites one clip envelope in one Live undo step'), the API prerequisite, a hard limit (max 500 points), error behavior (AMBIGUOUS_MATCH) with a recovery path (device_index), and semantic gotcha (stepped envelopes).

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?

Front-loads purpose in one line, then labels blocks 'Side effects:', 'Example:', 'Edge cases:'. Every sentence is load-bearing — no restated name, no filler.

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 5-param mutation tool with zero annotations, no output schema, and 0% schema coverage, the description supplies side effects, limits, errors, an example, and alternative routing. Only the return/response behavior is unspecified, which is a minor gap for a mutating write tool.

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 0%, so the description must compensate, and it largely does: it explains device_index's role (disambiguating a parameter name shared across devices), the automation_points format via a concrete example ({"time", "value"}), and the 500-point cap. track_index and clip_index are only shown positionally in the example, not explained, so it falls short of full coverage.

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?

States a specific verb and resource: 'Replace one Session clip parameter envelope with verified breakpoints.' The scope (one clip, one parameter, Session clip) is precise and lets an agent distinguish it from the sibling create_clip_automation_curve without opening either 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?

Explicitly routes to the alternative for a concrete case: 'Envelopes are stepped, so a smooth ramp needs dense points — or use create_clip_automation_curve.' It also flags the Session-clip context requirement. It stops short of a full when-to-use vs when-not comparison across all automation siblings, but the key alternative is named with its selecting condition.

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