Plan Pause Tightening

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile. The description adds meaningful behavior beyond those annotations: it clarifies the output shape (centered removal ranges, keep ranges, savings, apply routes), explicitly states it respects sentence boundaries, and emphasizes it is local-only and never mutates Premiere. This is useful context, though it doesn't go into detail about failure modes or edge cases like overlapping ranges.

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?

Three sentences with no waste. The first sentence states the core function and constraints, the second lists the output categories, and the third covers the safety profile. It avoids repeating parameter details already in the schema. Minor gap: 'apply routes' is a bit terse and could use one short clarifying phrase, but overall it is efficiently structured.

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?

The tool is planning-only with rich input schema (100% coverage) and an output schema, so the description doesn't need to explain return values in depth. It covers the key behavioral constraints (sentence boundaries, local-only, non-destructive) and output categories. The main omission is not explicitly noting that the word_timeline must come from get_clip_transcript_uxp, although that's already in the schema. Given the complexity of the nested word_timeline object, the description could have mentioned prerequisites or that it is a compute-only planning step, but it is still reasonably complete.

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 input schema already provides detailed descriptions for all six parameters (schema description coverage is 100%), covering defaults, bounds, and semantics. The description adds interpretive meaning that goes beyond individual parameter docs: it explains how max_pause_seconds and target_pause_seconds interact (pauses longer than max are shortened down to target), and that target splits evenly around the cut. This adds genuine value without needing to repeat schema field docs.

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 states a specific operation: planning (not executing) the shortening of inter-word pauses, scoped to pauses longer than max_pause_seconds and respecting sentence boundaries. It clearly distinguishes itself from deleting pauses by explicitly saying 'not deleting.' However, it doesn't explicitly differentiate from sibling planning tools like plan_filler_word_removal or plan_silence_review_markers, which also operate on timing/transcript content, so it falls short of full sibling differentiation.

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 implies the tool is for planning pause tightening before any apply step, especially since it names 'apply routes' as part of the return, suggesting a plan-then-apply workflow. However, it does not explicitly state when to prefer this over alternatives like plan_filler_word_removal or plan_silence_review_markers, and it doesn't name a sibling fallback. The 'Local-only; never changes Premiere' line adds a clear usage safety condition, which helps.

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