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

Annotations only declare the safety profile (not destructive, non-idempotent); the description adds meaningful behavioral context beyond them: it is experimental, depends on the QE DOM, fails cleanly when APIs are missing, and self-verifies via isAdjustmentLayer and placement readback. This is rich disclosure for 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 dense sentences with the experimental/QE caveat front-loaded and no filler. Slightly technical but every clause 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 described, and the description covers the failure mode, dependency, and verification behavior. Complete enough for an agent to call it and anticipate the QE-API failure path.

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 one parameter and 100% schema description coverage, the schema already documents track_index (video track, default 0). The description adds only that placement is at the playhead, which is contextual rather than parameter syntax, so baseline 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?

States a specific verb+resource ('add an adjustment layer') plus placement scope ('at the playhead on the specified track'), which cleanly distinguishes it from siblings like add_track, add_transition, and get_clip_adjustment_layer.

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 refusal condition ('Refuses when the host lacks the QE APIs') is a useful prerequisite that tells the agent when this call will not work, but there is no explicit guidance on when to prefer this over alternatives or what to do instead. 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 declare the safety profile (non-destructive, non-idempotent, closed-world), so the description need not restate it. It adds nothing behavioral, though – it does not say whether existing keyframes are merged, replaced, or appended, which is material for a mutation on a clip's audio automation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no wasted words. It is efficient, though arguably terse given the operation modifies clip automation.

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 a rich input schema, an output schema, and annotations covering the safety profile, the definition is largely sufficient for correct invocation. The remaining gap is what happens to pre-existing keyframes, which is minor against the structured data already present.

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

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

Schema description coverage is 100%, so the schema fully documents node_id, time_seconds, and level_db (including the +15 dB cap). The description adds no parameter meaning beyond the schema, so the baseline of 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?

The description states a specific verb (add) and resource (audio level keyframes) plus the outcome (fades or level changes). It distinguishes the audio-specific nature from the generic add_keyframe sibling, though it never names 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?

