BlitzReels Video Editor

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the agent knows this is a mutating but safe operation. The description adds only the default theme ('classic white') and does not disclose other behavioral traits like interaction with existing timeline items or the impact of layerIndex. With annotations covering the core safety profile, a 3 is appropriate.

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 a single, efficient sentence that immediately states the tool's purpose and its default. No wasted words; it front-loads the core action and resource.

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?

For a tool with 11 parameters, including two modes (overlay vs title_card) and several parameters that are ignored based on the mode, the description is too thin. It does not explain when to use overlay vs title_card, nor does it mention that certain parameters (size, theme) are ignored for overlay. Since an output schema exists, return values are covered, but the usage context is incomplete for such a configurable tool.

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 55%, so a significant portion of parameters (name, layerIndex, startSeconds, durationSeconds, text) lack descriptions in the schema. The tool description adds no parameter guidance beyond mentioning the default theme, which is already in the schema. It fails to compensate for the undocumented parameters, making this a weak area.

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 clearly states the verb 'Add' and the resource 'opening title card (hook) or generic text overlay to a project timeline,' which is specific and unambiguous. It does not explicitly differentiate from sibling tools like timeline_media_add or add_transition, but the purpose is clear enough for an agent to understand what this tool does.

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 gives no explicit guidance on when to use this tool versus alternatives, nor does it mention scenarios where another tool would be more appropriate. The distinction between 'overlay' and 'title_card' is only hinted at by the parenthetical, but no concrete usage context is provided.

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

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

Annotations already declare a non-destructive, idempotent, open-world mutation. The description adds no further behavioral context such as what exactly is created, permissions required, side effects on the timeline, or how expectedRevision affects the write. It does not contradict annotations, but it does not enrich them either.

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 a single front-loaded sentence with no filler. However, it is too sparse for a 12-parameter mutation tool with low schema coverage, so its brevity becomes under-specification rather than effective conciseness.

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?

For a 12-parameter tool with 25% schema coverage, existing annotations, and an output schema, this description is incomplete. It gives the purpose but omits the parameter meanings and usage context needed to invoke the tool 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?

With only 25% schema description coverage, the description must compensate for 9 undocumented parameters. It indirectly touches on timelineItemId (optional attachment) and includeSfx (paired with sound), but ignores name, easing, preset, intensity, layerIndex, durationSeconds, and expectedRevision.

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 verb and resource: 'Add a timed transition effect.' It distinguishes itself from timeline siblings like add_text_overlay or timeline_audio_add by resource type, though it does not explicitly name an alternative. Clarity is high but lacks sibling routing.

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?

There is no when-to-use or when-not-to-use guidance. The phrase 'optionally attached to one timeline item and paired with sound' implies the tool can be used standalone or attached, but this is context about parameters, not selection guidance versus alternatives.

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

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

Annotations already declare destructive, idempotent and closed-world behavior, so the bar is lower. The description adds real value by disclosing atomicity ('one sequence transaction') and the 100-item ceiling, which the annotations do not cover. It omits, however, what happens on conflict or partial failure.

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?

A single front-loaded sentence with zero waste; the resource, the scope, and the batch limit all land immediately.

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?

Output schema and annotations cover returns and safety, so the description need not restate them. It adequately conveys scope and atomicity, with only expectedRevision conflict semantics left unaddressed.

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 loosely maps 'timing, trim, layer, or state' onto the update fields, but adds no syntax or constraint detail beyond what the schema already documents.

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 (Update) plus the resource (timeline clips/items) and the batch scope ('up to 100 timeline items in one sequence transaction'). This distinguishes it from the single-item update_timeline_clip sibling, though it never names that sibling explicitly.

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 'batch' framing and the 100-item cap imply when to prefer this over the single-item sibling, but there is no explicit when-to-use/when-not statement, no mention of expectedRevision conflict behavior, and no guidance on partial failures.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds genuinely useful detail beyond them: it discloses that word overrides are preserved by default and only cleared when clearWordOverrides=true, and that existing captions are restyled while spoken audio is preserved. That explains exactly what the 'destructive' behavior touches, though it says nothing about permissions or auth requirements.

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 short sentences, front-loaded with the core action, then the override caveat, then the preservation guarantee. No filler and every sentence carries distinct information.

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, return values need not be explained, and the description covers the mutation's effects and preservation guarantees adequately for a destructive tool. It is still thin on permission/authorization context and on how the required idempotencyKey should be supplied.

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 only 40%, so the description must compensate, and it does explain the semantics of clearWordOverrides (the flag that controls override destruction). However, projectId, lookId, workspaceId, and idempotencyKey receive no added meaning in the description, leaving most parameters undocumented.

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 ('Apply') and resource ('a verified caption look') with an explicit scope of 'one project', so the action is unambiguous. It does not explicitly differentiate itself from adjacent caption siblings like captions_themes_list or captions_source_prepare, which is the only thing keeping it from a 5.

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 word 'verified' implies a prerequisite that the look must first be validated, giving some implied usage context, but there is no explicit when-to-use, when-not-to-use, or named alternative. The agent has to infer the workflow ordering.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true, so the burden is lighter, yet the description still adds real context: retry behavior ('avoids duplicate captions on identical retries'), that the full recording is preserved, and that no-speech is a legitimate success rather than a failure. It stops short of saying which existing editable captions are overwritten or what authorizations are needed, so it is not a 5.

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 tight sentences, with the core action front-loaded and each clause carrying distinct information (source, retry/idempotency behavior, precondition, edge case). No filler or repetition.

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?

An output schema exists so return values need not be described, and the annotations cover safety and idempotency. The description supplies the prerequisite and the no-speech success state, leaving only minor gaps around overwrite scope and parameter mapping.

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?

