Add overlay (light leak / dust / grain)

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

The description lacks detail on behavioral traits beyond the basic operation. It does not disclose whether the overlay overwrites existing clips, whether the track must exist, or any side effects. Annotations only provide openWorldHint: true, which contradicts the schema's additionalProperties: false. The description adds some context (default V2 track, blend mode list), but without readOnlyHint or destructiveHint, the agent needs more clarity on mutability and safety.

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 very concise: two sentences that efficiently convey the primary purpose, default behavior, and a complementary tool. Every word adds value, with no redundancy or filler. The key information is front-loaded, making it easy for an agent to quickly understand the tool's core function.

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 the tool has 6 parameters (1 required) and no output schema, the description covers the main intent and default values but omits details on timing parameters (atSeconds, outSeconds) and behavior when they are absent. The reference to a sibling tool is helpful, but the description does not explain what happens after the overlay is placed (e.g., does it return anything?). It is adequate but not comprehensive.

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 description adds meaning beyond the schema by stating default values for videoTrack (2) and blendMode (screen), and listing common blend modes. It explains the purpose of blend modes for cinematic effects. However, atSeconds and outSeconds lack descriptions in both schema and description, which is a gap. Overall, the description compensates well for the 67% schema 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?

The description clearly states the tool's purpose: placing a media clip as an overlay on a higher video track with a blend mode and opacity. It specifies the resource (overlay media), the action (place), and the context (cinematic use for light leaks, dust, grain). It distinguishes from sibling tools like premiere_add_audio (audio) and premiere_place_clip (standard clip placement) by emphasizing the overlay and blend mode functionality.

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 provides clear context for when to use this tool: for adding overlays with blend modes like light leaks. It also suggests combining with premiere_keyframe for fades. However, it does not explicitly state when not to use it or mention alternatives (e.g., for simpler clip placement use premiere_place_clip). The guidance is good but not exhaustive.

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