Usage is implied by the stated goal ("to create fades or level changes"), which tells the agent roughly when this applies. However, no alternatives are offered – it does not contrast with adjust_audio_levels, set_clip_volume, or the generic add_keyframe, so the agent must infer which to pick.

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, idempotentHint=false), so the description's added value is the schema-vs-value distinction, which is genuinely useful. It stops short of stating behavior on duplicate field names, required project state, or permissions, so it's strong but not exhaustive.

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, front-loaded with the action and its scope, followed by the corrective routing. No wasted text.

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 description resolves the main ambiguity (schema definition vs value assignment). Only minor gaps remain, e.g. uniqueness/error behavior for the new field.

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% and all three required params are self-documented (including the field_type enum mapping in the schema). The description adds no format or constraint detail beyond the schema, 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+resource ('Add a custom metadata field to the project's metadata schema') and immediately scopes it as a schema/column definition only, which distinguishes it from value-writing tools like set_metadata.

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?

Explicitly states when NOT to use it ('it does not set a per-item value') and names the alternatives ('set_metadata field_name/value or complete Project Metadata XML with readback') for updating a value. Routing is unambiguous.

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-read-only, non-idempotent, non-destructive write. The description adds real value beyond them: it discloses that the receipt warns when the keyframe time falls outside the clip's visible range, and it scopes the verification to stored parameter data only.

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 action front-loaded and no filler. The trailing scope caveats are brief and each carries information, though the third sentence is slightly dense.

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

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

An output schema exists, so return values need no explanation. For a write tool with annotations already covering the safety profile, the description adds the warning behavior and the verification boundary, leaving little an agent needs 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%, so all five parameters are already documented in the schema. The description alludes to time semantics ('outside the clip's visible range') but adds no syntax or format 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 and resource ('Add and read back a keyframe on an effect property'), which is distinct from siblings like add_audio_keyframes (audio) and get_keyframes (read-only). It is clear without explicitly naming an 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 scope note ('verifies stored parameter data only; render/playback verification remains host-dependent') implies the intended context, but it never states when to use this over set_keyframe_interpolation, get_keyframes, or add_audio_keyframes. Usage is inferable, not 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=false, idempotent=false, destructive=false, but the description adds real behavioral context beyond them: the QE DOM experimental status, that undoStackIndex movement does not prove reversibility, that each attempt protects an engine undo boundary, and what undoTracked:false means. This is valuable disclosure, though the jargon is dense.

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 purpose is front-loaded and correct, but the experimental/undo caveat is verbose and uses unexplained internal terms (QE DOM, undoStackIndex, undoTracked) that consume space without clearly helping an agent decide or act. Some of it could be tightened.

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 return values need not be explained, and the safety profile is covered by annotations. The description fills the remaining gap by flagging the experimental nature and undo-tracking caveat, leaving only minor ambiguity about clip vs sequence routing.

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 six parameters are already documented with types, enum-like color values, and the node_id alternative. The description merely restates the read-back fields (name, comments, color, duration) and adds no syntax or format detail 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?

States a specific verb and resource ('Add a marker') plus its two targets ('active sequence or a clip'), and the read-back of name/comments/color/duration. It does not explicitly name sibling alternatives like add_marker_to_project_item or add_markers_batch, 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 body gives no explicit when-to-use guidance; the route to clips is implied through the node_id parameter rather than stated in the description. The alternative tool (add_marker_to_project_item) is named only inside the schema, not in the description itself.

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?

Despite annotations already declaring the non-read-only, non-destructive, non-idempotent profile, the description adds substantial non-obvious behavior: pre-write validation and range-checking, read-back of marker count and times, fail-closed on mismatch, and an EXPERIMENTAL QE boundary that refuses Undo/Redo crossings by default and reports unknown protection for unreadable history. It even flags a limitation (no native marker reversal verification), which is exactly the kind of caveat 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?

Purpose and scale are front-loaded in the first sentence, verification semantics follow, and the experimental QE caveat is clearly separated. It is dense but each clause carries operational weight; 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?

For a mutation tool with full annotations and an output schema (so return values need not be explained), the description covers validation, failure mode, and Undo/Redo safety adequately. The remaining gap is sibling routing — it never tells the agent when the batch tool is preferable to add_marker or add_marker_to_project_item.

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 all five parameters (including nested marker fields and the node_id/allow_beyond_end/skip_existing_within_frames semantics) are fully documented in the schema. The description restates the 200-item cap and range-checking but adds no syntax or format meaning beyond what the schema provides, so the baseline 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?

States a specific verb and resource with scope: 'Add up to 200 sequence or clip markers in one verified CEP request,' and parenthetically lists the workflows it serves (beat grids, chapters, silence reviews, client notes). The batch/verified framing distinguishes it from single-marker siblings, though it never names add_marker explicitly as the single-marker 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 parenthetical use cases imply when to reach for this tool, and the node_id schema note points at add_marker_to_project_item for the Premiere 25.2.3 limitation. But the description itself gives no explicit when-to-use or when-not guidance relative to add_marker, add_marker_to_project_item, or the plan_*_markers siblings, leaving selection largely 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 cover the safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds significant context beyond them: it records an observed marker boundary for guarded Undo/Redo, that crossing it is refused by default, and that unreadable history yields unknown protection. This is useful, non-obvious behavioral disclosure, though the QE jargon is dense and its practical impact could be spelled out more plainly.

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?

Purpose is front-loaded in the first clause, followed by a dense but purposeful behavioral sentence. It is appropriately short, though the QE sentence leans on internal jargon that reduces immediate readability rather than wasting space.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. Combined with 100% schema coverage, the description is complete enough to call the tool, with the only real gap being the missing routing guidance versus the marker siblings.

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 7 parameters (including the type enum and duration semantics) are already documented structurally. The description adds no parameter-level meaning beyond that, so the baseline of 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 clear verb+resource ('Add a marker to a project item') and clarifies the target as a 'source clip marker' via parenthetical, which helps distinguish it from timeline/sequence marker siblings. However, it never names add_marker or add_markers_batch or explains how this differs from them, leaving sibling differentiation to inference.

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 '(source clip marker)' parenthetical implies when this tool applies (project-item/source context), but there is no explicit when-to-use, when-not-to-use, or pointer to add_marker/add_markers_batch for the alternative scope. Usage is only implied.

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 discloses a critical behavioral fact beyond the annotations: the tool cannot perform its advertised action because of missing API support. This prevents an agent from attempting an unsupported operation and directs it to supported workflows. It does not contradict any annotation.

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: the unavailability and reason come first, followed by the two alternative routes. Every sentence earns its place with no wasted wording.

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 an unavailable tool with an output schema and annotations present, the description provides everything needed: why it cannot be used and exactly where to go instead. Nothing an agent needs in order to avoid or replace this tool 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%, so the schema already documents all four parameters in detail. The description adds no parameter-specific guidance beyond the schema, 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 explicitly states that the tool is unavailable and explains why: Premiere does not expose a supported scripting API for creating caption clips from raw text. It also names the correct siblings for the two relevant use cases, so an agent can immediately tell this tool is not the right choice.

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 gives explicit routing: use add_title for on-screen titles from plain text, and import an .srt/.vtt with create_caption_track for captions. This is exactly the when-to-use information an agent needs to choose an alternative.

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 declare the mutation/safety profile (readOnly=false, idempotent=false, destructive=false); the description adds substantial behavior beyond that: Premiere-built templates get text baked into a verified copy because no writable text exists, After Effects templates are written by position and read back with enumerated verification outcomes (verified/mismatch/missing_property/committed_unverified), and the clip is trimmed to duration_seconds with length read back.

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?

Four sentences, front-loaded with the core action and default, then branching by template kind. Every sentence carries information, though the verification-status enumeration is dense and could be trimmed slightly without loss.

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-value explanation is correctly omitted, and the description covers the complex kind-dependent write/verify semantics that an agent could not infer. It is nearly complete for a 6-parameter mutation tool, missing only explicit placement interaction with existing tracks.

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% and the schema already documents every default, the text-vs-lines exclusivity, and the template/track/start/duration meaning, so the baseline is 3. The description adds only a marginal concrete example (a lower third's name and role for the ordered lines) and restates the default template, not enough to materially exceed 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 names a specific verb+resource ('Add an on-screen title from plain text using a stock Essential Graphics template') and immediately scopes it to Premiere-shipped templates, which separates it from sibling tools like import_mogrt, add_text_overlay, and add_custom_metadata_field. An agent can pick this tool over its neighbors without opening 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 explicitly routes the agent to list_stock_titles to inspect templates/kind/line counts and to export_frame to confirm the render, and it distinguishes the two template kinds by behavior. It does not, however, state when to prefer this over add_text_overlay or import_mogrt, so the alternative-selection guidance is partial rather than complete.

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 real behavioral context beyond the annotations: Project presets are refused before Premiere is contacted, AME encodes from a scratch project copy, and start_batch triggers every ready AME job including unrelated ones. This is meaningful disclosure for a non-idempotent, non-destructive mutation, though it does not cover auth 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?

The purpose is front-loaded and the whole thing is short. However the sentence 'Same as Project presets are refused before Premiere is contacted' is garbled and reads like a broken copy-paste, hurting clarity despite the brevity.

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 annotations, a 100%-covered schema, and an output schema present, the description supplies the key gotchas an agent needs (saved project requirement, .epr preset prerequisite, scratch-copy behavior, batch side effect). It is nearly complete, missing only explicit sibling routing.

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

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

Schema description coverage is 100%, so the schema already documents output_path, preset_path, and start_batch. The description reinforces preset_path and start_batch semantics but adds little that the schema does not already state, so the baseline 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?

States a specific verb+resource: requesting an Adobe Media Encoder render-queue handoff for the active sequence. An agent understands exactly what the tool does. It does not explicitly differentiate from siblings like start_batch_encode or encode_project_item, 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?

Provides prerequisites (saved project, .epr preset_path) and explains the start_batch opt-in, which implies when to use the flag. However it never names an alternative tool or states when NOT to use this versus start_batch_encode or encode_project_item, so 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?

Goes well beyond the annotations, disclosing that QE razors a spanning clip, that tail preservation is only an attempt, that the result may be reported as committed_unverified, and that scope 'target_tracks' desyncs other tracks. This is exactly the kind of side-effect/auth/verification context that annotations (readOnly=false, destructive=false, idempotent=false) cannot carry. Note mild tension: the razor/desync side effects sit close to the line of destructiveHint=false, but since no data is deleted the annotations are not formally contradicted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then caveats in order of importance. Some experimental framing ("attempt to preserve its tail", committed_unverified mechanics) is dense but each clause conveys a distinct behavioral risk, so little 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?

With annotations present and an output schema covering the committed_unverified return, the description supplies the missing behavioral context (razoring, tail displacement, desync tradeoff). Only a brief note on sibling routing is absent, which is a minor 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 coverage is 100% and each parameter is already documented, including the scope enum with its desync warning. The description's scope note largely restates that, so it adds little beyond the schema; a baseline 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?

States a specific verb+resource ("Insert a project item at a timeline position"), and adds experimental QE razor/tail detail that distinguishes it from plain inserts. It does not explicitly differentiate from nearby siblings like batch_add_to_timeline or insert_from_source, but the purpose is unmistakable.

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 one conditional ("Pass scope 'target_tracks' to ripple only the named pair") but never states when to prefer this over batch_add_to_timeline, insert_from_source, or overwrite_from_source. Usage is implied rather than routed.

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 discloses substantial behavior beyond the annotations: experimental QE sync-lock handling may ripple or split earlier placements, the tool preflights items and tracks, and it verifies placements in the final sequence. It also explains that changed placements return 'committed_unverified' with observed final positions.

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 sentences and front-loads the core purpose before caveats and verification behavior. Each sentence earns its place, though the final sentence is dense and could be slightly more 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?

For a complex batch-edit tool with an output schema and annotations covering safety, the description provides the key operational caveats: experimental sync-lock ripple/split behavior, preflight validation, final verification, and the committed_unverified status. Nothing critical for correct invocation appears to be 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%, so the baseline is 3. The description reinforces 'up to 32 project items' and 'insert-edit semantics,' but adds no parameter-level detail beyond what the schema already documents for the clips array.

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 with scope: 'Insert up to 32 project items with insert-edit semantics in one validated CEP request.' It immediately distinguishes the tool as a batch operation limited to 32 items, setting it apart from single-item siblings such as add_to_timeline.

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 by the batch scope and 'insert-edit semantics,' but the description never explicitly says when to choose this tool over add_to_timeline or other insertion tools. No when-not or alternative guidance 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 readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is known. The description usefully adds that the call fails if Premiere cannot add the exact requested count (an all-or-nothing semantic), which is not derivable from annotations, but it says nothing about permissions, how the new track is inserted into the stack, or effects on existing 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?

Two short sentences, front-loaded with the core action, with no filler. Slightly under-specified rather than verbose, but structurally 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. Still, for a mutation tool with a similarly-named sibling (add_tracks) and no coverage of insertion placement or prerequisites, the description leaves gaps an agent would need filled to call it confidently.

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% and both parameters (track_type enum, count with default) are fully documented in the schema, so the baseline is 3. The description's 'video or audio' and 'exact requested count' merely restate schema content rather than adding format or constraint detail.

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

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

States a specific verb and resource ('Add ... tracks to the active sequence') and scopes the target sequence and track kinds (video/audio). It does not, however, distinguish itself from the closely-named sibling 'add_tracks', which leaves a real ambiguity for an agent choosing between 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 gives no when-to-use guidance, no prerequisites (e.g. an active sequence must exist), and no indication of when this tool is preferred over 'add_tracks' or other track tools. Only an error condition is mentioned, which is a behavioral note rather than 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?

With annotations declaring a non-read-only, non-idempotent mutation, the description adds critical behavioral detail beyond the structured hints: it verifies that the active sequence gained the exact requested counts and explicitly reports when new tracks are inserted at index 0 and shift existing tracks upward. That insertion-position side effect is exactly the kind of behavioral context an agent needs before invoking the 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?

The description is a single front-loaded sentence built around the primary action, with each clause earning its place by adding verification and insertion-position behavior. There is no repetitive or filler content.

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 that an output schema exists and the input schema is fully documented, the description supplies enough behavioral context to invoke the tool correctly, especially the index-0 insertion and shift behavior. It remains slightly incomplete because it offers no guidance on when to choose this tool over the singular add_track sibling.

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

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

Schema description coverage is 100%, so the schema already fully documents all four numeric track-count parameters, including their default values. The description only generically mentions video and/or audio tracks and does not add syntax or format meaning beyond the schema, making the baseline 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 and resource: add video and/or audio tracks. It distinguishes the plural track-adding action from broader timeline editing, though it does not explicitly differentiate itself from the sibling add_track or delete_track 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 explains what the tool does but never states when to use it instead of alternatives such as add_track, delete_track, or move_clip_to_track. No prerequisites, exclusions, or selection conditions 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 declare this is a non-read-only, non-destructive, non-idempotent, closed-world operation. The description adds valuable behavioral context beyond that: it flags the operation as EXPERIMENTAL/undocumented QE DOM and notes that it reads the transition back from the sequence track, implying verification behavior. It still omits failure modes and permission requirements, 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 short sentences are front-loaded with the experimental status and the core action. Every phrase carries information; 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?

With a rich input schema, annotations, and an output schema, the description covers purpose, experimental risk, and read-back behavior. It remains slightly incomplete on sibling selection among add_transition, add_transition_to_clip, and batch_add_transitions, but enough 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 100%, so the schema already documents all four parameters including defaults. The description adds no parameter-level syntax, format, or constraint detail beyond what the schema provides; baseline 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?

States a specific verb (Add), resource (video transition), and placement (between two clips at a cut point), which is more specific than a generic 'add transition'. However, it does not name or explicitly contrast with close siblings like add_transition_to_clip or batch_add_transitions, so sibling differentiation is left to inference.

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 scenario—inserting a video transition at a cut point—but offers no explicit when-to-use guidance, prerequisites, or exclusions. It does not point to add_transition_to_clip, batch_add_transitions, or list_available_transitions as alternatives, so the agent must infer tool selection.

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 mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds genuinely new context: the tool relies on an undocumented/experimental QE DOM surface and performs a read-back of the requested placement after writing, which hints that verification is built in. It still does not say what happens if a transition already exists on the edge or on failure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that leads with the experimental caveat and then states the operation and its read-back behavior. No filler, no redundant restatement of the title.

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

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

An output schema exists so return values need not be explained, and the annotations cover the safety profile. The description supplies the experimental warning and placement scope, but omits prerequisites such as where transition_name values come from (list_available_transitions) and what the read-back returns on failure, leaving a small gap for a mutation tool.

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

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

Schema description coverage is 100%, so node_id, position, transition_name, and duration_seconds are already documented in the schema. The description restates the start/end/both placement semantics already captured by the enum and adds no new parameter meaning, so the baseline of 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 ('Add a transition to a specific video clip') and scopes the target to the clip's start, end, or both edges. It is clear what the tool does, but it never names or contrasts with the obvious siblings add_transition or batch_add_transitions, so an agent must infer which one 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 explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as add_transition (single, non-clip-targeted) or batch_add_transitions (multiple clips). The only contextual signal is 'EXPERIMENTAL (undocumented QE DOM)', which warns about stability but does not tell the agent when this tool 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 a non-destructive, non-idempotent write operation (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds a useful behavioral boundary—it does not read or change Essential Sound Amplify automation—but says nothing about reversibility or exactly which clip properties are affected.

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 action and scope exclusion. Every sentence earns its place; there is 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 simple two-parameter mutation with rich annotations and an output schema, the description states the action and an important exclusion (Essential Sound Amplify automation). Its only notable gap is failing to differentiate itself from sibling volume 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 description coverage is 100%, and the schema already explains that level_db uses dB with 0 as unity and negative/positive semantics. The description repeats 'in dB' but adds no further parameter meaning, so 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?

Names a specific verb (Adjust) and resource (a clip's Volume > Level in dB), making the operation clear. However, it does not distinguish this tool from sibling set_clip_volume or set_clips_volume, which likely perform a similar level change on a clip or 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?

The description gives no when-to-use guidance or alternatives. Its only limitation statement ('Does not read or change Essential Sound Amplify automation') is a scope exclusion, not routing advice, so an agent cannot tell when to choose adjust_audio_levels over set_clip_volume.

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/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it never calls a model (deterministic), never persists transcript text (privacy), and never modifies Premiere. That is real added context, though return-value characteristics are left to the output schema.

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 purpose and followed by the negative guarantees. No filler; 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 annotations, a rich 100%-covered schema, and an output schema, the description supplies the remaining pieces an agent needs (determinism, no persistence, no Premiere mutation). It is complete for invocation; it stops short of describing expected output shape or pitfalls like oversized segment arrays.

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

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

Schema description coverage is 100%, so the schema documents all four parameters, including the revision pattern and default minimum_silence_seconds. The description only echoes 'revision-bound transcript segments and optional local silence ranges' without adding syntax or format detail beyond the schema, which is the baseline-3 case.

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 (analyze) and resource (dialogue-edit candidates), and pins down the inputs as caller-supplied, revision-bound transcript segments plus optional silence ranges. It's clear what the tool does, though it does not name the adjacent siblings (plan_filler_word_removal, plan_pause_tightening, detect_silence) that an agent might confuse it with.

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 by the required inputs (you need transcript segments from get_clip_transcript_uxp), but there is no explicit when-to-use vs. alternatives guidance or exclusion criteria. The agent can infer the context but is not routed.

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 cover the safety profile (destructiveHint=false, openWorldHint=false), and the description adds genuinely useful context beyond them: that it is analysis-only using an EBU R128 filter, does not normalize audio, and does not mutate Premiere. It still does not address readOnlyHint=false / idempotentHint=false, leaving a small residual question about whether any files are written.

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, zero filler, with the measurement scope front-loaded and the analysis-only constraint appended. Every clause carries information the agent can act on.

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 enumerated, and the description correctly focuses on scope and the non-mutating guarantee. It could go further by naming the normalization sibling it is meant to precede, but nothing essential for correct invocation 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%, so all five parameters (media_path, target_lufs, tolerance_lu, project_item_id, max_true_peak_dbfs) are already documented. The description mentions the measured metrics but adds no format or interpretation guidance for the target/tolerance/peak parameters, so the baseline of 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?

Names a specific verb (Measure) and concrete outputs (integrated loudness LUFS, loudness range LU, true peak dBFS) plus the source (local media file). The mention of FFmpeg's EBU R128 filter further distinguishes it from sibling tools like normalize_loudness_file or validate_delivery_conformance.

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?

Explicitly frames the tool as analysis-only and rules out normalization and Premiere changes, which steers the agent away from the wrong sibling. It stops short of naming the alternative (normalize_loudness_file) or the conditions under which a user would need analysis versus normalization.

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 claims 'Read-only delivery preflight' while the annotations declare readOnlyHint=false, idempotentHint=false and destructiveHint=false — a soft inconsistency worth flagging, since the server evidently considers the tool non-read-only (it likely spawns an FFmpeg decode process). Beyond that claim the description adds no behavioral context: no mention of cost/runtime, temp-file or decode side effects, or sample_seconds impact on execution time.

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, zero filler, with the classification taxonomy up front and the usage framing trailing. Nothing to trim.

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

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

An output schema exists, so return values need not be explained, and the enumerable result categories are given inline. The only gap is the unstated execution profile implied by sample_seconds and the unresolved read-only framing.

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 media_path and sample_seconds (1-300s, default 30) are already fully documented in the schema. The description adds nothing about parameter semantics; baseline 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?

Specific verb ('Classify') plus resource ('decoded video frames') and an enumerated set of outputs (progressive, top-field-first, bottom-field-first, mixed, undetermined), with the underlying mechanism named (FFmpeg idet). This distinguishes it clearly from siblings like set_sequence_field_type (a mutation) and analyze_video_qc (broader QC).

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?

'Read-only delivery preflight' implies the context of use, but there is no explicit when-to-use/when-not or routing to alternatives such as inspect_media_streams or analyze_video_qc, which also surface media characteristics. 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?

The description asserts 'Read-only: it does not contact Premiere or modify the file,' but the annotations declare readOnlyHint=false, directly contradicting the claim that the operation does not modify. This is a genuine inconsistency the agent cannot resolve from the definition, so it must be flagged even though the FFmpeg/no-Premiere detail is otherwise informative.

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 what is analyzed and followed by the side-effect profile; no filler or repetition of the title. Every clause earns its place.

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

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

An output schema exists, so return values need not be explained, and the description covers the analysis target, mechanism, and side-effect intent for a 3-parameter tool. Its completeness is undercut only by the read-only claim conflicting with the annotations, which leaves the true side-effect profile ambiguous.

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% and all three parameters (media_path, minimum_black_seconds, minimum_freeze_seconds) are documented in-schema, including defaults. The description adds no syntax or format detail beyond the schema, 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 (Analyze), a specific resource (a local video delivery), and a specific target (sustained black and frozen sections). It differentiates itself from Premiere-bound siblings by declaring it works on a local file with FFmpeg and never contacts Premiere, so an agent can tell it apart from tools like verify_delivery_file or analyze_video_interlacing.

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 'local video delivery' and 'does not contact Premiere' imply this is for offline/standalone QC of an already-rendered file, which is useful framing. However, it names no alternative sibling (e.g., verify_delivery_conformance, verify_delivery_file) and states no explicit when-to-use or when-not-to-use condition, leaving routing 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?

Adds meaningful behavior beyond the annotations (readOnly=false, idempotent=false, destructive=false, openWorld=false): a confirmation is required, both hosts and file metadata are rechecked, and the token is consumed before dispatch, implying one-time non-repeatable semantics. It also enumerates what is not touched. It stops short of describing failure behavior if the token is expired or already consumed.

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; the operative action and its scope constraint are front-loaded, and each remaining sentence adds a distinct constraint (confirmation, token consumption, exclusions). No filler.

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

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

An output schema exists, so return values need not be explained. For a two-parameter, non-destructive apply operation the description covers preconditions, side effects, and exclusions well; only edge-case failure handling is left implicit.

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% and both parameters (preview_token, confirm_import) are documented in the schema, so the baseline is 3. The description reinforces 'requires confirmation' and the one-time token nature but adds no syntax, format, or constraint detail beyond what the schema already provides.

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: import exactly one previewed completed AE render into its approved Premiere bin. The phrase 'exactly one' plus 'previewed completed' distinguishes it from preview_after_effects_render_handoff, preview_after_effects_render, and enqueue_after_effects_render at a glance.

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 context: the render must be 'previewed completed' and already have an 'approved' bin, and it states the negative scope ('Does not save, render, or change a timeline'). It does not explicitly name preview_after_effects_render_handoff as the mandatory prerequisite (the schema does), nor contrast with the sibling apply_mogrt_premiere_handoff.

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, idempotentHint=false, and destructiveHint=false, so the safety profile is partly covered. The description adds a caveat that 'a component-list readback does not verify rendered audio', which is useful beyond annotations, but it is cryptic and omits permissions, reversibility, or what the effect application actually changes.

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?

Purpose is front-loaded in the first sentence, and the remaining two sentences are short. The second and third sentences add implementation caveats about catalog lookup and verification limits, though they are somewhat jargon-heavy; no obvious filler is present.

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 need not be explained, and annotations cover basic safety. However, for a mutation tool with two required parameters, the description lacks essential context such as valid effect name sources, alternative batch tools, and what state changes after application.

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%: both 'node_id' and 'effect_name' are documented in the input schema. The description adds no extra meaning about parameter format, valid values, or how 'effect_name' relates to the catalog lookup, so 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 ('Apply') and resource ('audio effect to a clip'), which distinguishes it from the generic 'apply_effect' sibling by narrowing scope to audio. However, it does not explicitly name or contrast with any sibling tool, so an agent must infer the boundary from the tool name 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 mention of alternatives such as 'batch_apply_effect' or 'apply_effect'. The description also omits where to find valid effect names (e.g., 'list_available_audio_effects'), leaving the agent without routing information.

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, destructiveHint=false, idempotentHint=false, which tells the agent this mutates state but isn't destructive and isn't idempotent. The description adds that it revalidates identities before activation/mutation and requires exact confirmation token. It does not mention what happens if validation fails, nor does it detail the non-destructive nature (e.g., undoable?). With annotations covering safety profile, a 3 is appropriate as the description adds some but not rich behavioral 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?

Two sentences, front-loaded with the core action and key requirements. No wasted words; every clause adds necessary context (revalidation, capabilities, token, fresh preview).

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 nested-object schema with output schema present and annotations covering safety, the description provides sufficient context: it clarifies the preview requirement, the token, and the revalidation step. It could mention the capability requirement more explicitly (it says 'Requires the edit capability') and perhaps what happens on success/failure, but overall it is complete 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 description coverage is 100%, so the schema already documents all parameters in detail. The description mentions 'exact preview confirmation token' which maps to the confirmation_token parameter but adds no new syntax or format details. Baseline 3 when schema does the heavy lifting.

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: 'Apply a previously previewed compound edit'. It clearly distinguishes itself from siblings like preview_edit_plan or apply_effect by emphasizing 'compound' and 'previously previewed'. However, it could more explicitly name the sibling preview_edit_plan as the source of the plan.

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 specifies that the plan must be previously previewed and requires a 'exact preview confirmation token', implying preview_edit_plan must be called first. It also states 'changed targets require a fresh preview', giving a condition for when to re-preview. No explicit when-not-to-use guidance, but clear context.

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=false). The description adds a genuinely useful caveat that a component-list readback does not verify rendered pixels, warning the agent that apparent success is not visual confirmation. But the QE DOM catalog/exact-name probe sentence is implementation jargon that does not translate into agent-actionable 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 core action is correctly front-loaded in sentence one, but the two follow-up sentences are dense internal-implementation notes whose benefit to the caller is only partially clear. They are not pure filler (they hint at verification limits) but they are not well-explained either.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. What remains missing is routing guidance versus batch_apply_effect and any statement of failure modes (e.g. unknown effect_name), leaving the definition only minimally complete for a mutation tool.

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

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

Schema coverage is 100% and both parameters are documented in the schema, including an example effect name. The description adds no additional meaning about node_id or effect_name, so the schema does the heavy lifting and 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?

The first sentence states a clear verb+resource ('Apply a video effect to a clip'), so the agent knows exactly what it does. However, it gives no differentiation from close siblings like batch_apply_effect, apply_lut, or apply_audio_effect, leaving the agent to infer the distinction from names alone.

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

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

There is no when-to-use guidance at all. With siblings such as batch_apply_effect, apply_audio_effect, apply_lut, and apply_after_effects_render_handoff in the same family, the description never says when this single-effect tool is preferred over those 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?

Goes well beyond annotations: discloses that the scripting API cannot load LUT files, that writing a LUT path is accepted but not rendered, that the tool fails before changing the clip, and specifies testing context on Premiere Pro 25.2.3 macOS. This tells the agent not to expect side effects, consistent with destructiveHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the unavailability warning and ordered logically: limitation, evidence, consequence, then alternative. The test-methodology sentence is long, but it supports the limitation claim; overall the description is slightly verbose for a non-functional tool.

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

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

Given an output schema exists and annotations cover safety, the description supplies the critical missing context: the tool is non-functional on this backend, what happens when it is called, and the recommended manual alternative. Nothing required to decide against invocation 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%, so node_id and lut_path are already documented in the schema. The description refers generally to writing a file path to LUT asset parameters but adds no parameter-level syntax or meaning beyond what the schema provides. 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 the tool is unavailable on the CEP backend and cannot load a LUT file into Lumetri Color, which makes the actual behavior clear even though the intended action is implied by the name/title. It explains that it fails before changing the clip, but does not explicitly differentiate it from sibling color or effect 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?

Explicitly routes the agent away from this tool and names the alternative: apply the LUT in Lumetri Color > Creative > Look (Browse...). It also makes clear the tool will not work before invocation, so there is no ambiguity about when to use 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?

Annotations already declare the non-read-only, non-idempotent, non-destructive, closed-world profile. The description adds genuinely useful context beyond that: it is bounded to a disposable verification sequence, it requires explicit confirmation, and it makes 'no rendered-frame claim', clarifying that only insertion and control descriptors are verified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and scope, with no wasted clauses. The jargon ('explicit disposable Premiere verification sequence') is dense but each phrase carries scope 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 read-back of insertion and control descriptors need not be detailed. For a bounded, confirmation-gated mutation the description covers scope, precondition, and limits well.

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 preview_token and confirm_import are already documented in the schema. The description reinforces 'exactly one' and the confirmation requirement but adds no new syntax or format detail beyond what the schema provides, making 3 the correct baseline.

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 (import), a precise resource (exactly one previewed MOGRT), and the exact destination (empty track of the disposable Premiere verification sequence). This clearly distinguishes it from the sibling preview_mogrt_premiere_handoff, which produces the preview rather than consuming 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?

The description implies the tool must be preceded by preview_mogrt_premiere_handoff ('previewed MOGRT') and states the confirmation requirement. It does not spell out explicit when-not conditions, but the preconditions are clear.

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 carry the safety flags (readOnly=false, idempotent=false, destructive=false); the description adds real behavioral context beyond them: the authority requirements, the constraint that only empty explicitly named tracks are touched, and the caveat that host readback is not playback or render verification. That last point is a non-obvious limitation an agent would otherwise not know.

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 prerequisites and constraints. Nothing is redundant, though the final readback caveat is phrased cryptically enough that it costs a little readability.

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 needn't be explained, and annotations cover the safety profile. The description fills in authority, targeting, and verification caveats, leaving only the explicit naming of the required preview_*_spot source tools as a 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% with only two parameters, so the schema already documents both. The phrase 'one exact previewed ... plan' mildly reinforces the provenance requirement in the schema, but adds no syntax or format detail beyond it. Baseline 3 is correct when the schema does the heavy lifting.

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 ('one exact previewed motion-demo, product-spot, or brand-spot plan'), and the type list cleanly separates it from the generic apply_edit_plan and apply_mogrt_premiere_handoff siblings. An agent can tell which preview output this consumes 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?

Explicit preconditions are given (edit authority, filesystem authority for MOGRT, targets only empty explicitly named tracks) plus the implicit requirement that the plan be 'exact' and previously previewed. It stops short of naming the preview_*_spot tools as the required source, so selection guidance is clear but not fully routed.

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 that this is a non-readOnly, non-destructive, non-idempotent write operation. The description adds valuable postcondition behavior: it confirms the property in XMP and reports failure if it never lands there. It does not cover permissions or behavior when the property already exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the action and target, and contains no filler. The second sentence adds the critical verification and failure behavior.

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 do not need explanation. The description covers the action, target, verification behavior, and failure mode, which is complete enough for this two-parameter write tool.

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

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

Schema coverage is 100%, so both parameters are fully documented in the input schema. The description adds a 'key/value pair' framing but no additional format, validation, or usage details beyond the schema baseline.

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 (attach), resource (custom property key/value pair), target (active sequence), and verification against the XMP packet. It distinguishes the tool from generic metadata setters by emphasizing XMP confirmation and failure reporting.

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 explicit when-to-use, when-not-to-use, or alternative tools are mentioned. Sibling tools such as add_custom_metadata_field and set_xmp_metadata are not referenced, so the agent must infer when this tool 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and non-openWorld, so the safety profile is largely covered. The description adds genuinely new behavioral context: 'Local-only', implying no network/media fetch, and 'never changes Premiere', plus the scoring and fix-route output shape. It stops short of noting runtime or input-size limits for large snapshots.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the verb 'Audit' and the target, then the defect enumeration, then outputs, then the safety note. The eleven-item check list is long but each entry is a concrete, non-redundant check that helps an agent predict coverage. Slight verbosity in the enumeration keeps it from a 5.

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 deeply nested snapshot schema at 100% coverage and an existing output schema, the description supplies the remaining context an agent needs: scope (single snapshot), the breadth of detection, the output shape in prose, and the local read-only guarantee. Missing only comparison with adjacent audit tools, but that is a usage-guideline gap rather than a completeness 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%, and every one of the seven parameters (frame_rate, gap_min_frames, max_speed_percent, expected_frame_rate, flash_frame_max_frames, expected_duration_seconds, snapshot) is documented with defaults and ranges in the schema. The description adds no semantics beyond what the schema already 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 (audit) and resource (one sequence snapshot), then enumerates the eleven defect classes it detects (flash frames, gaps, overlaps, disabled clips, repeated shots, video without audio, extreme speed, invalid times, empty tracks, leading black, trailing gaps) and the outputs (0..100 score, findings with timecodes, fix routes). This is far more specific than the name alone and distinguishes it from read-only inspectors like inspect_sequence_review_report or diff_sequence_snapshots.

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 specifying that it audits 'one sequence snapshot', which signals the input precondition, but it names no alternatives and gives no explicit when-to-use or when-not-to-use guidance versus closely related siblings such as inspect_sequence_review_report, analyze_video_qc, or diff_sequence_snapshots. Usage is inferable but not spelled out.

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 non-read-only, non-destructive, non-idempotent, but the description adds real behavior the annotations cannot: it creates a NEW sequence, Premiere derives dimensions from source height, the tool then forces the requested frame size and verifies it, and the Auto Reframe effect refits afterward. This is useful operational context beyond the flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and its output shape, with no filler. The second sentence is dense but every clause carries information about the tool's internal behavior.

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 no explanation, and the description covers the creation semantics, the dimension quirk, and verification. It omits any mention of when to prefer this over simpler resize tools, which would round it out.

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 the baseline is 3, but the description adds genuine semantics for target_width/target_height by explaining Premiere's derived-sizing behavior (1080p at 9:16 yields 607x1080) before the requested size is applied.

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 ('Auto-reframe a sequence into a new sequence of target_width x target_height'), and the phrase 'into a new sequence' distinguishes it from resolution-mutating siblings like set_sequence_resolution or set_scale_to_frame_size.

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: no explicit when-to-use, when-not, or named alternative is given. An agent can infer this is for reframing (e.g., to vertical) but must decide on its own versus set_sequence_resolution or set_scale_to_frame_size.

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