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

Beyond the annotations (readOnly=false, destructive=false), the description adds two concrete behavioral facts: invalid cues cause explicit failure and imports are atomic (no partial import). It does not contradict annotations, though it omits dry-run 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?

The description is two short sentences, with the primary operation first and the failure guarantee second. It is tightly written and every phrase adds 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?

For a 9-parameter tool with no output schema and sparse annotations, this description is too thin: it does not explain how parameters relate to the operation, what a successful import returns, or the role of dry_run and include_plan. Essential operational context 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?

The input schema has 9 parameters at 0% description coverage, and the description only weakly maps 'SRT text' to content and new_name. No explanation is provided for dry_run, include_plan, offset, font_size, track, or color, so the agent must guess at their semantics.

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

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

The description names the action ('Import'), the resource ('SRT text'), and the destination ('a new managed revision'), making the tool's role clear against siblings like export_srt and style_subtitles. It avoids vague language and communicates a specific operation.

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—when SRT text should be ingested as a managed revision—but gives no explicit when-to-use guidance, exclusions, or mention of alternatives such as edit_draft or export_srt. There is no way for an agent to know when not to choose this tool.

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 readOnlyHint=false and destructiveHint=false, so the description is not contradicting them. It adds important behavioral context beyond annotations: it replaces existing keyframes, and it warns that alpha animation requires exported-frame verification in the installed app. This is valuable disclosure that helps the agent understand side effects and verification needs, exceeding what annotations alone 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?

The description is two sentences, front-loaded with the core purpose and then the key behavioral caveat. Every word earns its place; there is no fluff or redundancy. It is concise and structured to immediately convey what the tool does.

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

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

Given the tool has 7 parameters, 4 required, and zero schema description coverage, the description is incomplete. It does not explain the purpose of the name/new_name parameters (likely related to renaming presets), what strength does, what dry_run means, or what include_plan does. It also does not mention return values (no output schema). An agent would need to guess or probe to correctly invoke this tool with the right values for all 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 0%, so the description must compensate by explaining parameters. It mentions the preset types (zoom_in/out, etc.) but does not explain the meaning or usage of other parameters: name, new_name, clip_ids, strength, dry_run, include_plan. The description only partially covers the preset parameter's values, leaving the other six parameters undocumented. This is insufficient given the zero 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 tool creates clip-relative motion keyframes, lists the specific preset types (zoom_in/out, pan_left/right, slide_up/down, fade_in/out, pulse), and notes that existing keyframes are replaced. This is a specific verb+resource with no ambiguity about what it does, and it distinguishes itself from sibling list_motion_presets which is about listing, not applying.

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: it is for applying motion presets to clips, and it explicitly states that existing keyframes on the same properties are replaced. However, it does not mention any alternatives or conditions when not to use this tool, such as 'use list_motion_presets to see available presets' or 'avoid if you need additive keyframes'. Since it provides clear context but no exclusions, a 4 is appropriate.

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

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

Beyond the annotations, the description clearly discloses side effects and important traits: it creates a new managed revision, never downloads resources, attaches transitions to the outgoing visual clip, and preserves the non-replaced phase for animations. This is valuable behavioral context that annotations alone do not 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?

The description is compact and front-loaded with the core purpose, followed by targeted parameter and behavior clarifications. Every sentence adds meaning, and there is no redundant restatement of the tool name or schema.

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 strong behavioral disclosure, the tool has eight parameters, five required, no parameter descriptions, and no output schema. The description does not explain critical required parameters like name, new_name, and clip_ids, nor optional controls like dry_run, include_plan, or duration. An agent would struggle to construct a fully correct invocation without additional information.

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 must compensate for undocumented parameters. It explains resource_kind and resource_name, but leaves name, new_name, clip_ids, duration, dry_run, and include_plan ambiguous. Given eight parameters, five required, this is a significant 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 uses a specific verb ('apply') and identifies the exact resource types: a transition or entrance/exit animation, with resource_kind values enumerated. It also distinguishes this from generic motion preset tools by emphasizing 'uniquely cached catalog-free' native resources.

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 when to use the tool: for outgoing-visual-clip transitions or entrance/exit animations, with resource_name sourced from list_native_resources. It does not explicitly discuss exclusions or alternatives like apply_motion_preset, but the scoping is concrete enough for an agent to route correctly.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds significant behavioral detail: it creates one new revision, performs no intermediate copies, aborts on invalid steps before any write, and does not publish/export. These traits are critical for safe invocation.

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 dense yet well-structured: it front-loads the core purpose, then enumerates step types, and ends with behavioral constraints. Every sentence adds value, and the length is justified by the complexity.

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 5 parameters and no output schema, but the description only covers the steps parameter and general behavior. It omits explanations for dry_run and include_plan, which are likely important for callers, and provides no return-value expectations. For a complex batch 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?

