setCaptionSettings

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

Annotations only cover the safety profile (not read-only, not destructive, closed world); the description instead supplies the non-obvious behavior: field precedence (style first, then plate, then any explicit field wins), the plate-driven recolour side effect, lane fallback with resolvedLane to detect it, and that enabled captions are burnt into the export. This is exactly the context annotations cannot carry.

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?

Front-loaded with the action and the precedence rule, and every clause carries information rather than filler. It is a single dense block for 17 parameters, though, and prose is doing work that a short structured list would do more scannably.

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?

No output schema exists, and the description still volunteers the one interesting return signal (resolvedLane) plus the export side effect. Given 17 parameters, zero required fields, and a mutation with no destructive annotation, the agent has everything needed to call 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 description coverage is 6%, so the description carries nearly the whole burden and does: ranges and units for insetX/insetY, fontSize, plateOpacity, min/maxWordsPerLine, hex format for color, what each anchor does, the rule that insetX is ignored when anchorH is centred, and what language/lane select. Only projectId/fontFamily/fontWeight are left to the schema, and fontFamily/fontWeight are folded into the 'style' explanation.

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?

Opens with a specific verb pair ('turn the captions on or off') plus the styling/positioning scope, and anchors it to a concrete mental model ('as the editor's Captions pane does'). It is clearly distinguishable from read-side siblings like getCaptions and translation-side siblings like putCaptionTranslation.

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?

States patch semantics explicitly ('Only the fields you pass change') and gives the prerequisite that captions require a transcript, plus the lane fallback rule. It never names a competing sibling tool or says when to prefer getCaptions/putCaptionTranslation over this, so it stops short of full routing guidance.

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