Plan Chapter Markers

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description's 'Local-only plan; never changes Premiere' largely restates readOnlyHint, though it usefully confirms the call has no Premiere side effects. It does not disclose failure modes (e.g., transcript revision mismatch, word-ordering violations) that the schema hints at but does not fully explain behaviorally.

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?

Two sentences, front-loaded with the core action and output, ending with the key non-mutation guarantee. No filler; every clause carries information an agent needs.

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?

With an output schema present, the description need not enumerate return values, yet it still names the three outputs (chapters, youtube_timestamps, add_marker-ready markers), which is helpful. Given 7 params (1 required), nested objects, and full schema coverage, the definition is adequate; the only real gap is behavioral detail on input validation failures.

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%, so the baseline is 3. The description gestures at titling via 'distinctive tokens' (mapping loosely to stop_words/title_words) and at transcript input via 'word-timed transcript', but adds no syntax, format, or default-value guidance beyond what the schema already documents for all 7 parameters.

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 (Plan), resource (YouTube-style chapters), the input required (word-timed transcript), and the method (local TextTiling-lite topic-shift detection). It also names the downstream artifact ('add_marker-ready Chapter markers'), which separates it from siblings like add_markers_batch that actually write markers. An agent can pick this over the many other plan_* tools without opening a 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 description makes the trigger condition clear (you must have a word-timed transcript), and 'Local-only plan; never changes Premiere' tells the agent this is a dry-run/preview step whose output feeds add_marker or add_markers_batch. It does not explicitly state exclusions (e.g., when to prefer plan_beat_montage or a different chaptering approach), so it stops short of a 5.

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