The description thoroughly explains the 'steps' parameter structure (listing each action and its fields), but does not clarify the other parameters (name, new_name, dry_run, include_plan). Since schema coverage is 0%, the description partially compensates but leaves a gap for four 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?

The description states a specific verb ('Apply ... save') and resource ('1-100 ordered editing steps ... ONE new revision'), and lists the allowed step actions. It clearly differentiates from single-edit and publish tools by emphasizing the batch nature and the single revision output.

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 batch editing by stating 'Apply 1-100 ordered editing steps' and notes it does not publish/export, which clarifies scope. However, it does not explicitly contrast with alternatives like edit_draft or publish_draft, leaving some inference required.

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 and destructiveHint=false, and the description's 'Detect' aligns with this safety profile. The description adds value by enumerating the specific data gathered (app, folder, features, limitations), which goes beyond the annotation. It does not mention side effects or output format, but for a read-only inspection tool this is acceptable.

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 with no wasted words. It front-loads the key verb ('Detect') and then enumerates the objects in a natural, clear order. This is efficient and complete.

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 no parameters, no output schema, and read-only annotations, the description covers the essential behavior. It could be marginally more complete by mentioning the return format (e.g., a structured list), but an agent can infer the output type from the domain and the 'detect' semantics. The description adequately captures the tool's purpose.

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 and the schema coverage is 100%, so there is no parameter burden for the description to offset. The description correctly implies no arguments are required. Nothing else is needed for parameter understanding.

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 uses a specific verb ('Detect') and names concrete resources ('installed app, local draft folder, implemented features and limitations'). This clearly distinguishes it from sibling tools like create_draft, edit_draft, or list_managed_projects, which perform active operations. An agent can immediately understand this is an environment inspection tool.

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

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

No guidance is given on when to call this tool versus others. There is no mention of any prerequisite, recommended use case, or explicit alternative to use instead. The description states only the action, not the circumstances that should lead an agent to invoke it.

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?

Discloses concrete behavior: dry_run=True writes nothing, false copies media and writes a new project; validation rejects same-track overlaps; experimental font /6 mapping. This adds significant value beyond annotations (readOnly=false, destructive=false). 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?

Compact but information-dense; the description flows logically from purpose to plan fields to clip details and execution behavior, with the main scoping sentence first. Though dense, every sentence earns its place given the complexity.

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 nested plan object and 0% schema coverage, the description covers all required semantics: field structure, defaults, validation rules, execution modes (dry_run), and behavioral constraints. It is fully sufficient for an agent to build a valid call, and no output schema exists to rely on.

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 has 0% parameter descriptions, so the description must compensate. It thoroughly documents the plan object structure, defaults, clip requirements, coordinate system, and dry_run semantics. Only include_plan is not explained, but its purpose is self-evident from its name.

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 a specific verb 'Validate/build' and resource 'a new self-contained Mac draft', and explicitly notes it does not register in the native app – a distinguishing trait from siblings like publish_draft or edit_draft. This is far from tautological and clearly identifies the tool's function.

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 creating a self-contained draft without native registration) and implies use cases from the 'does not register' note, but it does not explicitly compare to alternatives like edit_draft or publish_draft, nor state when not to use it. Some reasoning is left to the agent.

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 (readOnlyHint=false, destructiveHint=false). The description adds genuinely valuable non-obvious behavior beyond that: source always remains unchanged, gaps are preserved, no implicit ripple editing, and each operation's exact shape. This is exactly the kind of behavioral color the annotation layer cannot 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?

