resolve_add_marker_at_playhead

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

No annotations are provided, so the description carries the behavioral burden. It does disclose that the operation creates a marker at a precise playhead and highlights drop-frame timecode support, which is a useful edge-case behavior. However, it does not mention side effects such as duplicate markers, prerequisites like an open timeline, or whether existing markers are affected.

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 a single, focused sentence with the core action front-loaded. 'Including drop-frame timecode support' is a relevant qualifier rather than filler, and there is no unnecessary verbosity.

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 three-parameter mutation with no output schema, the description gives enough to understand the core action, and the drop-frame timecode detail adds useful context. Still, it omits guidance on when to prefer this over resolve_add_marker, and with no annotations, the safety and side-effect profile is left largely to inference.

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 description coverage is 0%, so the description must compensate, but it says nothing about the `name`, `note`, or `color` parameters. The schema's titles and defaults provide some structure, yet the description adds no semantic detail about what these values mean, what format is expected, or why `name` is required.

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 names a specific verb and resource: 'Add a marker at the exact current playhead', which clearly distinguishes it from generic marker tools like resolve_add_marker. The added detail about drop-frame timecode support further narrows the purpose. An agent can understand exactly what this tool does without reading the 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?

The phrase 'at the exact current playhead' provides clear contextual guidance: use this tool when a marker should be placed precisely where the playhead is now. It does not explicitly contrast with resolve_add_marker or state when not to use it, though the playhead-specific framing strongly implies that distinction.

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