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 indicate idempotent=true, readOnly=false, and destructive=false. The description adds valuable behavioral context: the operation is transactional and limited to 100 items. It does not contradict the annotations and provides insight beyond the structured hints.

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, tightly packed sentence. It front-loads the verb, specifies the supported fields, and includes the critical constraints (up to 100 items, one transaction) without any wasted words.

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 rich schema (100% coverage) and the presence of an output schema, the description is sufficient for understanding the core operation. It captures the essential batch and transactional behavior. A minor gap is not explicitly directing users to the singular update_timeline_clip for single updates, but that is more of a usage guideline than a completeness issue.

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 100%, so every parameter already has a description. The phrase 'timing, trim, layer, or state' adds semantic grouping to the fields, but it does not provide new syntax or details beyond what the schema already documents. This is the baseline for high schema coverage.

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 action ('Update'), the resource ('timeline items'), and the scope ('up to 100 ... in one sequence transaction'). It explicitly lists the kinds of updates (timing, trim, layer, state), which distinguishes it from singular siblings like update_timeline_clip.

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 clear context for use: it is for batch updating up to 100 items atomically ('one sequence transaction'). It does not explicitly name an alternative for single-item updates, but the batch limit and transactional phrasing imply the appropriate use case.

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?

Annotations declare idempotentHint=true and destructiveHint=false, so the description doesn't contradict them. It adds one useful behavioral context: 'Icon and shot values may be pack filenames or asset:<media_asset_id>.' This goes beyond fields but is more about data representation than side effects or prerequisites. It doesn't disclose permissions, reversibility, or any consequences of cloning, which are relevant for a mutating 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 sentences with no fluff. The main action is front-loaded, and the asset-format clarification is appended efficiently. Every word 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?

Despite having an output schema, the description omits critical context: How is the source carousel identified? There is no carouselId parameter. Also, it doesn't state any prerequisites (e.g., whether the target project must exist) or what happens to existing slots. For a mutating clone operation, this is a significant 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 25% (projectId has a generic 'UUID string' description). The description does not explain the role of any parameter (e.g., projectId as target vs. source, workspaceId, name, idempotencyKey). The note about icon and shot formats refers to the copied content, not the parameters themselves. It fails to compensate for the low schema coverage.

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 ('Duplicate'), the resource ('a carousel'), and the target ('onto a new project'). 'Copies slots' adds a behavioral detail. This clearly distinguishes it from sibling operations like carousels_migrate or carousels_compile because it is a pure copy operation onto a new project.

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 no guidance on when to use this tool versus alternatives. It doesn't mention conditions, exclusions, or name any sibling for contrast. An agent has to infer that 'clone' implies a copy action, but there is no explicit direction about when this is preferable to other carousel-related 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?

The description adds useful behavioral context beyond the annotations: the server controls chip layout, safezones, and export pixels, so callers should not expect to specify those details. 'Create or replace' is consistent with idempotentHint=true, and the annotations already cover read/write and destructive hints; no contradiction is evident.

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 with the action front-loaded and no wasted words. The second sentence adds a meaningful behavioral boundary without repeating schema constraints.

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 tool with 10 parameters, nested slides/style/visual objects, and no schema descriptions. The two-sentence description leaves key semantics unexplained, including idempotency key behavior, clear_existing semantics, platform-specific constraints, and how the result relates to existing projects.

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%, so the description needed to compensate, but it only maps 'slide document' to the slides parameter. It does not explain required fields like idempotencyKey, platform, or name, nor options such as clear_existing, style, series_id, or project_id.

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 concrete action ('Create or replace a carousel project') and the input source ('a slide document'), making the core purpose clear. It doesn't name or contrast sibling tools like carousels_patch_document or carousels_clone, so it stops short of full differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance about when to use this tool versus alternatives such as carousels_patch_document, carousels_preview, or carousels_migrate. The phrase 'Server owns chip layout...' hints at an automated-compilation use case, but the agent is left to infer when this is the right choice.

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, non-destructive, idempotent operation. The description adds valuable behavioral context beyond annotations: 'never publishes' (side-effect boundary) and 'never invents metrics' (data integrity guarantee). It also clarifies the input modes ('named recipe or a brief') and output ('compile-ready named-template slides'). This is good additional context that goes beyond the structured 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?