The description is compact — a single purpose sentence plus a dense operation list that earns its place. The operation examples are front-loaded and each token adds information. It is somewhat dense in the middle but appropriately so for a tool with a five-parameter schema and zero param help.

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 no output schema, 5 params, and a mutation-like behavior, the description covers the operation model thoroughly but omits the semantics of dry_run and include_plan — both of which shape what the tool returns. Without an output schema to fill the gap, an agent cannot predict the call's result shape or how the dry-run/plan modes behave.

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 0%, so the description carries the full burden, and it does compensate for the hardest parameter by documenting the operations array in detail (a field that is otherwise an untyped 'additionalProperties: true' bag). However, it leaves dry_run (which defaults to true — a surprising default), include_plan, name, and new_name unexplained beyond what their names imply, leaving meaningful gaps.

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

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

The description opens with a specific verb+resource phrase — 'Create a new revision of an MCP-managed project; source always remains unchanged' — which clearly defines the action and distinguishes it from an in-place edit. The operation catalog (append/remove/update/split) and the explicit 'gaps are preserved / no implicit ripple editing' statements further differentiate it from siblings like ripple_delete and batch_edit.

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 strong operational context: how to express edits (ops list), the fact that trimming/moving goes through update, and a pointer to read_managed_project for obtaining IDs. However, it never explicitly names alternatives or states when not to use this tool; the 'no implicit ripple editing' exclusion only implies that a sibling handles ripple 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 readOnlyHint=true and destructiveHint=false, so the description does not need to re-establish safety. It adds mild value by specifying 'does not write or upload files,' which rules out side effects like network uploads more concretely than the annotations do, but it adds no deeper behavioral context such as encoding details or handling of missing tracks.

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. Both the core behavior and the key non-behavior are stated efficiently, and 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?

