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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds substantial behavioral detail: it locks captions to a position when explicit, removes old shot-aware placement, explains dynamic as 'legacy karaoke without a preset', and notes that single_line overrides preset stacking. It also warns about the error when no captions exist. This goes well beyond the annotations and gives the agent a full picture of side effects.

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 long but every sentence carries unique value—no filler. It is front-loaded with scope and primary function, then branches into examples and edge cases. While dense, the complexity of the tool (many style parameters) justifies the length. It could arguably be tightened, but the structure remains effective and scannable.

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's complexity (nested style object, many optional fields) and lack of output schema, the description is remarkably complete. It covers usage, side effects, parameter semantics, error conditions, and points to related tools. An agent has everything needed to decide when and how to invoke it correctly.

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 coverage is 50%, but the description compensates richly. It explains the meaning of key fields: style.preset with the preset menu, highlight_color, uppercase, emphasis_words, size_scale (with range and example), single_line, and how position locks behavior. It also clarifies that emphasis_words is a top-level argument and describes the effect of dynamic. This adds significant semantic value beyond the raw schema.

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 opens with a clear statement of scope ('PROJECT-SCOPED'), the specific action ('Change how existing captions LOOK'), and what it does NOT do ('without touching their text or timing'). It distinguishes itself from add_captions by referencing its preset menu and from other caption tools. The verb+resource combination is unambiguous and an agent can immediately tell this tool modifies visual styling rather than content.

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 explicitly tells when to use it (change appearance, lock position, fine-tune size) and when not (text/timing). It points to add_captions for the preset menu and mentions the error case when no captions exist. It also clarifies that it works for from_transcript and manual captions, giving clear context for selection among siblings.

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