The description is two sentences, front-loaded with the core action and output, followed by two crisp negative constraints. Every word earns its place. It's concise, structured, and immediately scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 9 parameters, an output schema, and annotations. The description covers the core input modes (recipe or brief) and the key behavioral boundaries (no publish, no invented metrics). It doesn't explain the optional parameters (offer, locale, product, audience, platform, workspaceId) or how they influence the expansion, but the output schema exists and the annotations cover safety. For a complex tool with 9 params, the description is reasonably complete but could benefit from a note on how optional params shape the output. Given the output schema exists, the description doesn't need to explain return values. A 4 is fair.

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%, so the description carries the burden of explaining parameters. The description mentions 'named recipe or a brief' which maps to recipeId and brief parameters, but it doesn't explain the other 7 parameters (name, offer, locale, product, audience, platform, workspaceId). The schema itself has enums for recipeId and platform, and types for others, but no descriptions. The description adds some semantic context (recipe vs brief) but doesn't compensate for the 0% coverage of the remaining parameters. Baseline 3 is appropriate because the description adds some meaning but leaves many parameters 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?

The description states a specific verb ('Expand'), a clear resource ('a named recipe or a brief'), and the output ('compile-ready named-template slides'). It also distinguishes itself from siblings by explicitly saying it 'never publishes' (contrasting with carousels_compile) and 'never invents metrics' (contrasting with generation_plan_brief or similar). This is a clear, specific purpose statement that differentiates it from the sibling 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 when to use this tool: when you have a named recipe or a brief and want to expand it into slides. It also gives an exclusion: 'never publishes', which tells the agent not to use this tool when publishing is the goal. However, it doesn't explicitly name the alternative tool for publishing (e.g., carousels_compile) or state when to use a sibling instead. The context signals show siblings like carousels_compile, carousels_clone, carousels_patch_document, which are related, but the description doesn't explicitly route to them. Still, the 'never publishes' clause provides a clear boundary.

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. The description adds a small amount of scope context (which artifacts are read) but discloses nothing beyond that, such as auth requirements or side effects — acceptable given the annotation coverage.

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 states both the action and the two resources read with no filler. It is slightly under-specified, but every word 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?

The tool is simple (2 params, 1 required), annotations cover safety, and an output schema exists, so the description need not explain return values. The main gaps are parameter semantics and the meaning of the nullable workspaceId, which leaves the description adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 50%: projectId has a tautological 'UUID string' description and workspaceId has none. The description does not compensate by explaining what projectId identifies, what workspaceId null means, or how the parameters relate to the slot document/template catalog.

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 identifies distinct resources ('carousel slot document and the named template catalog'), which separates it from sibling carousel tools like carousels_patch_document, carousels_compile, and carousels_preview. It does not explicitly contrast itself with those siblings, but naming the exact artifacts read is enough to disambiguate the core intent.

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 guidance on when to use this tool versus alternatives such as carousels_preview, carousels_kit, or characters_get. Usage is only weakly implied by the verb, and no prerequisites, exclusions, or sibling routing are mentioned.

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 real behavioral context beyond the annotations: applying themes rewrites fonts, colors, overlays, and asset logos, and 'Never persist signed URLs' is a concrete constraint. The main gap is that delete_theme and delete_template operations are not disclosed, though this does not contradict the readOnly or idempotent hints.

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 main action and containing no filler. The side-effect warning and signed-URL constraint each earn their 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?

For a tool with a 7-value op enum, 9 parameters, and delete operations, three sentences are not enough. An agent cannot determine which parameters are required per operation or how scope, workspaceId, and slideIndex interact; the output schema covers return shape, but the operation-selection semantics remain under-documented.

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 11% schema description coverage, the description needed to explain op, themeId, savedTemplateId, scope, and slideIndex, but it only adds general context about what themes rewrite. It does not clarify per-operation parameter requirements or the difference between project and brand scope.

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-resource pair ('Save or apply a theme, brand theme, or named slide template') and adds detail about what themes do ('rewrite fonts, colors, overlay, and asset:<id> logos'). It does not explicitly distinguish from sibling apply/list tools, and it omits the delete operations visible in the op enum, so it is not 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 description implies the use case by saying the tool saves/applies themes, and the op enum provides sub-operations. However, it never states when to prefer this tool over siblings such as captions_themes_list, story_kits_apply, or series_apply, nor does it give any exclusions.

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=false, idempotentHint=true. The description adds that it rebuilds a document and then patches slots, implying a two-step behavior. It doesn't disclose side effects beyond what annotations cover, but it does clarify the migration nature. 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?