With no output schema, the description does at least indicate the return format ('SRT text'), which is helpful. However, it omits the semantics of the optional track parameter, and there is no mention of whether the tool returns raw SRT content directly or wraps it in a structure, leaving a moderate completeness gap for a fairly simple 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 0%, so the description must compensate for the two parameters. It indirectly clarifies that 'name' identifies a managed project, but 'track' is completely unexplained: no information about valid values, what a null track means, or how track selection affects output.

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 uses a specific verb ('Return'), names the resource ('a managed project's subtitles'), and states the exact output format ('SRT text'). It also distinguishes itself from siblings by explicitly noting that it does not write or upload files, which sets it apart from tools like add_srt and publish_draft.

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

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

The phrase 'a managed project's subtitles' makes the context clear: this tool is for retrieving subtitle text from a managed project, not for native drafts or media inspection. It does not explicitly name alternatives or when-not-to-use conditions, but the context is sufficiently clear given 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?

No contradiction with annotations: readOnlyHint=false matches the creation of a PNG and adding an image clip. The description adds useful context beyond annotations by specifying a NEW PNG is generated and that the output is placed on the timeline as an image clip with adjustable duration. It does not disclose output file location or naming.

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 efficient sentences with the primary action front-loaded in the first clause. Every phrase earns its place, and the follow-up sentence about the image clip adds genuine behavioral value without bloat.

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 creation tool with no output schema, the description covers the core behavior and the timeline side-effect, which is the most important agent-facing consequence. However, it omits the meaning of path, output_dir, and dry_run, and says nothing about what is returned, leaving meaningful gaps for 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 coverage is 0% (no parameter descriptions in the schema), so the description must carry the load. It clarifies 'time' as a source time and implies the output is a PNG/image clip, but 'path' (source file identity), 'output_dir', and 'dry_run' are left semantically unexplained, leaving three of four parameters ambiguous.

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 ('Extract a NEW PNG at a source time') and names concrete use cases (inspection, covers, freeze frames). It does not explicitly differentiate from any of the 21 sibling tools, though its purpose is unambiguous enough that an agent could distinguish it from inspect_media or process_media without opening schemas.

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 intended-use context ('for inspection, covers or freeze frames') that signals when an agent should reach for this tool. However, it names no alternatives and gives no exclusions or when-not-to-use guidance, leaving comparison against siblings 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 indicate readOnlyHint=true and destructiveHint=false, and the description aligns with them. It adds useful context by specifying 'no uploads' and restricting the input to local media paths, but it does not cover error behavior or return formatting.

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 conveys the operation, the output properties, the input constraint, and a side-effect guarantee. There is 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?

Given one required parameter and no output schema, the description adequately names what the tool reads and where the input must come from. It does not specify supported media formats or invalid-path behavior, but these are minor for this narrow read-only 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?

The input schema only provides the parameter name 'path' with zero description coverage, so the description must compensate. It does so by defining the path as an 'absolute local media path,' which clarifies the required format and scope beyond the schema.

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

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

The description starts with the specific verb 'Read' and names exact output properties: duration, resolution, and audio presence. It also scopes the input as an 'absolute local media path,' which clearly identifies the tool as a read-only media inspection utility.

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

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

The description implies the tool is for retrieving media metadata from local paths and clarifies that no uploads occur, but it does not explicitly name alternatives or state when not to use it. The usage context is present but 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 and destructiveHint=false, so the safety profile is known. The description adds the crucial scope constraint (authored by this MCP, configured workspace), which is meaningful behavioral context beyond the annotations. No contradictions.

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 zero filler. It immediately states the action and scope, making it maximally efficient.

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, read-only list tool with no parameters and no output schema, the description is fully sufficient. An agent can call it correctly with the provided information, and annotations cover safety. No missing details.

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 and schema coverage is trivially 100%. Per the baseline for 0-parameter tools, a score of 4 is appropriate; the description adds no parameter details because none exist.

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 'list', the resource 'projects', and a precise scope: 'only projects authored by this MCP in its configured workspace'. This distinguishes it from sibling tools like list_native_resources and list_motion_presets without ambiguity.

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 scope 'only projects authored by this MCP' implies when to use this tool, but it does not explicitly mention alternatives or when not to use it. The distinction from sibling list tools is implicit rather than stated, leaving the agent to infer the routing.

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 and destructiveHint=false, so the safety profile is covered. The description adds a behavioral caveat about 'version-specific limits' in native exported behavior, which is useful context beyond the annotations. However, it does not elaborate on what those limits are or how they manifest.

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 with no wasted words. It front-loads the core action and resource, then adds a relevant caveat. 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?

For a zero-parameter, read-only list tool with annotations covering safety, the description is nearly complete. The only gap is the vague 'version-specific limits' caveat, which could be more explicit about what the agent should expect. However, given the tool's simplicity, this is adequate.

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

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

The tool has zero parameters, so the schema provides no parameter documentation. The description adds meaning by specifying the resource type ('local linear motion recipes') and the scope ('local'), which helps the agent understand what the tool operates on. With 0 params, baseline 4 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 states a specific verb ('list') and resource ('local linear motion recipes'), which clearly identifies the tool's function. It does not explicitly differentiate from siblings like apply_motion_preset, but the verb 'list' versus 'apply' provides implicit distinction.

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 context by specifying 'local linear motion recipes' and noting 'native exported behavior has version-specific limits,' which hints at when this tool is relevant. However, it does not explicitly state when to use this tool versus alternatives like apply_motion_preset or list_native_resources.

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 and destructiveHint=false. The description adds valuable context: no effect scripts execute, nothing is downloaded, and cache presence does not prove entitlement/playback. This goes beyond the annotations and clarifies safety and limitations.

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 compact and front-loaded with the core purpose. Every sentence adds value: the kind list, the caveat about entitlement/playback, and the safety note. 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?

For a read-only list tool with no output schema, the description covers the main purpose and safety. However, it does not describe the return format or how query/cache_root affect results, and with 0% schema coverage, an agent may not know how to use the optional parameters effectively.

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 must compensate. It explains the 'kind' parameter by listing allowed values (all, animation, video_animation, text_animation, transition), but does not explain 'query' or 'cache_root'. The description adds some meaning for one parameter but leaves the other two undocumented.

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

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

The description states a specific verb ('Find') and resource ('reviewed native video/text animations and transitions in the local effect cache'), and lists the kind values. It is clear what the tool does, though it does not explicitly differentiate from siblings like list_motion_presets or apply_native_resource.

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 checking local cache presence and notes that cache presence does not prove entitlement or playback. It does not explicitly state when to use this tool versus alternatives like list_motion_presets or apply_native_resource, but the scope is clear enough to infer.

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 are minimal (all false), so the description carries the behavioral burden. It discloses that the tool copies media into a new draft (mutation), fails on audio-only inputs, and uses the shorter of requested and source length for fixed duration. These are meaningful behavioral details beyond the annotations, though it leaves other behaviors (e.g., dry_run effects) unexplained.

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 concise at three sentences, front-loading the main action. However, some phrasing is ambiguous ('None uses full video lengths'), which could be clearer. It earns points for brevity and structure but loses some for clarity in phrasing.

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 10 parameters and no output schema, the description is severely incomplete. It does not describe the effect of dry_run, include_plan, track, or the return value. An agent would struggle to correctly set parameters without additional information. The description covers only a fraction of the tool's behavior, making it inadequate for a tool of this 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 0%, so the description must compensate for parameter meaning. It only hints at duration behavior but does not explain key parameters like name, paths, fps, width, height, dry_run, include_plan, or track. The description adds minimal value for parameter understanding, leaving most parameters ambiguous.

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 assembles local videos/photos in order, which is a specific action on a defined resource. It distinguishes itself from siblings by the act of assembling into a new draft, but it does not explicitly name alternative tools. The core purpose is unambiguous, though it could more directly contrast with similar creation tools like create_draft.

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 assembling media in order, and mentions constraints like audio-only inputs failing and duration behavior, but it does not provide explicit guidance on when to use this tool versus alternatives such as process_media or create_draft. The 'when to use' is implied rather than stated, and no exclusions or alternatives are named.

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 explicitly states that the source is untouched, that output is a new file with a unique filename, and that effects are baked in non-editable. This aligns with annotations readOnlyHint=false and destructiveHint=false and adds meaningful behavioral detail beyond 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?

The description is compact and front-loads the main purpose before listing operation details. It is somewhat dense and run-on, but contains 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?

It covers operations, ranges, booleans, reverse limit, source preservation, and downstream use, but omits behavior for dry_run and output_dir, and lacks return/result detail. Moderate completeness for a moderately complex 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?

The description adds valuable semantics for the operations object (ranges, booleans, reverse limit) but does not explain 'path', 'output_dir', or 'dry_run', which have no schema descriptions either. Coverage is partial, so the baseline remains at 3.

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 that the tool creates new media with baked local effects上手 and distinguishes it from editable native adjustments. It does not name sibling tools like batch_edit, but it does indicate that output can be reused with create_draft and montage_create, giving useful context.

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 through phrases like 'preprocessing, not editable native adjustment parameters' and notes output reuse with create_draft/montage_createOF, but it does not explicitly list alternative tools or provide clear decision rules for when to use this tool over others.

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 substantially exceeds the annotations by explaining non-obvious behaviors: existing drafts are never replaced, the index is backed up, native edits are not synced back, and the default is no-write validation. This gives an agent a clear safety and side-effect profile beyond the simple read/write/destructive 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 dense but every sentence carries useful information: purpose, prerequisites, safety guarantees, exclusions, and access requirements. It is efficiently front-loaded with the core action and then provides constraints in a compact block.

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 prerequisites, behavioral guarantees, and exclusions, which is strong for a tool with no output schema. It is slightly incomplete regarding what the tool returns on success/failure, but this is not essential for selecting and safely invoking 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 0% schema description coverage, the description compensates well for draft_root by specifying it must be an absolute existing com.lveditor.draft folder with root_meta_info.json, and for dry_run via 'defaults to no-write validation.' However, the required 'name' parameter is not explained, leaving a small semantic 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 starts with a specific verb and resource: 'Add a managed revision as a NEW native draft and register it on Jianying's home page.' This clearly distinguishes the tool from siblings like create_draft or edit_draft by emphasizing native publication registration rather than generic creation or editing.

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 concrete when-to-use context: prerequisite folders, the need to fully quit Jianying, and keeping it closed until publication finishes. It also states what the tool does not do, such as launching the app or exporting video, but it does not explicitly name alternative sibling tools for 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 cover read-only safety. The description adds value by detailing return behavior: compact summary, paged clip IDs/timing, view=full returning complete plan, and a limit constraint. This goes beyond the annotations and informs the agent about pagination and output format, though it doesn't describe the summary's structure or offset 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?

The description is three short sentences with no filler. It front-loads the main purpose ('Read a compact summary') and then efficiently conveys view options and constraints. Every sentence adds value, and it's well-structured for quick parsing.

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 read tool with 5 parameters and no output schema, the description covers the main use cases: views, pagination limit, and filtering. It lacks details on offset, the content of the default summary view, and possible other views, but overall it's reasonably complete given the tool's simplicity and the annotations covering safety.

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 must compensate. It explains view modes, limit<=200 constraint, and track filter, adding meaning to those parameters. It doesn't mention offset, but offset is a standard pagination parameter. Overall, it clarifies key parameters and constraints, though not exhaustively.

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 reads a compact summary of a managed project, with specific view options. It distinguishes from siblings by focusing on reading a single project's summary, though it doesn't explicitly name alternatives like list_managed_projects. The verb 'read' and resource 'managed project' are specific enough.

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 internal usage guidance (view=clips vs view=full, track filtering, limit<=200) but doesn't explicitly state when to choose this tool over siblings like list_managed_projects or read_native_draft. It implies usage context but lacks explicit exclusions or alternative routing.

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 and destructiveHint=false, so the safety profile is clear. The description adds that only plaintext drafts are supported and encoded drafts return unsupported, which is useful behavioral context. However, it does not describe what the returned content looks like or how unsupported is signaled.

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 no fluff. The core action and the key limitation (plaintext only) are front-loaded. It is concise and readable, though it could have added path details without much extra length.

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 a simple one-parameter read-only tool with strong annotations, the description is mostly adequate. The gap is the 'unsupported' behavior for encoded drafts: it does not state whether the tool errors, returns empty, or returns a structured notice, which an agent might need to handle the response correctly. No output schema increases the burden.

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 must compensate for the single 'path' parameter. It does state the resource is a 'directory/file', giving some hint about path semantics, but it does not specify whether the path should be absolute, relative, or point to a directory vs file. This is partial compensation but not complete.

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 ('Inspect') and the resource ('plaintext native draft directory/file'), and explicitly notes it does not change anything. It is distinguishable from siblings that write or apply changes, though it does not name any specific sibling alternative.

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 context that it is for inspection without modification, implying it should be used over editing tools, but it does not explicitly state when to use it vs alternatives or when not to use it. The 'without changing it' clause helps but is not a full usage guideline.

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 only indicate read/write and destructive characteristics; the description adds meaningful behavioral context by explaining that ALL clips become gapless and that other tracks remain unchanged. This goes beyond what the annotations or schema communicate.

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, tight sentence with no filler. The core action is front-loaded and every part of the sentence adds useful information about scope and side effects.

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 7-parameter mutation tool with 4 required parameters, no output schema, and zero parameter descriptions. A one-sentence overview is insufficient: the agent cannot know what 'name' and 'new_name' mean, or that 'dry_run' defaults to true, which may prevent the operation from actually executing.

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%, and the description only indirectly clarifies 'track' and 'clip_ids'. It provides no explanation for required parameters like 'name', 'new_name', or for behavior-affecting parameters like 'dry_run' and 'include_plan', leaving the agent to guess.

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 a specific verb and resource: reorder all clips of one track into a gapless sequence. It also distinguishes scope by noting 'ALL clips' and that other tracks remain unchanged, which separates it from siblings like ripple_delete or batch_edit.

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 the tool: when reordering all clips on a single track. However, it does not explicitly state when not to use it or name alternatives, so the usage guidance is implied 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?

The description clearly implies a destructive effect by deleting intervals, trimming clips, and closing gaps, yet the annotation destructiveHint is false. This is an annotation contradiction and is actively misleading to an agent evaluating call safety.

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 brief, front-loaded with the primary effect, and adds only relevant caveats. It is trimmed and readable, though it sacrifices too much information for the parameter count and complexity involved.

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 no output schema, no parameter descriptions, and sparse annotations, the description is not complete enough for an agent. It explains the core operation and one edge case, but leaves dry_run, include_plan, return behavior, error states, and up-front conditions undocumented.

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

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

Schema description coverage is 0%, and the description does not explain any of the six parameters. Required fields like name, new_name, start, and end remain ambiguous, especially new_name, which is unintuitive for a delete operation.

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 action and resource: deleting a timeline interval from all tracks, trimming crossing clips, and closing the gap. This is clear and distinct from siblings like reorder_track or apply_motion_preset, but it does not explicitly differentiate itself from similar edit/delete 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 does not say when to choose ripple_delete over sibling tools, what prerequisites apply, or in which context ripple deletion is appropriate. The caveat about animated intervals is a limitation, not usage guidance.

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

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

The description adds substantial behavior beyond the annotations: features merge per group for transform/style/keyframes while others replace, passing null removes a group, keyframes use clip-relative seconds with linear interpolation, and circle width defaults compensate aspect ratio. It also discloses the 'new revision' behavior, which is not visible from the schema or 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 dense but well-structured: a one-sentence summary is front-loaded, followed by semicolon-separated group specifications. Every section adds necessary detail, though the volume of technical field lists makes it long and heavy to parse.

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 complex nested-object tool with no output schema and sparse annotations, the description covers the main content model, merge/replace semantics, removal via null, resource resolution, and keyframe interpolation. It is incomplete only in that it omits explanations of dry_run/include_plan and does not specify what the tool returns or how a new revision is named.

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 must compensate. It thoroughly documents the 'features' object's structure, field names, units, defaults, and nesting. However, it does not explain top-level parameters like dry_run, include_plan, name, new_name, or clip_ids, leaving some parameter semantics to the agent to guess.

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 first sentence states a specific action ('Apply advanced controls') on a specific resource ('selected clips') with an important scope qualifier ('in a new revision'). The detailed group list (transform, crop, text_style, keyframes, etc.) clarifies what 'advanced controls' means and distinguishes this from sibling tools like apply_motion_preset or style_subtitles.

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 by enumerating the supported feature groups and gives one prerequisite ('Resolve downloaded native resources first'), but it does not explicitly state when to prefer this tool over alternatives like apply_motion_preset or batch_edit. There are no exclusions or 'instead of' notes, leaving the choice of tool partly 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 are minimal (readOnly=false, destructive=false), and the description adds meaningful behavior: the operation is batched, scoped by track or clip IDs, and applied in a new revision, signaling a non-destructive update flow. It does not contradict the annotations, and the 'new revision' detail provides useful safety context.

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 packs the core action, target scope, fields affected, and safety-related revision behavior. There is no filler or redundancy, and the most important information is front-loaded.

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 styling and targeting details, but with 7 parameters, a nested style object, no output schema, and no parameter descriptions, important gaps remain such as what name/new_name mean, what include_plan does, and whether dry_run prevents actual changes. It is adequate but not fully 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?

With 0% schema description coverage, the description must compensate, and it partially does by naming style fields (font_size/color/x/y) and the targeting parameters (track, clip_ids). However, the required name and new_name parameters remain ambiguous, and dry_run/include_plan semantics are left entirely to inference.

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 ('Batch update'), a specific resource ('subtitle font_size/color/x/y'), and a targeting mechanism ('by track or clip IDs'). This clearly distinguishes it from generic siblings like batch_edit or edit_draft and makes its scope immediately apparent.

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 a clear usage context: batch restyling subtitles with either track-level or clip-level targeting. It does not explicitly name alternatives or exclusion criteria, so it stops short of 5, but an agent can confidently select this tool for subtitle styling work.

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