delete_clip

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

With no annotations provided, the description must fully disclose behavioral traits. It merely states the action without mentioning irreversibility, permissions, effect on playback, or undo behavior. For a destructive tool, this is a significant gap; the agent cannot know the consequences of invoking it.

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 extremely concise: a one-sentence purpose followed by parameter definitions. Every word earns its place, and the front-loaded purpose allows quick understanding. No filler or redundancy.

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 simple two-parameter delete tool, the description covers the core purpose and parameter semantics. An output schema likely exists (as indicated in context), so return values need not be described. However, lacking annotations, it omits any context about side effects or when this action is appropriate, which leaves the description minimally complete but not strong.

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 only integer titles with 0% description coverage, but the description’s Args section explicitly defines both parameters as zero-based indexes. This adds meaningful semantics beyond the schema, enabling correct invocation. Slightly more detail (e.g., ranges) could improve it, but it already compensates well.

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 'Delete a clip from a clip slot' uses a specific verb ('delete') and a precise resource ('clip slot'), clearly distinguishing it from sibling tools like delete_arrangement_clip or delete_track. It conveys both the action and the target context unambiguously.

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 explicit guidance on when to use this tool versus alternatives such as delete_arrangement_clip or stop_clip. While the phrase 'clip slot' implies session view usage, it does not state exclusions or mention prerequisites, leaving the agent to infer the appropriate context.

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