Two sentences, no fluff. The core action is front-loaded. It could be slightly more structured by naming the alternative tools, but it's concise and readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema (not shown), so return values are covered. The description explains the migration workflow but lacks parameter semantics and explicit routing to siblings. For a migration tool with 3 params and 2 required, an agent would need more context on what idempotencyKey and workspaceId mean, and when to use this vs carousels_compile. It's adequate but has clear gaps.

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 a description, and it's just 'UUID string.'). The description does not explain the parameters at all. idempotencyKey and workspaceId are undocumented in the schema, and the description doesn't compensate. With low coverage, the description should add meaning but doesn't.

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 action: 'Rebuild a compile slot document from a legacy overlay carousel' and then 'patch slots like any compiled deck.' This clearly identifies the resource (compile slot document) and the operation (migrate/rebuild from legacy carousel). It distinguishes itself from siblings like carousels_compile and carousels_patch_document by focusing on legacy migration, though it doesn't explicitly name 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?

The description implies usage: use this when you have a legacy overlay carousel and need to rebuild a compile slot document. It says 'Then patch slots like any compiled deck,' which hints at a workflow but doesn't explicitly state when to use this vs alternatives like carousels_compile or carousels_patch_document. No exclusions or alternative tool names 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?

It reveals behavior beyond annotations: 'One write for the filmstrip' signals atomicity/scope, and 'Insert rasters an empty named template unless sourceIndex copies a slide' describes a non-obvious default. Annotations already handle idempotency and non-destructive status, so this is appropriate supplementary disclosure.

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, with the operation list front-loaded and the nuanced insert behavior isolated in the second sentence. No filler or repetition 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?