Only half the parameters carry schema descriptions, and those present just say 'UUID string'. The description adds indirect meaning for idempotencyKey ('identical retries') and projectId ('project captions'), but it never clarifies the assetId-vs-projectId relationship or the source-selection semantics, so it only partially compensates for the coverage gap.

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 pairs a specific verb and resource ('Restore editable project captions from the selected source's completed canonical transcript'), which is clearly distinct from siblings like captions_words_list or media_transcript_get. It does not explicitly name a sibling to disambiguate against, but the resource is precise enough for an agent to select it.

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 states a meaningful precondition ('Requires source transcription first') and defines an edge outcome ('no-speech is an explicit successful state'), which tells the agent when the call is valid. However, it never names an alternative tool or a when-not condition, so routing against e.g. captions_words_correct or captions_look_apply is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds that it includes both built-in looks and saved themes, which is useful context, but does not disclose additional behaviors like pagination or ordering. This is adequate given the annotations, but not overly rich.

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 a single, front-loaded sentence that directly states the action and scope. No redundant words or filler, making it highly concise and well-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?

For a simple list operation, the description, combined with comprehensive annotations and a full output schema, provides complete context. There are no missing details about return values or safety, and the tool's simplicity means no additional context is needed.

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?

All three parameters have full descriptions in the input schema, achieving 100% schema coverage. The description itself does not add parameter-level meaning, but the schema is sufficient, so the baseline score of 3 is appropriate.

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 clearly states the tool lists built-in caption looks and saved caption themes for a workspace, using a specific verb and resource. It distinguishes itself from sibling tools by focusing on caption themes, which is unique among the provided tools.

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 usage as a simple listing tool, but provides no explicit guidance on when to use it versus alternatives or when not to use it. Since no alternative theme-listing tools exist among siblings, this is acceptable but not explicitly stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful scope beyond that: it clarifies that timing, other captions, and the spoken audio are preserved, which narrows what "destructive" means here. It stops short of addressing partial-failure or auth behavior, so not a 5.

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 tight sentences, front-loaded with the action and followed by the preservation guarantee. No filler, and the second clause carries real information rather than restating the name.

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?

An output schema exists, so return values need not be described. The description covers the action and its side effects adequately, but omits guidance on the required idempotencyKey and the batch constraint (max 200 updates), which an agent must know to invoke 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 only 25% (only projectId has a trivial "UUID string" note). The description partially compensates by explaining that updates target words via "stable IDs" (wordId), but leaves idempotencyKey, workspaceId, array size limits, and the text-length constraint entirely unexplained in both schema and description.

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+resource ("Replace selected caption words") and the mechanism ("by their stable IDs"), which is easy to distinguish from the list-oriented sibling captions_words_list. It does not explicitly name or contrast any sibling, so it falls just short of the top mark.

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 use case (correcting already-existing caption words identified by ID, which presupposes a prior captions_words_list call) but never states when to use this versus alternatives or any prerequisites. Usage is inferable but not documented.

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

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is free. The description adds real context beyond that: results are 'bounded' (paginated), the words are 'editable' (i.e. subsequently mutable via the correct sibling), and IDs are 'stable' so they can be referenced later.

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?

A single well-packed sentence with the read action and scope front-loaded and no filler. Density is high but each clause (bounded, editable, stable IDs, optional match) carries information.

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?

An output schema exists, so return values need not be explained. For a 5-parameter read tool the description covers scope, filtering and pagination at a high level but omits ordering behavior, what 'bounded' limits actually are, and how stable IDs map to downstream correction calls.

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 only 20% (only projectId is annotated), so the description must compensate. It does so partially: 'one project' scopes projectId/workspaceId, 'optionally matching text' explains matchText, and 'bounded' signals limit/offset pagination. It still gives no bounds or ordering semantics for limit/offset.

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?

Specific verb (read) plus resource (caption words + stable word IDs) and scope (one project), with an optional text filter. It reads clearly as a listing tool against siblings like captions_words_correct, though it never names the alternative that mutates words.

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?

Usage is implied rather than stated: reading is clearly the safe/fetch direction, and 'for one project' plus 'optionally matching text' hints at when it applies. There is no explicit when-not guidance or pointer to sibling tools such as captions_words_correct or captions_themes_list.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered structurally. The description adds no behavioral context beyond that — it doesn't say what existing styling is lost (overrides? per-slide edits?), that the operation is idempotent and safe to retry, or that it is scoped to one carousel.

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?

A single front-loaded sentence with zero filler, and the destructive verb 'Replace' leads. It is efficient, though the brevity tips into under-specification for a destructive tool.

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?

For a destructive mutation with three sibling 'apply' tools and an undocumented optional workspaceId, the description leaves too much open: it never says whether all slides are re-styled, whether manual edits are lost, or how it differs from carousels_apply_theme. An output schema exists, so return values need not be explained, but the selection and impact gaps remain.

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 only 33% — only projectId carries a (generic 'UUID string.') description, while workspaceId and idempotencyKey are undocumented in the schema. The description compensates for none of this: it doesn't explain the optional workspaceId, nor whether idempotencyKey enables safe retries of this destructive replace.

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?

Names a specific action (replace styling) and the source applied (the workspace's saved brand theme), so the agent knows what the tool does. However, it makes no attempt to distinguish itself from the near-identical siblings carousels_apply_theme and carousels_apply_template, which is the highest-risk confusion for this tool.

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?

There is no when-to-use guidance, no when-not-to-use guidance, and no reference to the alternative 'apply theme' or 'apply template' tools. The agent is left to infer selection purely from the word 'brand' in the name.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is known. The description's use of 'Replace' aligns with the destructive hint and adds that the source must be a saved private template, but it says nothing about authorization needs, what happens to the overwritten slide content, or the destructive scope. With annotations covering safety, a 3 is appropriate.

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?

A single front-loaded sentence with no wasted words. It is tight, though its brevity is partly what leaves the usage and parameter gaps unfilled.

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 output schema removes the need to describe return values, but for a destructive five-parameter mutation the description is too thin: no usage context against numerous siblings, no preconditions, and minimal parameter clarification on top of 20% schema coverage.

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 only 20% (just projectId as 'UUID string.'). The description only loosely maps to savedTemplateId ('saved private template') and slideIndex ('one carousel slide'); it says nothing about idempotencyKey, workspaceId, or the 0–34 slideIndex range. For a 5-param tool at low coverage, the description does not compensate for the gap.

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 verb (replace), resource (one carousel slide), and source (a saved private template), so the operation is clear. It does not, however, distinguish itself from overlapping siblings such as carousels_apply_theme, carousels_apply_brand, or carousels_patch_slide, all of which also mutate a carousel slide.

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?

There is no guidance on when to use this tool versus the dense set of carousel siblings (apply_theme, apply_brand, patch_slide, save_template). No prerequisites, no exclusions, and no indication of when a saved-template replacement is preferable to a theme or brand apply.

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

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

Annotations already disclose destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds that styling is replaced by an existing saved theme, which is consistent with the annotations, but it does not explain what prior styling is lost, auth requirements, or rate limits.

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?

A single front-loaded sentence with no wasted words. It is efficient, though its extreme brevity leaves important details to other fields.

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?

For a mutating tool with four parameters, 25% schema coverage, and no carousel-id parameter described, the description is incomplete. The output schema and annotations reduce some burden, but they do not excuse the absence of parameter and prerequisite context.

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 only 25%, and the description names no parameters or formats. It implies themeId is the 'existing saved theme', but does not explain themeId, projectId, workspaceId, or the required idempotencyKey.

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 ('Replace') and resource ('this carousel's styling'), plus the source ('existing saved theme'). It does not explicitly differentiate itself from close siblings like carousels_apply_brand or carousels_apply_template, but the verb-resource combination is clear.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as carousels_apply_brand or carousels_apply_template. The agent must infer context from the name alone.

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

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

Annotations already declare readOnly=false, destructive=false, and idempotent=true, so the safety profile is covered. The description adds a useful trait — 'Copies slots' — clarifying that slot content is duplicated, but it does not state source-carousel behavior or side effects on the origin. Some added value on top of annotations.

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 short sentences, front-loaded with the purpose. Little waste, though the trailing icon/shot sentence is misaligned with the actual schema and reads as tangential rather than essential.

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?

An output schema exists so return values need not be described, but with 4 parameters at 25% coverage the description should explain the required idempotencyKey/projectId semantics and the optional name/workspaceId. It omits these and instead references fields not present in the schema, leaving the definition inadequate for a mutation tool.

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 only 25% (only projectId documented), so the description must compensate — and it does not. Worse, it discusses 'Icon and shot values' that do not correspond to any of the four parameters (name, projectId, workspaceId, idempotencyKey) and nested objects are absent, so this reference is confusing rather than clarifying. name, workspaceId, and idempotencyKey are left unexplained.

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 and resource ('Duplicate a carousel') plus a target scope ('onto a new project'), which cleanly distinguishes it from siblings like carousels_apply_template and carousels_migrate. It stops short of explicitly naming an alternative, but the core operation is unambiguous.

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?

There is no when-to-use / when-not-to-use guidance and no alternative tool is named. 'Onto a new project' implies context but leaves the agent to infer the conditions that select this over carousels_migrate or carousels_apply_template.

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

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

Annotations already declare destructive=true, idempotent=true, readOnly=false, and openWorld=false, so the safety profile is covered. The description adds genuinely useful ownership context ('Server owns chip layout, safezones, and exact export pixels'), telling the agent the server controls pixel-level layout. However it does not explain the create-vs-replace trigger, the role of idempotencyKey, or what clear_existing destroys.

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 tightly written sentences with no filler, and the operation plus its scope are front-loaded. Nothing is wasted, though the extreme brevity is part of the completeness problem rather than a virtue here.

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?

This is a complex mutation with 10 parameters, nested objects, and enum-driven visual kinds, and the description covers almost none of that surface. An output schema exists so return values needn't be explained, but the upsert trigger (project_id), clear_existing, idempotencyKey, and the required 'slides' structure are all undocumented.

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 0% across 10 parameters (project_id, clear_existing, style, locale, idempotencyKey, etc.), so the description carries the full burden and largely fails to. 'From a slide document' loosely gestures at the slides array and 'chip layout' at the style.chip object, but no parameter behavior, format, or required-vs-optional meaning is clarified.

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+resource ('Create or replace a carousel project from a slide document'), and 'create or replace' usefully signals upsert semantics. It does not name or distinguish itself from adjacent siblings like carousels_preview, carousels_clone, or carousels_patch_slide, so an agent must infer the boundary.

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?

No guidance on when to use this versus carousels_preview (validate first?), carousels_clone, or carousels_patch_slide (incremental edits). No prerequisites, no mention of when a replace is triggered vs a fresh create. The agent is left to infer routing from the verb alone.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description only adds that deletion targets a single 'private' template, which is minor context but nothing about irreversibility, confirmation, or the role of idempotencyKey.

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?

A single front-loaded sentence with zero filler, which is appropriately tight for this operation. It is efficient, though arguably under-specified rather than optimally concise.

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?

An output schema exists (so return values need no explanation) and annotations carry the destructive/idempotent profile, reducing the description's burden. Still, for a destructive delete with 75% of parameters undocumented, the definition leaves real gaps in usage and parameter guidance.

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 only 25% (just 'UUID string.' on projectId), and the description adds no meaning for savedTemplateId, idempotencyKey, or the optional workspaceId. A delete tool with three required params and near-zero schema docs should have its description compensate, and it does not.

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 (Delete) and a well-scoped resource (one saved private carousel slide template), so an agent can distinguish it from sibling mutations like carousels_delete_theme or carousels_save_template. The 'private' qualifier adds a useful scoping detail, though it doesn't explicitly name competing siblings.

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 only restates what the tool does; it gives no when-to-use context, no prerequisite/permission hints, and no comparison to alternatives such as carousels_delete_theme or the other carousel lifecycle tools.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description only adds the word 'private,' which hints at scope but not at irreversibility, permission requirements, or what happens to carousels currently using the theme. It does not contradict the annotations, but adds very little beyond them.

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?

A single front-loaded sentence with no filler, which is good, but for a destructive, four-parameter mutation the terseness tips into under-specification rather than efficiency.

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?

An output schema exists so return values need not be described, but the description omits everything an agent needs for a destructive mutation: scoping rules between projectId/workspaceId, retry semantics via idempotencyKey, and the consequences of removing a theme.

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 only 25% (only projectId has a bare 'UUID string.') and the description names no parameters at all, so it does not compensate. Nothing explains themeId, workspaceId versus projectId scoping, or that idempotencyKey makes retries safe.

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?

'Delete one saved private carousel theme' states a specific verb (delete), resource (carousel theme) and scope (one, saved, private). It does not, however, distinguish itself from the sibling carousels_delete_template or explain why a theme versus a template should be targeted.

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 gives no when-to-use context, no prerequisites (e.g., ownership or permission of the private theme), and never points at the adjacent tools carousels_delete_template, carousels_save_theme or carousels_apply_theme. The agent must infer routing from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is largely covered. The description adds two genuine behavioral guarantees beyond that, 'never publishes' and 'never invents metrics', which are valuable constraints. It says nothing about persistence, whether the expanded slides are saved to a carousel, or how output is scoped, so it is useful but thin.

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 short sentences, front-loaded with the core action and followed by the two negative guarantees. No filler, no restatement of the tool name, every clause earns its place.

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?

An output schema exists, so return values need not be explained, but for a 9-parameter tool with 0% schema coverage the description is far too sparse. It never explains how the non-recipe context fields (audience, platform, offer, locale) shape the expansion, nor where this fits relative to carousels_compile or carousels_apply_template.

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 0% across 9 parameters, so the description carries the full burden, yet it only obliquely covers the recipe/brief inputs. Parameters such as offer, locale, product, audience, platform, and workspaceId are unexplained in both the schema and the description, and the enum choices for recipeId and platform receive no interpretation.

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 transformation: turn a named recipe or brief into 'compile-ready named-template slides'. That is a clear verb+resource, and the 'never publishes' clause implicitly separates it from the compile/publish siblings. It stops short of explicitly naming which sibling to use instead, so it lands at 4 rather than 5.

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 phrase 'a named recipe or a brief' implies the two entry paths (recipeId vs. the 'from_brief' recipe plus brief), which is useful routing. However, there is no explicit when-to-use guidance relative to close siblings like carousels_apply_template, carousels_compile, or carousels_clone, leaving the agent to infer the workflow position.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds essentially nothing beyond the annotations – it does not explain what the returned "slot document" contains, what the "template catalog" scope is, or any access requirements. It does not contradict the annotations.

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?

A single short sentence with no waste and the action front-loaded. Efficient, though the brevity comes at the cost of substance rather than being paired with it.

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?

An output schema exists, so return values need not be described, and the read-only behavior is covered by annotations. Still, for a retrieval tool the description leaves key ambiguity about what is being fetched and how workspaceId scopes the result, making it only minimally adequate.

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 50%: projectId is described only as "UUID string" (a type restatement) and workspaceId has no description at all. The prose mentions neither parameter and adds no meaning about how projectId or workspaceId scope the read, so it fails to compensate for the coverage gap.

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 ("Read") and two resources ("carousel slot document" and "named template catalog"), so the basic operation is clear. However, the terms "slot document" and "template catalog" are ambiguous, and the description offers no differentiation from siblings like carousels_preview, carousels_compile, or carousels_expand_recipe, which also operate on carousel documents.

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?

There is no guidance on when to use this tool versus the many other carousels_* siblings (preview, compile, migrate, clone). No preconditions or context for invocation are given.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is largely covered. The description adds the behavioral context that the result is a normal compiled deck and can subsequently be patched, but it never says what gets destroyed or replaced (the existing document? the legacy carousel?), which matters for a destructive operation.

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 tight sentences with no filler, and the core action is front-loaded. It is arguably under-specified rather than over-long, so conciseness itself is good.

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?

For a destructive, jargon-heavy migration tool, the description leaves out when to use it versus carousels_compile, what happens to the legacy source after migration, and any meaning for the required idempotencyKey. The output schema covers return values, but the operational context is thin.

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 only 33% – only projectId has even a minimal 'UUID string.' note, while idempotencyKey and workspaceId are undocumented in both schema and description. The description contributes nothing about parameters, so it fails to compensate for the coverage gap.

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 and resource: rebuilding a 'compile slot document' from a 'legacy overlay carousel'. That is more than a restatement of the name 'carousels_migrate', but it never differentiates itself from close siblings such as carousels_compile or carousels_get, and the internal jargon ('compile slot document') is undefined.

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?

'Then patch slots like any compiled deck' implies a downstream workflow (the output behaves like a compiled deck and can be patched), which is useful implied usage. However, it never states when to choose migration over carousels_compile or carousels_apply_template, nor any precondition such as 'only for legacy overlay carousels'.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true; 'identical keys replay' merely restates the idempotency annotation without explaining what is destroyed, merged, or overwritten when patching a slide. No new behavioral context (merge semantics, revision conflict behavior) is added beyond what the annotations and required-field list already convey.

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 tight sentences with no filler, and the mutation/crop behavior is front-loaded. It is compact to the point of being under-specified, but it is not padded.

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?

An 11-parameter, nested-object, destructive mutation tool with an output schema gets only two terse sentences; the description identifies the two edit modes but leaves mode selection, parameter roles and conflict handling to inference.

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 only 9% across 11 parameters, so the description must compensate and largely does not; it hints at crop, slots/media, creativeArtifact and expectedRevision but says nothing about idempotencyKey, workspaceId, templateId, lines, slideIndex or projectId semantics.

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?

Names the verb (patch) and the resource from the title, and lists the two modes (native slots/media vs. completed Remotion frame artifact with crop). However, jargon like 'native slots' and 'Remotion frame artifact' is unexplained, and it never articulates how this differs from siblings such as carousels_slides_insert or carousels_clone.

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 a prerequisite ('Requires expectedRevision') but gives no when-to-use versus the many sibling carousels_* tools, and no indication of when to choose the slots/media path over the artifact-crop path. An agent must guess which mode applies.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds genuinely useful context beyond that: it explains what is overwritten ('Replaces cached previews at deterministic storage keys') and what is preserved ('preserves the source project and slide document'), which is exactly the mutation impact an agent needs.

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 tight sentences with zero waste, front-loading the core action and then the storage/impact detail. Nothing is redundant.

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?

An output schema exists so return values need not be explained, and the destructive/idempotent behavior is well covered. However, with 5 parameters and only 20% schema coverage, the description leaves the enumeration and selection parameters (chrome, slideIndexes) unexplained.

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 only 20% (just projectId's 'UUID string'), and the description does not compensate. Key params like 'chrome' (tiktok/instagram/none), 'slideIndexes', 'workspaceId', and the required 'idempotencyKey' are undocumented in either place, leaving their semantics opaque.

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 ('Render and store') plus resource and scope ('private JPEG previews for the selected carousel slides'). It clearly distinguishes a preview-generation action from siblings like carousels_apply_template or carousels_compile, though it doesn't name those alternatives.

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?

No guidance on when to use this versus carousels_get, carousels_compile, or other carousel tools, and no prerequisites or exclusions are stated. The agent must infer the usage context entirely.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, and the description adds the concrete side effect behind that flag: the oldest saved template is evicted once the 40-template limit is hit. That is genuine value beyond the annotations. It stops short of covering permissions/visibility rules for 'private' templates.

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?

One sentence, two clauses, zero filler, with the primary action front-loaded and the destructive limit rule trailing. Nothing to trim.

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?

An output schema exists so return values need no explanation, and the eviction behavior is disclosed. But for a six-parameter mutation with 17% schema coverage, the description leaves scope semantics, idempotency key usage, and template visibility rules unaddressed.

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 only 17% (projectId alone has 'UUID string.'), so the description carries the compensation burden and barely does so. It never explains slideIndex, the project/brand scope enum, the idempotencyKey, or when workspaceId is needed; only 'one carousel slide' loosely maps to slideIndex.

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 and resource: saving one carousel slide as a private template, with the slide-level granularity made explicit. It does not, however, distinguish itself from the adjacent siblings carousels_save_theme or carousels_apply_template, so an agent must infer the boundary from names alone.

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?

No when-to-use guidance and no exclusions. Nothing tells the agent why it would pick this over carousels_save_theme, nor when to save a template versus applying an existing one, nor how the project/brand scope parameter should be chosen.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real behavior beyond them: the theme is saved as private, it becomes the active theme, and the oldest theme is evicted at the 40-theme cap. That eviction detail is exactly the kind of destruction semantics annotations cannot convey. It still omits permission requirements and what 'activate' changes for other users.

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?

One front-loaded sentence whose two clauses both earn their place: the primary action first, then the retention constraint. No filler.

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?

An output schema exists, so return values need not be described, and annotations carry the safety profile. However, with five parameters at 20% schema coverage and a mutation that maintains a capped theme library, the description should at least hint at scope/idempotency behavior to be fully actionable.

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 only 20% — just 'UUID string.' on projectId — yet the description explains no parameters. The scope enum (project vs brand), workspaceId, idempotencyKey, and name are all left for the agent to infer, so the description fails to compensate for the sparse 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 names a specific verb-plus-resource pair ('save and activate the current carousel styling as a private theme'), which clearly separates it from siblings like carousels_save_template or carousels_apply_theme. It stops short of explicitly contrasting itself with those siblings, so it is clear but not fully differentiated.

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?

There is no statement of when to choose this over carousels_save_template, carousels_apply_theme, or carousels_apply_brand, nor any prerequisite (e.g., that styling must already exist on the carousel). Usage is only inferable from the phrase 'current carousel styling'.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=true), and "Preserves existing slide content" adds useful confirming context. However, the key behavioral detail an agent needs — that templateId and sourceIndex select mutually exclusive modes — is not disclosed, nor is the insertion semantics of index.

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 tight sentences with the action front-loaded and the non-destructive guarantee second. No filler or redundancy.

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?

Output schema is present so return values need no explanation, and annotations cover the safety profile. The remaining gap is the unexplained mode-selection logic and insertion-position semantics, which is a modest but real omission for a mutation tool with 6 parameters.

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 only 17%, so the description carries real weight here. It does map "named template" to templateId and "copy an existing slide" to sourceIndex, but index, idempotencyKey, and workspaceId remain undocumented in both schema and description. Partial compensation only.

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 and resource ("Insert one new carousel slide") and clarifies the two sourcing modes (named template vs. copying an existing slide). It is clearly distinct from carousels_slides_remove/reorder/undo, though it does not name any sibling explicitly.

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 two modes (template vs. copy) imply usage conditions, but the description never states when to choose this over alternatives such as carousels_slides_reorder, carousels_patch_slide, or carousels_clone, nor any prerequisites. Usage is inferable but not guided.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so safety is covered. The description adds only the detail that the slide's content is removed along with it, with no info on auth, irreversibility, or side effects on indices.

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?

A single front-loaded sentence with no filler. Its brevity is virtuous here, though it verges on being too terse to guide invocation.

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?

For a destructive multi-parameter tool with only 25% schema coverage, the description is thin. The output schema relieves it of explaining returns, but nothing compensates for the undocumented index, projectId, and idempotencyKey semantics.

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 25% across 4 params, so the description carries most of the burden but adds nothing. It never explains the 'index' selector (including its 0-34 bound), the idempotencyKey, or the optional workspaceId.

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 (remove) and resource (carousel slide) with the scope of 'one' slide plus its content. It is clearly distinguishable from siblings like carousels_slides_insert and carousels_slides_reorder, though it never names them.

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?

No when-to-use guidance and no mention of alternatives or prerequisites. Notably it does not point to carousels_slides_undo as a recovery path, nor explain how this differs from carousels_patch_slide.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds the meaningful behavioral fact that the operation 'replaces the existing slide order' (i.e., other slides shift), which is useful context beyond the flags, but says nothing about bounds, failures, or side effects on dependent assets.

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 tight sentences, front-loaded with the action and no wasted words. It is arguably under-specified rather than bloated, so terseness itself is not a fault here.

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?

An output schema exists so return values needn't be documented, and annotations cover destructive/idempotent behavior. However, with 5 parameters at 20% coverage and no usage routing against three closely related sibling tools, the description leaves substantial gaps for a mutation operation.

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 only 20% across 5 params, so the description must compensate and largely does not. 'New index' loosely grounds the from/to positional integers, but projectId, workspaceId, and idempotencyKey receive no explanation and the 0-34 index bound is left to the 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?

States a specific verb and resource ('Move one carousel slide') plus the destination concept ('new index'), which cleanly separates it from carousels_slides_insert, carousels_slides_remove, and carousels_slides_undo. It stops short of explicitly naming those siblings or confirming which operation family it belongs to.

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?

There is no when-to-use guidance, no condition that selects this over carousels_slides_insert/remove/undo, and no prerequisites such as required permissions. The reader must infer the use case entirely from the name.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description usefully reinforces this by saying the current slide document is replaced, but it does not say how far back the revision goes, whether the operation can itself be undone, or what happens if no prior revision exists.

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?

A single efficient sentence with the action front-loaded and no filler. It is appropriately short, though the brevity borders on under-specification rather than being optimally sized.

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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. But for a destructive, low-coverage-parameter mutation, the description leaves key call-time questions unanswered: revision depth, undo-of-undo behavior, and the role of idempotencyKey and workspaceId.

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 only 33% (just a trivial 'UUID string' for projectId), leaving workspaceId and idempotencyKey undocumented, and the description adds nothing about any parameter — not even which project's carousel is targeted. With low coverage the description needed to compensate and does not.

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 (Restore) and resource (previous carousel document revision) and notes the replace semantics, which separates it from additive siblings like carousels_slides_insert or carousels_patch_slide. It does not, however, distinguish itself from editor_edit_undo, and the mismatch between the slide-oriented name and the 'document revision' wording leaves the scope slightly ambiguous.

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?

No when-to-use guidance, no prerequisites, and no mention of the obvious alternative editor_edit_undo or of when an undo is unavailable (e.g., no prior revision). The agent must infer everything from the name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is covered. The description adds nothing beyond that: it does not explain what gets destroyed/overwritten on update, that likeness and reference-rights consent must be confirmed before a human character is applied, or how idempotencyKey governs replay. It essentially restates the annotation-covered mutation behavior.

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?

A single front-loaded sentence with no filler or repetition. It is well-formed, though its brevity is a symptom of under-specification rather than disciplined economy.

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?

For a 14-parameter, destructive, consent-gated mutation tool, this description is far too thin. An output schema exists so return values need not be explained, but the create-vs-update branching, consent prerequisites, and idempotency behavior are all missing.

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?

Only 2 of 14 parameters carry schema descriptions (~21% coverage), so the description must compensate and largely fails to. 'Reference-based' loosely gestures at referenceAssetIds/primaryReferenceAssetId, but type/species/storyFacts/defaultVoiceId/characterId/canonicalDescription are left with no semantic explanation at the description level.

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 pair ('create or update') and a specific resource ('reference-based character'), and adds the domain ('repeatable faceless story generation'). An agent can distinguish it from the read-only siblings characters_get and characters_list, though it never states that distinction explicitly.

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?

There is no when-to-use guidance: nothing says when to create vs update (e.g., presence of characterId), when the consent flags are required, or how this relates to characters_get/characters_list or generation_faceless_create. The phrase 'for repeatable faceless story generation' implies context but is not actionable routing guidance.

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

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

The description adds minimal behavioral context beyond the annotations. 'Inspect' aligns with readOnlyHint=true and destructiveHint=false. The mention of 'ordered reference-image set' hints at the output structure, but no further details about auth, rate limits, or idempotency are provided. Annotations already cover the safety profile.

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?

A single sentence of 14 words that is front-loaded and efficient. However, it is slightly terse and could be more explicit about the core resource (e.g., 'Reusable character' is a domain term that may not be universally understood). Still, it earns its place without excess.

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 simple nature of the tool (read a single character), the presence of annotations and an output schema, the description is mostly complete. It clarifies the use case and the ordered reference-image set. However, it does not explicitly state that the characterId is required or that the operation is read-only, though these are inferred from context and annotations.

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 description does not mention any parameters. Schema coverage is 50% (workspaceId has a description in the schema, but characterId does not). The tool description could have explained what characterId represents, but it fails to compensate for the undocumented parameter, leaving a gap.

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 specifies the verb 'Inspect' (read-only) and the resource 'one reusable character and its ordered reference-image set', with a clear scope ('before planning a story'). This distinguishes it from siblings like 'characters_list' (list all) and 'characters_apply' (apply a character).

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 provides a clear context for when to use this tool ('before planning a story'), but does not explicitly mention when not to use it or alternatives such as 'characters_list' for browsing. The sibling list implies the differentiation, but the description could be more direct.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe, repeatable read operation. Description adds the term 'bounded' which hints at scope but doesn't explain what 'bounded' means (e.g., workspace-scoped, project-scoped) nor mention pagination behavior that offset/limit implies. No contradiction with annotations.

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?

Single sentence, 14 words, zero waste. Each part ('List', 'bounded reusable characters', metadata details) serves a clear purpose. Front-loaded with the action and resource.

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?

Despite low parameter description coverage, the output schema exists and parameter names are clear. The description lacks a note about workspace scoping or archived behavior, but for a simple list tool with rich annotations and output schema, it is largely complete. Could mention that workspaceId is optional and defaults to user's default.

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 covers 4 parameters but description coverage is only 25%—it does not mention or elaborate on any parameter. However, the output schema exists and parameters like limit/offset/workspaceId/includeArchived are self-explanatory from names and schema defaults. Baseline 3 is appropriate since description adds no value beyond schema, but schema names provide adequate context.

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?

Description states specific verb ('List'), resource ('bounded reusable characters'), and included data ('identity, voice, facts, and image-reference metadata'). It clearly distinguishes this tool from sibling tools like characters_get or characters_apply by framing it as a list operation. However, it doesn't explicitly differentiate from other list tools in the sibling set.

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?

Implied usage is listing characters, but no explicit guidance on when to use this vs alternatives like characters_get (for a single character) or characters_apply (for applying characters). No exclusion criteria or context about filtering, pagination, or prerequisites beyond schema-bound parameters.

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

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

The description goes well beyond the annotations (which already indicate destructive and idempotent). It discloses that dry-run is the default, real deletion requires confirmation and a retention choice, workspace delete permission is needed, and an idempotency key is required. This fully informs the agent of conditions and 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 a single, well-structured sentence that efficiently conveys purpose, default behavior, and prerequisites. Every phrase adds value without wordiness.

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 description covers the core behavior and preconditions for this destructive, idempotent tool with 6 parameters. Given that the output schema exists (so return format is already specified), the description provides sufficient context for the agent to understand the tool's workflow, though it does not elaborate on what the dry-run preview returns.

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?

With only 33% schema description coverage, the description must compensate for the lack of parameter details. It does add semantic value by referencing dry-run, confirmation, retention choice, workspace permission, and idempotency key. However, it does not explain the precise conditions for each parameter (e.g., dryRun must be false, confirmDelete must be true, or the meaning of retention enum values), leaving some ambiguity for the agent.

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 clearly states the tool's purpose with a specific verb and resource: 'Preview or delete a terminal clip batch.' It distinguishes itself from sibling tools like delete_timeline_items by focusing on clip batches, and the dual preview/delete nature is explicit.

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 provides clear context for when to use this tool: for previewing or deleting a terminal clip batch. It implies that real deletion requires explicit confirmation and permissions, giving the agent actionable guidance. It doesn't explicitly name alternatives, but the resource type is distinct enough from siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds that results are bounded and that no generation/rendering occurs, but says nothing about pagination traversal, ordering, or what happens when no candidates exist.

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, both front-loaded: the first says what is returned, the second bounds expectations and rules out adjacent operations. No filler or restatement of the tool name.

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 explain return shapes, and it correctly focuses on purpose, exclusions and boundedness. The only real gap is parameter-level guidance for the two UUID scoping arguments and paging controls.

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 only 25% (assetId is documented merely as "UUID string"; workspaceId, limit and offset have none). The description contributes no parameter meaning at all — it never explains what assetId/workspaceId scope the candidate listing to, nor that limit/offset drive the paging implied by "results are bounded."

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 ("Read") and resource ("existing suggested moments") and enumerates the payload an agent will see (source ranges, hooks, transcript excerpts, thumbnails). It is clear this is a read of pre-computed candidates rather than the clips themselves, though no sibling from the large clips_* family (e.g. clips_list, clips_inspect) is named to disambiguate.

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?

"before producing videos" places the call in a workflow sequence, and "this does not generate suggestions or render clips" is an explicit when-not that excludes clips_create/clips_export style work. No named alternative tool is given for the case where the agent wants committed clips rather than candidates.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, and idempotentHint=false, covering the mutation/safety profile well. The description adds only that the batch is private, then repeats the URL source-type capability already in the schema. It does not add beyond annotations like async/polling behavior or what gets destroyed.

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 front-loaded sentences with no padding; the core action is stated first. The second sentence is somewhat redundant with the url parameter description, but the overall size is appropriate.

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 13 parameters, no required fields, an output schema, and 100% schema coverage, the structured data carries most of the burden. However, the description omits the end-to-end workflow (list candidates, select, then create/reselect) and any async/status context, leaving gaps for a fairly complex creation tool.

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 all 13 parameters are fully documented in the schema and the baseline is 3. The description's mention of source URL types duplicates the url parameter's own description rather than adding syntax or constraint detail.

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?

Clear verb+resource: create a private clip batch from an asset or a URL, with the supported source types named. It does not differentiate itself from siblings like clips_reselect, clips_recover, or clips_repair, which also operate on clip batches, so an agent must infer the boundary.

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 names source capabilities (social videos, Google Drive, direct URLs) but gives no when-to-use guidance, no prerequisites, and no routing to alternatives such as clips_reselect or clips_candidates_list. The one useful routing hint ('Resolve IDs with clips_candidates_list first') lives only in the schema, not the description.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description adds genuinely useful behavior beyond that: it replaces the delivery pointer and preserves earlier exports, telling the agent exactly what state changes and what is retained.

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 followed by the side-effect/precondition detail. No filler or redundant restatement of the title.

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, return values need not be explained, and the description covers the mutation's precondition and effect on state. It is slightly under-complete on parameter meaning and on routing to alternatives, but adequate for a 5-param delivery operation.

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 only 20% (essentially just workspaceId's UUID note), so the description must carry the load. It only indirectly clarifies confirmVisualQa as a QA gate; clipId, exportId, and especially idempotencyKey are left undocumented in both schema and description.

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 precise verb+resource: promoting a completed export to the accepted delivery for a clip. It clearly distinguishes this from siblings like clips_export, exports_start, or exports_list by describing a selection/pointer operation rather than a creation one.

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 implies the precondition 'after explicit visual-QA confirmation,' which tells the agent when it is legitimate to call this tool. However, it names no alternative tools and gives no when-not guidance (e.g. what to do if QA has not passed, or how this relates to exports_list).

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

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

Beyond the annotations, it discloses two meaningful traits: it can consume account credits (a cost/side-effect warning) and it is asynchronous with persisted state that must be polled. Idempotency is already carried by annotations and idempotencyKey. It stops short of explaining what the destructiveHint entails.

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 tight sentences with the core action front-loaded, followed by the return/async behavior and the credit caveat. Each sentence carries information with no filler, though the phrasing is slightly dense.

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?

An output schema exists so return values needn't be described, and the description does cover cost and async flow. Still, as a credit-spending mutation tool with 6 params at 17% coverage, it omits enough parameter behavior that an agent cannot call it confidently without opening 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 only 17% (just workspaceId's 'UUID string'), so the description must compensate across 6 parameters. It vaguely gestures at quality/format via 'existing-account-supported quality' but never explains format, resolution, coverFrameSeconds, workspaceId, or the required idempotencyKey, leaving most parameters undocumented.

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 verb and resource ('Render one managed clip') and implies scope via 'one' and 'at an existing-account-supported quality', which separates it from batch/status siblings. However it does not explicitly distinguish itself from exports_start or clips_status_get, so an agent must infer the boundary.

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?

'Returns persisted export state; inspect until the accepted delivery file is ready' implies a polling workflow, which is useful usage context. But it never states when to choose this over exports_start, nor how it relates to clips_delivery_promote or clips_inspect, leaving the selection to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds that the response includes render counts and download links, which hints at a polling/retrieval use case, but does not state whether the batch must be complete or whether the data is eventually consistent. Modest added value above the annotations.

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?

A single front-loaded sentence that lists the four returned artifacts with no filler or repetition. Nothing could be trimmed without losing information.

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?

An output schema exists, so the description need not document return values, and it is adequate for a two-parameter read tool with full annotations. The gap is routing: with siblings clips_status_get, clips_inspect, and clips_list in the same namespace, the description never helps the agent choose this one over those.

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% for both parameters, so the schema already explains batchId and the optional workspaceId default. The description adds no syntax, format, or scoping detail beyond what the schema provides, making the baseline of 3 appropriate.

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 ('Get') plus resource ('a BlitzReels clip batch') and enumerates what comes back: status, generated clips, render counts, and download links. That is more informative than a bare 'get batch'. It does not, however, distinguish this tool from the closely named sibling clips_status_get, leaving some ambiguity about which retrieval endpoint to pick.

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?

There is no when-to-use guidance, no preconditions (e.g. batch must be finished rendering), and no mention of alternatives such as clips_status_get or clips_list. The agent must infer usage purely from the name and the description's field list.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description reinforces this with 'Does not publish content', but adds nothing about permissions, whether an unpublished page returns an error, or rate limits. Per the lower bar when annotations exist, this is adequate but thin.

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 compact sentences with no filler; the core action is front-loaded and the clarifying exclusion comes second. Every clause earns its place.

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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. Still, with two required parameters and a 50% documented schema, the definition could clarify what the share state means when unpublished or how workspace scoping applies.

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 50%: assetId is documented only as 'UUID string' and workspaceId has no description at all despite being required. The description mentions neither parameter, so it adds no meaning beyond the schema's formats and does not compensate for the coverage gap.

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 (Read) and resource (the source video's clip share page) plus what is retrieved: public status and visible clips. The closing 'Does not publish content' distinguishes it from clip_share_publish/unpublish, though it never names those siblings explicitly.

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 negative clause 'Does not publish content' gives an implicit when-not signal, steering the agent away from the publish path. However, there is no explicit guidance on when to read this versus clip_share_visibility_set or clip_share_unpublish, so usage is only implied by negation.

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

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

Annotations already declare destructive, idempotent, and openWorld behavior, so the bar is lower and the description usefully adds context beyond them: the mandatory confirmPublicSharing gate, the returned verified public URL, and the scope clarification that no social-network post occurs. It could go further on reversibility (that unpublish restores the private state), but it adds real value.

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 tightly written sentences with the action and scope front-loaded, followed by the prerequisite and the return guarantee. Every sentence carries information and none is redundant.

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?

An output schema exists, so the description need not detail return values (though it usefully names the public URL), and the annotations cover the safety profile. For a 7-parameter, all-required mutation the description is nearly sufficient, with the main gap being the undefined idempotency and identifier semantics.

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 only 14%, so the description should compensate, and it does explain the semantic fields (title, description, allowDownloads, confirmPublicSharing). It leaves assetId, workspaceId, and especially idempotencyKey unexplained, so significant parameter semantics remain undocumented.

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 and resource: making the selected clip page public with reviewed metadata and download permission. An agent can distinguish it from clip_share_unpublish, but the description does not explicitly contrast it with clip_share_visibility_set, which sounds like it also affects the same public/private surface.

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 prerequisite 'Requires confirmPublicSharing=true from the user' gives a clear precondition for invocation. However, it names no alternative or exclusion condition, so the agent must infer when to choose this over clip_share_visibility_set or clip_share_unpublish.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds genuinely non-obvious context: the change is limited to the existing publication and explicitly preserves private projects and exports, which bounds the blast radius. It still doesn't say whether unpublishing is reversible, but it adds real value beyond annotations.

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 short sentences, front-loaded with the core action, with the scope caveat second. No filler.

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?

An output schema exists and annotations cover the safety profile, so the description need not explain return values. However, for a destructive mutation with a required idempotencyKey, the description says nothing about the idempotency contract or error cases, leaving a real gap.

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 only 33% — workspaceId and idempotencyKey carry no descriptions, and assetId is documented merely as 'UUID string'. The description mentions no parameters at all, so it does nothing to compensate for the coverage gap; an agent must infer that assetId selects the clip page.

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 and resource — 'Disable public access to the selected clip page' — which is clearly distinct from clip_share_publish and clip_share_visibility_set. It does not name those siblings explicitly, so it falls short of a 5, but the action is unambiguous.

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?

'Changes an existing publication' implies the precondition that a publication exists, and hints at scope, but it never says when to use this versus clip_share_visibility_set or clip_share_publish, nor what happens if no publication exists. Usage is implied rather than stated.

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