Plan Client Notes Checklist

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

Beyond the readOnly/idempotent/destructive annotations, the description adds meaningful behavioral traits: 'Local-only and deterministic' and 'never changes Premiere.' It also discloses processing behavior (classification, priority inference, approvals/questions separation) and the exact side-effect-free output, so an agent knows it is safe to call.

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 tightly written, with the main purpose front-loaded, a colon-delimited enumeration of value-add behaviors, and a final safety statement. No sentence is redundant with the schema or annotations.

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 an output schema and fully-documented parameters, the description provides the missing context an agent needs: input intent, processing pipeline, output target, and side-effect guarantees. It is complete for deciding to call and for understanding the result without duplicating the schema.

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 100%: every parameter, including timecode format details for notes, has a rich description. The tool-level description adds useful narrative context around the notes parameter and output, but does not materially deepen the meaning of the other eight parameters, so the baseline of 3 applies.

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 (turn feedback into checklist) and enumerates concrete outputs: timecode finding, classification into audio/color/graphics/etc., priority inference, approval/question separation, and an add_markers_batch payload. This clearly differentiates it from sibling marker-creation tools such as add_markers_batch, which actually modify the sequence.

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?

It clearly frames the input trigger ('pasted client or reviewer feedback') and signals that this is a planning-only step by stating it 'never changes Premiere' and emits a payload for add_markers_batch. It stops short of explicitly naming when to choose this over alternative planning/marker tools, so the guidance is strong but not exhaustive.

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