The definition is too sparse for a 9-parameter mutation with 11% schema coverage: it does not clarify how from/to/index map to operations, what idempotencyKey should be, or how workspaceId interacts with projectId. Output schema exists, so return-value docs are not needed, but call construction remains underspecified.

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 11% schema coverage, the description must carry parameter meaning but only hints at templateId ('named template') and sourceIndex ('copies a slide'). Positional semantics for to, from, and index, plus workspaceId and idempotencyKey, are left completely unexplained, and 'duplicate' is listed even though op's enum omits it.

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 enumerates a specific action set ('Reorder, remove, insert, duplicate, or undo slides') on a clear resource ('compiled carousel'), so an agent can tell this is a structural slide-level patch rather than a single-slide edit. It does not explicitly contrast with carousels_patch_slide, so it stops short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'on a compiled carousel' gives a context clue, but the description never states when to prefer this tool over sibling tools like carousels_patch_slide, carousels_compile, or carousels_get. No when-not conditions or alternative names are 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 signal that this is a non-read-only, idempotent, non-destructive operation. The description adds valuable context beyond these annotations: it re-rasters only that slide and never rewrites HTML. This is specific behavioral disclosure about side effects that annotations do not cover.

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 terse sentences with no waste. The purpose is front-loaded, followed by behavioral constraints. Every clause earns its place and the description is highly scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values are covered. However, an 8-parameter tool with a nested slots object and low schema coverage needs far more input context. The description does not explain what 'lines' represents, how slot keys are used, or the roles of mediaAssetId and workspaceId, leaving an agent to guess at correct invocation.

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 13% (only projectId has a description). The description names 'slots' and 'template_id' as the patchable entities, but leaves lines, mediaAssetId, workspaceId, and slideIndex unexplained. With 8 parameters and a nested object, this partial compensation is insufficient for an agent to understand what to pass.

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 exactly what the tool does: patch named slots or template_id on one slide. It names the specific verb, resource, and scope, and adds behavioral differentiators (re-rasters that slide only, never rewrites HTML) that distinguish it from broader carousel tools like carousels_patch_document.

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 for single-slide targeted updates ('on one slide', 're-rasters that slide only') but never explicitly says when to prefer this over alternatives or when not to use it. It does not mention carousels_patch_document or other sibling tools, so the agent must infer the boundary from the name and scope.

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. The description adds valuable behavioral context: it returns MCP images (not just data), renders JPEG stills, and uses the exact platform frame. This goes beyond what annotations provide.

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, front-loaded with the action and purpose. Every phrase earns its place: 'JPEG stills', 'compiled carousel', 'exact platform frame', 'MCP images', 'inspect chips on the real slides'. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema (MCP images), so return values are covered. The description explains the purpose and output format. It could mention that the carousel must be compiled first (prerequisite), but the word 'compiled' implies this. For a read-only preview tool with rich annotations, this is nearly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 25% (only projectId has a description, and it's just 'UUID string'). The description mentions 'compiled carousel' and 'platform frame' which hints at projectId and chrome, but doesn't explain slideIndexes or workspaceId. The chrome enum is self-explanatory, but slideIndexes semantics (which slides to render) are not described. Baseline 3 is appropriate since the description adds some context but doesn't fully compensate for the low schema coverage.

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 ('Render'), a specific resource ('compiled carousel'), and the exact purpose ('inspect chips on the real slides'). It clearly distinguishes this from sibling tools like carousels_compile or carousels_get by focusing on previewing rendered stills as MCP images.

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 this is for inspecting a compiled carousel before/after compilation, and the 'exact platform frame' phrasing signals it's for platform-specific visual verification. It doesn't explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it over compile/get 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 disclose idempotentHint=true and destructiveHint=false; the description adds the upsert-like 'create or update' behavior and the fact that the character is reference-based. It does not disclose important operational constraints such as consent or rights gates, but those are documented in the schema properties, so the additional behavioral gap is moderate.

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 tight sentence that front-loads the operation, the resource kind, and the use case; no filler or restatement of the title. It earns its place, even though it sacrifices detail.

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?

Although an output schema exists, the tool has 14 parameters and a very low schema description coverage. The description leaves critical invocation questions open—how updates are keyed (characterId vs idempotencyKey), what reference assets are required, and which consent flags must be set. This is not complete enough for a complex write 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 21%, so the description should compensate for the many undocumented parameters. It does not: no mention of idempotencyKey, characterId as the update selector, referenceAssetIds/primaryReferenceAssetId, voice fields, or storyFacts. The only hint is 'reference-based,' which weakly maps to the reference asset parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Create or update') and resource ('reference-based character'), and adds the purpose context 'for repeatable faceless story generation.' This is enough to distinguish it from sibling read tools like characters_get/characters_list and from story-generation tools, even though it does not name a 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?

Provides a clear context by describing the intended use case—reusable characters for faceless story generation—but does not articulate exclusions or point to alternatives such as characters_list or generation_faceless_create. The agent can infer when to use it but is not explicitly steered away from sibling 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?

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 readOnly=false, destructive=false, idempotent=false, and openWorld=true. The description adds meaningful context by calling the batch 'private' and enumerating supported source types, which the annotations do not convey. However, it omits that this is likely an asynchronous batch-producing operation and says nothing about permissions 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?

Two tightly written sentences with zero filler; the primary action and the source modes are front-loaded. Nothing is wasted.

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 for a 13-parameter creation tool that spawns a batch, the description is thin: it does not indicate the result is a batch needing status polling (clips_status_get), nor how capacity limits interact with clipCount. Adequate but with 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 100%, so all 13 parameters – including selection, durationBounds, and clipPresetId – are already documented in the schema. The description adds no parameter-level detail beyond the source-type enumeration, which the 'url' schema field already states. Baseline 3 applies.

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 ('Create a private BlitzReels clip batch') and names the two source modes (existing asset or user-provided video URL). This is clearly distinguishable from siblings like clips_candidates_list or clips_reselect, though it never names those siblings to route the agent 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 description gives no when-to-use guidance or exclusions. It does not tell the agent to resolve candidate IDs via clips_candidates_list first, nor does it mention the assetId-vs-url selection rule – that only appears in the schema parameter descriptions.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description's job is to add beyond that. It does add two genuinely useful facts: the operation is asynchronous and must be polled ('inspect until the accepted delivery file is ready'), and it can consume account credits. However it does not say what the returned export state looks like, how long renders take, or what failure/rejection looks like.

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, front-loaded sentences with no filler; the render action comes first and the polling instruction second. The middle clause ('persisted export state') is slightly jargon-y but not wasteful.

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-value detail is legitimately omitted, and the credit-spend warning covers the main operational risk. But with 2 required params at 17% coverage and no alternative-tool routing, the definition is only minimally sufficient for an expensive, idempotency-keyed render call.

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%, so the description carries the burden of explaining parameters — and it explains none of them. clipId, workspaceId, format, resolution, coverFrameSeconds, and the required idempotencyKey are all undocumented in prose, leaving an agent to guess at identifier sources and the meaning of 'existing-account-supported quality'.

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 ('Render one managed clip') plus the quality constraint tied to the account. It is distinguishable from siblings like clips_create, but it never contrasts itself with exports_start or other export-adjacent tools, so sibling differentiation is only inferred.

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 a workflow ('inspect until the accepted delivery file is ready') but never states when to use this tool instead of exports_start, exports_list, or clips_presets_list. There is no explicit when/when-not guidance or named alternative anywhere in the text.

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.

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

Annotations already flag destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds genuinely new context: the operation requires explicit user confirmation and only toggles one clip while preserving other clips and private project data. That narrowing of blast radius is exactly the kind of detail annotations cannot 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 tightly written sentences with the action front-loaded and the safety/preservation constraint immediately trailing. No filler and nothing 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?

Because an output schema exists, return values need not be described. For a destructive, open-world mutation the description supplies the key facts: confirmation requirement and preservation of other content. Only the three opaque identifiers (workspaceId, assetId, idempotencyKey) are 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 only 17%, so the description must carry the parameter burden, and it largely does not. It implies clipId and visibility (show/hide) and covers confirmPublicSharing via the confirmation sentence, but workspaceId, assetId, and idempotencyKey get no explanation at all.

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 pair and resource: 'Show or hide one identified clip on an existing public review page.' The scope (one clip, existing public review page) is precise enough to distinguish it from a general publish/unpublish, though the sibling tools clip_share_publish and clip_share_unpublish are not named.

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?

Provides one real precondition — 'after explicit user confirmation' — which is actionable. However, it never says when to use this tool versus clip_share_publish, clip_share_unpublish, or clip_share_get, so alternative selection 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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description contributes only that the read covers a 'selected source range' and workflow/delivery info, adding modest context but no auth, pagination, or scoping 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 tight sentence with no waste and the resource and scope front-loaded. It is efficient, though very sparse for a tool with two parameters and several near-identical siblings.

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 annotations cover the safe-read profile, making the bare description minimally workable. Still, it omits clipId semantics and any disambiguation from clips_get, leaving the agent to guess when this differs from the other clip read tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50% and the required `clipId` has no description at all, nor does the description clarify its format or how it relates to `workspaceId`. The description provides no parameter meaning beyond what the (partially documented) schema shows, 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 resource (one managed clip) and enumerates the facets returned: selected source range, project, workflow state, delivery information. However, it never distinguishes this from the very similar sibling `clips_get` (nor `clips_status_get`), so an agent cannot tell the two apart from the description 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, no prerequisites, and no reference to alternatives such as clips_get, clips_list, or clips_candidates_list. Given how many clip-related siblings exist, this absence is a real gap.

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 without the description. The description adds only that results carry 'current workflow state'; it says nothing about pagination limits, filter behavior, or result ordering, so it adds limited value beyond the structured fields.

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. Its only weakness is the compressed, undefined jargon ('bounded managed clips'), which costs a little clarity at the same word count.

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 the read-only/idempotent profile. What remains missing is filter semantics for a six-parameter listing tool, particularly the undocumented status filter and pagination bounds, which an agent needs to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 50%, and the covered fields are trivially documented as 'UUID string.' The description does not explain limit, offset, or the status filter at all, nor does it clarify how assetId/projectId/workspaceId scope the listing; the vague 'selected source or project' is the only hint and it is not tied to a named parameter.

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 gives a specific verb (List) and resource (managed clips) plus scope (from the selected source or project) and a hint at returned data (current workflow state). It does not, however, distinguish itself from close siblings like clips_candidates_list or clips_presets_list, and the qualifier 'bounded managed' is unexplained jargon.

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 use this tool versus clips_get, clips_inspect, clips_candidates_list, or clips_status_get, and no preconditions or exclusions. The phrase 'from the selected source or project' implies a context dependency but never says how that selection is made.

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 indicate this is a mutating, non-idempotent operation, and the description reinforces this with verbs like 'regenerate' and 'promote,' but it does not disclose side effects, prerequisites, or reversibility. For example, 'promote an accepted delivery export' implies a state change but no details are given about what is affected or whether confirmation is needed.

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 sentence that packs many operations into a comma-separated list, making it somewhat run-on but still efficient in length. It is front-loaded with 'List or inspect clips' but the long list of loosely related actions reduces clarity and structure.

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 30 parameters, 7 enums, and an output schema, the description provides only a high-level operation list. It lacks critical contextual details such as parameter dependencies, operation-specific behaviors, or typical use cases, making it incomplete for an agent to reliably invoke the 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?

With 30 parameters and only 17% schema description coverage, the description carries a heavy responsibility to explain parameters, but it names none of them. It does not map operations to required fields (e.g., which params are needed for 'repair' vs 'export') nor explain enums like selectionMode or layoutMode.

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 enumerates the tool's operations with action verbs (list, inspect, regenerate, repair, start export, promote, inspect, apply), making its broad purpose evident. It distinguishes from siblings like clips_get or exports_start by covering a wider range of clip management actions, though the list-like structure prevents a single focused purpose from being stated.

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 is provided on when to use clips_manage versus sibling tools such as clips_get, clips_create, or exports_start. The description only lists operations without explaining which to choose for a given scenario or when a more specific sibling tool would be preferable.

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 well-covered. The description adds the factual content (clipping/caption defaults) but does not disclose additional behavioral traits such as return format, pagination, or whether presets include custom user-defined ones.

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, focused sentence that immediately states the action and object. It contains no redundant phrases 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?

With an output schema present and comprehensive annotations, the description is largely complete for a simple list tool. However, it could provide slightly more contextual value by hinting at how these presets are used (e.g., 'These presets can be applied when creating clip batches'), which would help new users understand the workflow.

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 tool has zero parameters, so schema coverage is trivially 100% and the description has no parameter burden. A baseline score of 4 is appropriate since there is nothing to explain.

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 action ('List') and resource ('available clip batch presets'), and specifies the included information ('clipping/caption defaults'). This distinguishes it from sibling tools like captions_themes_list and clips_get, which serve different purposes.

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 usage is implied by the tool's name and description—if you need to list presets, this is the tool—but there is no explicit guidance on when to use it versus alternatives, nor any mention of prerequisites or follow-up actions. The description could benefit from noting that these presets are for use with clip batch creation.

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=false, yet the description adds real value: it preserves accepted clips, returns the recovery batch ID, and -- critically -- may spend account credits and must be retried with the identical idempotency key. This cost and retry context goes beyond the structured hints.

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, front-loaded with the action, followed by a side-effect/return note and then cost/retry semantics. Every sentence carries distinct information with 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?

For a credit-spending mutation tool with full annotation coverage and an output schema, the description supplies the important extra context (credit cost, idempotent retry, preservation of accepted clips). The remaining gap is the under-documented workspaceId and targetClipCount 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 description coverage is only 25%; batchId's 'UUID string' is trivial and workspaceId, idempotencyKey, and targetClipCount are undocumented in the schema. The description recovers some meaning for idempotencyKey (retry semantics) and hints at targetClipCount ('missing clip count'), but leaves workspaceId and the count's 1-30 bound unaddressed.

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 (recover) and resource ('a terminal batch's missing clip count') plus the mechanism ('persisted recovery workflow'), which is well beyond a tautology. It does not explicitly distinguish itself from close siblings like clips_repair or clips_reselect, so it stops short of 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?

Guidance is implied: use it on a 'terminal batch' with missing clips, and it warns that credits may be spent and that retries must reuse the idempotency key. However, it never states when to prefer this over clips_repair, clips_reselect, or clips_create, and gives no prerequisites.

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 adds genuine scoping context ('Changes that clip's project; preserves the other clips'), clarifying the blast radius of the destructive operation, but says nothing about reversibility, permissions, 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?

Two tight, front-loaded sentences with no filler: purpose plus examples first, scope constraint second. Well-structured, though the second clause is the only scope information and could be slightly more precise.

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. However, for a destructive, 4-parameter mutation tool with only 25% schema coverage, the description leaves the repair modes and permission/authorization requirements unexplained, which is a meaningful 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 low (25%). The examples ('screen demo', 'captions away from faces') indirectly illustrate two repairMode enum values, but the description never explains repairMode, clipId, workspaceId, or idempotencyKey — including the two required parameters — so it 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 and resource ('Request a layout repair for one managed clip') and gives concrete examples of the operation ('preserving a screen demo or moving captions away from faces'). This lets an agent understand the action, though it never explicitly contrasts with near-siblings like clips_manage, clips_recover, or batch_update_timeline_clips.

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 only implied: the agent can infer this is for fixing the layout of a single clip. There is no explicit when-to-use vs when-not guidance and no named alternative for related tasks such as batch-editing or manually updating timeline clips.

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 the safety profile (destructiveHint=true, idempotentHint=true, readOnlyHint=false), so the bar is lower. The description adds valuable non-structured context: it can consume account credits, it preserves the other clips (blast radius), and it advises reading current state before retrying. Missing only details like whether the replaced source can be recovered.

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, front-loaded with the operation and mechanism before cost and retry caveats. No filler, though the credit and retry notes are compressed to the point of mild ambiguity.

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, but with 13 parameters at 15% schema coverage and a credit-spending mutation, the description leaves several parameters unexplained and gives no detail on the auto_best mode or the layout/content hints. Adequate for the main path, thin for full complexity.

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 15% across 13 parameters, so the description must carry meaning. It maps well to selectionMode (suggestion/time_range) and suggestion/time params, but leaves layoutMode, contentTypeHint, captionsEnabled, min/maxDurationSeconds, lookId, workspaceId, and idempotencyKey entirely undocumented. 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 ('Replace the source moment for one managed clip') plus the two mechanisms ('verified suggestion or explicit time range'). This clearly separates it from siblings like clips_create, clips_get, and clips_repair without needing to open any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies the usage path via 'using a verified suggestion or explicit time range' and gives a retry prerequisite ('read current state before retrying'), but never states when to prefer this over clips_create, clips_repair, or clips_recover, nor any when-not condition. Usage is inferable rather than explicit.

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, idempotent and non-destructive behavior, but the description adds real value beyond them: it discloses that signed links are renewed, that a review widget is not opened/remounted, and that bounded polling is supported. This is useful operational context not present in 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?

Two sentences, both front-loaded with the highest-value information (what is returned, then safety constraints). No filler and no repetition of structured 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?

An output schema exists, so return values need not be explained, yet the description still summarizes the return payload (progress, ready clips, renewed links). Combined with annotations covering the safety profile, nothing an agent needs to call this correctly is 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?

Schema description coverage is 100% with only two UUID parameters, so the schema already carries the parameter documentation. The description implies a single existing batch via 'one existing batch' but adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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 a precise resource set: one batch's progress, ready clips, and renewed signed links. It also implicitly differentiates itself from the repair/recover siblings by declaring it does not recreate or repair clips, so an agent can distinguish it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context ('safe for bounded polling and widget refresh') and a negative constraint ('does not recreate or repair clips'). It stops short of explicitly naming the alternative siblings (e.g. clips_repair, clips_recover) that handle those cases.

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, idempotent and non-destructive, so safety is covered. The description adds real context beyond them: the data is pre-existing and provider-reported, results are bounded, and it explicitly disclaims import/monitoring/attribution inference, which is valuable for an agent avoiding overreach.

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: purpose/scope front-loaded, then return fields, then explicit exclusions. Every clause carries information and nothing is wasted.

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 return-field enumeration is a bonus rather than a necessity, and annotations cover the safety profile. The remaining gap is parameter semantics for a six-required-param tool with zero schema descriptions, which the description does not fill.

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 six required parameters (workspaceId, platform, range, limit, offset, search), so the description must compensate but does not. It mentions the workspace conceptually and ordering by views, but says nothing about the platform/range enums, paging via limit/offset, or the search filter, 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 (Read) plus resource (existing provider-reported engagement), scope (in the selected workspace), and ordering (sorted by views), and even enumerates the returned fields. This clearly separates it from the editorial/generation siblings, none of which are read-only analytics 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 negative constraints (does not import new data, start monitoring, or infer leads/sales/revenue) usefully bound what the tool is for, but there is no positive when-to-use statement and no named alternative sibling to route between. 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.

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

Adds information about the preview mode and optional caption removal beyond the annotations, which already indicate destructive behavior. Still, it doesn't explain the dryRun/confirmDelete workflow or other behavioral nuances, so only partially transparent.

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 redundant filler. Efficiently conveys the core functionality and primary option.

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 having annotations and an output schema, the description omits essential workflow details for a destructive tool—such as how preview (dryRun) and confirmDelete interact, the purpose of idempotencyKey, and revision handling. This is a significant gap for safe usage.

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 adds meaning to timelineItemIds (up to 100) and removeAssociatedCaptions (linked captions), but schema coverage is only 29%, leaving many parameters (dryRun, confirmDelete, idempotencyKey, expectedRevision) unaddressed. The description does not compensate enough for the low coverage.

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?

Clearly states it previews or deletes timeline items and optionally removes linked captions. The verb 'delete' and resource 'timeline items' are specific, though it doesn't explicitly distinguish from sibling 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 phrase 'Preview or delete' implies a safe preview mode before deletion, providing some usage context. However, there's no explicit guidance on when to use this tool versus alternatives, nor on when to choose preview vs actual deletion.

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. The description adds genuine context beyond them: optimistic concurrency ('Revision checked'), default preview behavior via dryRun, and the workspace-scoping constraint on the asset. It does not say what a revision mismatch does, but the added disclosure is substantive.

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, all front-loaded: action and scope first, then revision/preview behavior, then preconditions. No filler and nothing buried.

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 tool the description covers the critical agent-facing facts (concurrency check, preview default, prerequisites), and an output schema exists so return values need not be described. Minor gap in not stating the failure path on a revision mismatch, but it is close to complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 29% across 7 required params. The description clarifies dryRun (previews by default), expectedRevision (revision checked), and workspaceId (same workspace as the asset), but leaves itemId, assetId, projectId, and idempotencyKey entirely to the schema. Partial compensation for a low-coverage 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 precise verb+resource ('Replace one shot's media asset') with an explicit scope constraint ('while preserving the other timeline items'), which separates it from siblings like editor_assets_insert or update_timeline_clip. An agent can tell what it mutates without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real preconditions for use: a current editor snapshot must exist and the asset must be in the same workspace, plus dryRun previews by default. It does not name a competing sibling tool to route against, so it falls short of full when/when-not 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?

Annotations already declare this as a non-read-only, idempotent, non-destructive write. The description's added value is the phrase 'Revision checked', which signals optimistic-concurrency failure behavior beyond the schema, and the default-preview behavior. However, it does not explain what a revision conflict looks like or what the dry run returns, so the added context is thin against a mutation tool.

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 with the core action and the placement constraint front-loaded, followed immediately by the two behavioral caveats. No filler or restated 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?

An output schema exists, so return values need not be described, but for a nine-parameter, fully-required mutation the description stops short of covering layer semantics, duration handling, or the idempotency key's role. It is adequate as a headline, not complete as a spec.

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 22% across nine required parameters. The description maps loosely to assetId, startSeconds, expectedRevision and dryRun, but layerIndex, durationSeconds (nullable), workspaceId, projectId and especially idempotencyKey receive no semantic explanation in either the description or the schema, leaving the agent to guess at stacking and deduplication behavior.

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 (Insert) and enumerates the asset kinds it accepts (workspace image, generated shot, audio asset) plus the placement target (an explicit project time). That is enough for an agent to distinguish it from generic clip/media siblings, though it does not explicitly contrast with timeline_media_add or timeline_audio_add, which overlap on the 'put media on the timeline' intent.

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?

'dryRun previews by default' implies a preview-then-commit workflow, which is useful usage context, but the wording is terse and relies on the agent inferring that the first call should be a dry run. There is no explicit when-to-use or when-not-to-use guidance relative to the many adjacent timeline/clip tools in the sibling 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: optimistic concurrency ('Revision checked'), default preview behavior, and the guarantee that the rest of the project is preserved.

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 zero filler, and the core action is front-loaded ahead of the concurrency and preservation notes.

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 annotations plus description jointly cover the mutation and concurrency behavior. It is nearly complete for its complexity, though the roles of several identifiers remain 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 11% across 9 required params, so the description must compensate. It clarifies volume, fade in/out, expectedRevision (revision checked) and dryRun, but leaves itemId, projectId, workspaceId and idempotencyKey entirely unexplained in both places.

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 (adjust) and a precise scope (one item's volume and audio fades), which cleanly separates it from siblings like mute_clip_audio or timeline_audio_add. It does not name an explicit alternative, but the resource and scope are 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?

The mention that 'dryRun previews by default' implies a preview-then-apply workflow, giving implied usage. However, there is no explicit when-to-use vs when-not guidance and no routing to alternatives such as batch_update_timeline_clips for multi-item edits.

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