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

Goes beyond the annotations by disclosing real consequences: it is a write (consistent with readOnlyHint=false) that requires fresh revisions, permanently consumes the operation IDs so they cannot be replayed, and neither undoes nor retries the underlying host edit. That is materially useful and consistent with destructiveHint=false and idempotentHint=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?

Three tight sentences: purpose first, then the revision prerequisite, then the consequences of acknowledging. No restatement of the title and 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 state-changing, revision-guarded tool with an output schema, the description covers preconditions, irreversibility of consumption, and the fact that acknowledgement is not a retry. Remaining detail (per-backend revision fields, idempotency) is fully carried by the schema.

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

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

Schema coverage is 100% and the nine parameters (including the nested expected_cep_target and idempotency_key semantics) are fully documented in the schema. The description only reinforces that the recovery and host-state revisions must be the exact latest values; it adds no format or fallback detail beyond that. 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 (acknowledge ... operation recovery) plus the precondition (user-reviewed reconciliation of uncertain execution after current-state inspection). An agent can tell this is the closure step after inspect_operation_recovery, though that sibling is never named outright.

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?

Establishes clear context: call only after inspecting current host state and after a user has reviewed the uncertain operations. The prerequisite of the exact latest recovery and host-state revisions is explicit, and 'does not undo or retry a host edit' rules out a misuse. It stops short of naming the inspection sibling or stating explicit when-not-to-call cases.

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

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

Goes beyond the annotations by flagging the tool as EXPERIMENTAL QE DOM, describing its refusal precondition, and disclosing post-write verification via isAdjustmentLayer and placement readback. It does not cover idempotency behavior (notable since idempotentHint is false while the schema exposes an idempotency_key), leaving a small gap 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 tight sentences with the EXPERIMENTAL caveat front-loaded and no filler; the refusal and verification behaviors are packed into one clause each.

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 output schema, full annotation coverage, and 100% schema descriptions, the description supplies the key extras an agent needs: experimental status, failure mode, and verification. Only the interaction with the idempotency key and expected-identity guards goes unmentioned in prose.

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 parameter meaning is already fully documented. The description only implicitly maps to track_index via 'specified track' and adds nothing about expected_cep_target or expected_project_path guards, matching the baseline 3.

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

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

States a specific verb and resource (add an adjustment layer) plus placement scope (at the playhead, on the specified track), which is enough to distinguish it from sibling insertion tools like add_title or apply_effect. It does not explicitly name an alternative, 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?

Implies usage through the playhead/track placement and discloses a hard precondition (refuses when the host lacks QE APIs), but gives no guidance on when to prefer this over related tools or when not 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), lowering the bar, but the description adds nothing beyond intent. It does not say whether new keyframes are additive or overwrite existing ones at the same time, what happens to prior automation on the clip, or how the idempotency/CEP-guard parameters change retry or failure behavior — all material 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?

One short sentence with zero filler, front-loaded with the action. It is efficient, though the brevity is partly under-specification rather than disciplined compression.

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 5-parameter mutation tool with nested keyframe objects, an idempotency key, and two optional CEP-identity guards, a single sentence is not enough. An output schema exists so return values needn't be explained, but ordering rules, overwrite behavior, and the purpose of the guard parameters are all missing.

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

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

Schema description coverage is 100%, with detailed per-field docs for node_id, keyframes, level_db bounds, time_seconds, idempotency_key and the expected_cep_target guard, so baseline 3 applies. The description adds no additional parameter meaning (e.g., whether time_seconds must be sorted or relative to clip start).

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 audio level keyframes') and adds the intended outcome ('create fades or level changes'). However, it never distinguishes this from close siblings like add_keyframe, adjust_audio_levels, or set_clip_volume, which an agent could easily 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?

No guidance on when to use this versus adjust_audio_levels (bulk level changes), set_clip_volume, or the generic add_keyframe. No prerequisites are stated, such as the clip having to be on an audio track or keyframes needing to be ordered by time.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered; the description adds useful context that the write only touches the schema, not item values. It does not say what happens on a duplicate field_name, whether a field can later be removed, or what the response confirms — gaps that matter for a schema-mutating call.

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

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

Three tight sentences with the core purpose front-loaded and the non-goal second. Minor deduction for the opaque phrase 'complete Project Metadata XML with readback', which names a workflow without saying how to reach it.

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

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

With an output schema present and 100% parameter coverage, the description needn't explain returns or field formats. It is nearly complete; only prerequisites (e.g. an open/saved project, field_name uniqueness) are left unstated, and the expected_cep_target/expected_project_path guards are covered by the schema.

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

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

Schema description coverage is 100% — field_name, field_label, field_type (with the 0-3 enum mapping), idempotency_key and both guard objects are all documented in-schema. The description adds nothing about parameters, 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 a custom metadata field to the project's metadata schema') and immediately clarifies the scope of the mutation: it creates a schema/column definition only. That distinction separates it cleanly from set_metadata, which sits right next to it in the sibling list.

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 names the condition where this tool is the wrong choice ('it does not set a per-item value') and routes the agent to the correct alternative (set_metadata field_name/value, or the Project Metadata XML path with readback). No inference is required to pick between schema definition and value assignment.

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 generic safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description earns credit by adding real behavioral information beyond that: it reads the value back as a receipt, flags when the time falls outside the clip's visible range, and explicitly scopes verification to stored parameter data rather than render/playback. It does not contradict idempotentHint=false, but it also never tells the agent that re-invocation duplicates the keyframe.

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, then the receipt warning, then the verification caveat. No filler, though the final sentence is slightly dense and could be split or trimmed for scannability.

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

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

With an output schema present, the description needn't explain the returned receipt, and 100% schema coverage handles the nine parameters including the nested guard objects. It is still slightly thin for a mutation tool with guard parameters and a sibling audio keyframe tool, 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 the schema already carries all nine parameters including property_index disambiguation, idempotency_key semantics, and the expected_cep_target guard. The description adds only a marginal hint about the time domain ('outside the clip's visible range'), which is exactly the baseline-3 case where 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?

Specific verb plus resource: 'Add and read back a keyframe on an effect property' clearly separates it from reads like get_keyframes and mutations like remove_keyframe. It implicitly distinguishes itself from the audio sibling via 'on an effect property', but never names that sibling explicitly, so the differentiation is inferred rather than stated.

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

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

The description gives no when-to-use context: it never says to reach for this instead of add_audio_keyframes, set_effect_property, or set_keyframe_interpolation, and it doesn't mention the prerequisite of inspecting the property first. The only usage-adjacent content is the out-of-range warning, which is a behavior, not routing guidance.

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

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

Annotations only declare readOnly/destructive/idempotent hints, so the description carries real added weight: it discloses that the operation is EXPERIMENTAL (QE DOM), that the undoStackIndex receipt does not prove reversibility, that an engine undo boundary is protected on every attempt, and what undoTracked:false means. These are genuine behavioral caveats an agent cannot get from structured fields. It stops short of stating permission/auth requirements or how partial failures surface in the receipt.

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 in the first sentence, which is good, but the remainder is a dense run of internal QA jargon ('undoStackIndex movement', 'observably advance the QE index', 'unverified with the created marker identity when available') packed into two long sentences. It is information-bearing but poorly parsed; it would benefit from being split and trimmed.

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

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

For a 9-parameter mutation tool with nested identity guards and an output schema, the description covers the non-obvious risks (experimental QE path, undo verification limits, tick-exact comparison). Return-value detail is rightly left to the output schema. Missing only explicit prerequisites (active sequence required, CEP vs UXP backend behavior) that the sibling set makes relevant.

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 nine parameters including color indices, duration semantics, idempotency, and the CEP guard objects. The description only marginally extends this with 'marker start and end storage are compared at exact integer ticks' and 'unsupported time writes remain unverified', which is note-worthy but does not meaningfully re-specify any parameter.

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

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

Opens with a specific verb+resource and scope: 'Add a marker to the active sequence or a clip and read its name, comments, color and duration back.' That distinguishes it from list/update/delete_marker siblings. It never explicitly names the closest alternative (add_marker_to_project_item) in the description itself; that routing only appears inside the node_id schema field.

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 'active sequence or a clip' framing implies context, and the EXPERIMENTAL/undo discussion hints at when to expect weak results, but there is no explicit when-to-use vs update_marker, list_markers, add_markers_batch, or add_marker_to_project_item guidance in the description. Usage is only implied, not 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?

Goes well beyond the annotations: all markers are validated and range-checked before the first write, the tool reads back count and each marker's time and fails closed on mismatch, and the QE Undo/Redo boundary behavior (refused by default, unreadable history = unknown protection, does not verify native marker reversal) is disclosed. These caveats are exactly the mutation-specific risks annotations cannot express.

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, use cases, and hard limits are front-loaded in the first sentence, and the safety/verification content follows in a logical order. The QE passage is dense and jargon-heavy ('records an observed marker boundary for guarded Undo/Redo'), costing some readability, but no sentence is 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 an 8-parameter, nested-object mutation tool with an output schema, the description covers verification, failure modes, idempotency, and guard refusals well enough to call it safely. It leaves the reviewed-identity guard parameters (expected_cep_target, expected_project_path) entirely to the schema, which is the main remaining gap.

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

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

Schema description coverage is 100%, so markers fields, idempotency_key semantics, and node_id refusal behavior are already documented in the schema. The description adds only the batch ceiling and sort behavior, both of which also appear in 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?

The opening states a specific verb and resource with hard scope ('Add up to 200 sequence or clip markers in one verified CEP request') and parenthetical use cases (beat grids, chapters, silence reviews, client notes). Parenthetical cases plus the singular siblings add_marker/add_marker_to_project_item make the batch-vs-single distinction inferable without opening a 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?

Usage contexts are given explicitly, and one alternative is routed: on Premiere 25.2.3 timeline clips the tool refuses and names the source time to use with add_marker_to_project_item. It stops short of stating when to prefer add_marker or update_marker over the batch, so it is clear context without full exclusions.

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

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

Beyond the annotations (which only say non-read-only, non-destructive, non-idempotent), the description discloses real behavioral traits: an experimental QE undo/redo boundary that refuses crossing, unknown protection on unreadable history, non-verification of native marker reversal, and tick-exact start/end comparison. The jargon is dense, but it materially adds failure-mode context the annotations do not carry.

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

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

The purpose is front-loaded in the first clause, which is good, but the remaining QE sentences are long and jargon-heavy ('guarded Undo/Redo', 'unreadable history records unknown protection') and reduce readability. It is not bloated with filler, but the phrasing costs clarity.

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, full annotations, and 100% schema coverage, the heavy lifting is done elsewhere; the description adds purpose and a meaningful caveat about verification limits. For a mutation tool in a guarded QE system, this is close to complete, though it could state prerequisites for the QE guard more plainly.

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 10 parameters including idempotency_key and expected_cep_target. The description only marginally adds meaning, noting start/end storage is compared at exact integer ticks and that unsupported time writes remain unverified, which touches time_seconds/duration_seconds but does not elaborate parameter usage.

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 to a project item'), and disambiguates by adding '(source clip marker)', which separates it from the sibling add_marker/add_markers_batch timeline-marker tools. It does not name those siblings explicitly, so differentiation is inferred rather than stated.

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

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

Usage is implied by the parenthetical 'source clip marker', letting an agent infer this is for source/project items rather than sequences. However, there is no explicit when-to-use/when-not guidance and no named alternative such as add_marker or add_markers_batch, leaving the agent to work out routing.

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

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

The single most important behavioral fact, that the operation is unsupported and will not work, is disclosed up front, which annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) do not reveal. What it omits is what actually happens on invocation, e.g. whether the call throws a specific error or returns a no-op result despite the full mutation-style 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 sentences, zero waste, and the disqualifying unavailability is front-loaded before the routing advice. Every clause carries decision-relevant information.

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

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

For a tool that cannot be used, the description supplies the reason and both redirect targets, which is sufficient for correct agent behavior. The remaining gap is behavioral: it never says what a caller sees if the tool is invoked anyway, which matters given a rich 7-parameter mutation schema and an output schema still attached to it.

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% across 7 parameters, including detailed prose on idempotency_key and expected_cep_target, so the schema already carries all parameter meaning. The description adds nothing about parameters, but baseline 3 applies when the schema does the heavy lifting, and the parameters are moot for an unavailable tool.

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 plainly that the tool cannot create caption clips from raw text because Premiere exposes no supported API, which tells an agent exactly what this tool is and is not. It doesn't restate the surface purpose (placing a text overlay on the timeline), but the unavailability notice is more valuable to selection than a restatement would be.

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 names two concrete alternatives and the condition that selects each: add_title for on-screen titles from plain text, create_caption_track for captions after importing an .srt/.vtt. Both branches are unambiguous and cover the two plausible intents an agent would have for this tool.

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

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

Goes well beyond the annotations: discloses the premiere baking step and why (no writable text), the textVerification status values, the baked-copy file location, the 50-copy cache retention policy with a data-loss warning, and the trim-and-read-back length check. This is rich, mutation-relevant context with no annotation contradictions.

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

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

Front-loads purpose and the text/lines distinction, then elaborates behavior. It is dense but every clause (paths, cache warning, verification names) carries signal; slightly long but not padded.

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

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

Given an output schema and full annotation set, the description fills the genuinely hard parts: the two template-kind pipelines, verification states, and cache retention. Nothing an agent needs to call correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds useful meaning about text vs lines and how the template parameter's kind changes behavior, but says nothing about track_index, start_seconds, idempotency_key, or expected_cep_target, which the schema alone must carry.

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) and resource (on-screen title from plain text via a stock Essential Graphics template), plus names the default. It is clearly distinguishable from siblings like add_text_overlay and import_mogrt by emphasizing stock template workflow.

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 to list_stock_titles to discover templates, their kind, and line counts, and explains the two execution paths by template kind. Lacks an explicit 'use X instead when...' against the other text/mogrt tools, so not quite a 5.

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 beyond the annotations by disclosing that presets are rejected before Premiere is contacted and why (AME encodes from a scratch project copy), and that start_batch sweeps unrelated ready jobs. It omits retry/idempotency behavior and that success doesn't confirm a render started (that detail lives only in the 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?

Compact, but the sentence 'Same as Project presets are refused before Premiere is contacted…' is grammatically broken and reads ambiguously, forcing the reader to reconstruct whether 'Same as Project' is a preset type or a comparison. That damaged clause costs clarity in an otherwise front-loaded description.

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

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

An output schema exists, so return values needn't be described. Prerequisites, the preset requirement, the pre-flight refusal, and the side effect of start_batch are all covered — enough for a correct call.

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

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

Schema description coverage is 100%, so the schema already carries parameter meaning. The description reinforces preset_path and start_batch but adds no syntax or semantics beyond what the schema states, and says nothing about output_path, expected_cep_target, or expected_project_path.

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: requesting an Adobe Media Encoder render-queue handoff for the active sequence. An agent can tell it apart from export_sequence or encode_project_item at a high level, though the description never explicitly contrasts those siblings.

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

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

It gives prerequisites (saved project, .epr preset_path) and a refusal condition, but never says when to choose this over siblings such as start_batch_encode, encode_project_item, encode_file, or export_sequence. 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 adds substantial behavior beyond the annotations: it is experimental, may razor a spanning target clip to preserve its tail, reads back target and sync-locked track changes, may still displace a tail, and reports those cases as committed_unverified. It also warns that 'target_tracks' scope will desync other tracks, which is useful risk context for a mutating edit.

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 front-loaded with the core action and then covers the experimental caveat and scope warning. It is dense and the middle sentence is long, but every sentence carries meaningful operational information.

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

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

For a complex timeline-mutation tool with eight parameters, nested guard objects, and an output schema, the description covers the key behavioral risks and the important scope option. It leaves alternative-tool selection and some guard-parameter rationale to the schema and sibling list, but is otherwise sufficiently complete for safe 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 parameters are already well documented. The description reinforces the meaning and risk of the scope parameter, but it does not add much parameter semantics beyond what the schema already states, and it does not discuss the other seven parameters.

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

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

States a specific verb and resource: 'Insert a project item at a timeline position.' The purpose is clear, but it does not explicitly distinguish itself from nearby siblings such as add_to_timeline_batch, insert_from_source, or overwrite_clip.

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

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

It gives one concrete usage rule for the scope parameter: pass 'target_tracks' to ripple only the named pair and desync other tracks. However, it does not say when to choose this tool over overwrite_clip, insert_from_source, or add_to_timeline_batch, leaving the main tool-selection guidance implicit.

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: it warns that experimental QE sync-lock handling 'may ripple or split earlier placements', explains the preflight-then-verify workflow, and defines the committed_unverified outcome with observed final positions. That is exactly the risk and result-shape information an agent needs before a mutating batch call.

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

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

Three tight sentences, front-loaded with the operation and then the side-effect risk and verification semantics. Some jargon ('validated CEP request', 'Experimental QE sync-lock') assumes domain knowledge but is not padding.

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 full schema coverage, annotations, and an output schema, the description supplies the missing narrative: side effects on existing placements and the committed_unverified result state. The remaining gap is routing guidance versus the single-item add_to_timeline, which an agent facing 150+ siblings would still have to infer.

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 nested parameters (clips, idempotency_key, expected_cep_target, expected_project_path) are documented in detail in the schema itself, so baseline 3 applies. The description adds nothing parameter-specific – notably it never mentions that an idempotency_key is available for safe retries, which the schema documents at length.

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: 'Insert up to 32 project items ... in one validated CEP request.' The batch/limit framing tells an agent this is the multi-placement variant, but the description never names the single-item sibling (add_to_timeline) that would complete the differentiation – that link only appears in the clips schema text.

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 'up to 32 ... in one validated CEP request', i.e. reach for this when placing multiple items together rather than one at a time. There is no explicit when-to-use/when-not statement, no mention of add_to_timeline or overwrite_clip as alternatives, and no guidance on sequencing vs other edit tools.

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

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

The description usefully adds the all-or-nothing guarantee: it errors rather than partially adding when the exact requested count cannot be met. That is real value beyond the annotations (destructiveHint=false, idempotencyHint=false). But it omits the idempotency/replay model that the schema's idempotency_key implies, leaving the agent to infer it from the parameter doc.

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

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

Two tight sentences, front-loaded with the action and followed by the failure contract. Nothing is wasted, though the second sentence could carry the sibling differentiation instead of only the error 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 five parameters, nested guard objects, and an output schema, the mechanical details are covered elsewhere. What is missing is the one thing only the description can supply: why this exists alongside add_tracks and when each applies.

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

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

Schema description coverage is 100%, so parameter meaning is fully documented in structured fields; baseline is 3. The description adds only that tracks added are 'verified' and that count must be satisfiable, without clarifying track_type/count defaults or the expected_* guard objects.

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 video/audio tracks to the active sequence), so the action is unmistakable. However, it never distinguishes itself from the sibling tool add_tracks (plural), which appears to do essentially the same thing, and 'verified' is left unexplained.

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 indication of when to use this versus add_tracks, nor any stated preconditions (e.g. an active sequence must exist, targeting behavior). The only conditional content is the error-on-count clause, which is a behavior, not usage guidance.

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

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

Adds a genuinely non-obvious behavioral fact beyond the annotations: QE inserts at index 0 and shifts every existing track up, which changes track indices agents may rely on. It also commits to count verification. It omits failure/rollback behavior and does not mention the idempotency_key guard despite idempotentHint=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?

One front-loaded sentence that puts the action before the verification and side-effect clauses; every clause carries information. It is a dense run-on, but nothing is wasted.

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

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

Output schema exists, so return values need no explanation, and the description covers the mutation's most surprising consequence. It leaves out prerequisites (an active sequence must exist) and what happens on partial or failed insertion, and does not point at the singular add_track alternative.

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 every parameter including the counts and the idempotency/guard objects is already documented in the schema. The description only echoes 'exact requested counts' without adding semantics such as defaults or interaction between track types, 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 and resource (add video and/or audio tracks) plus the mechanism (through QE) and an explicit post-check on the active sequence's counts. It does not distinguish itself from the sibling add_track, so an agent seeing both has no stated basis for choosing.

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 references to 'the active sequence' and by the verify-after step, but there is no explicit when-to-use guidance, no when-not, and no routing to sibling add_track for single-track insertion.

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

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

The description adds useful context beyond the annotations by calling out the experimental undocumented QE DOM path and noting that the transition is read back from the sequence track. It does not elaborate on failure modes, permission needs, or the optional idempotency and guard parameters.

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 experimental warning and a clear action statement. Nothing is wasted, and the read-back note is compact and relevant.

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 rich schema descriptions, an output schema, and annotations covering safety, the description is adequate for selection and invocation. It flags the experimental QE DOM nature, though it could say more about guard/idempotency behavior for this complex 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 the schema already explains all seven parameters in detail. The description adds no parameter-level meaning beyond the high-level notion of placing a transition at a cut point.

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: adding a video transition between two clips at a cut point. This distinguishes it from clip-level or batch transition tools by scope, though it does not name sibling alternatives 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?

It implies usage at a cut point between two clips and flags the tool as experimental QE DOM. However, it gives no explicit when-not guidance or alternatives such as add_transition_to_clip or batch_add_transitions.

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 it is a non-destructive, non-idempotent mutation; the description adds genuinely new context — that it rides an undocumented QE DOM path and that it verifies by reading back the requested placement. It stops short of stating what happens on a partial/failed apply or whether the clip must be selected.

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

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

One front-loaded sentence with the risk warning first and the effect second — no waste. It is arguably too short for the parameter surface, but nothing in it is 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 needn't be explained. But for a 7-parameter mutation with nested CEP guard objects and an idempotency key, the description says nothing about the precondition checks, session/restart behavior of keys, or where transition names come from — an agent must read the schema to call it safely.

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 heavy lifting is already done; the description only echoes the start/end/both placement semantics. It adds nothing on transition_name sourcing, duration_seconds, or the idempotency_key and expected_cep_target guards.

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 a transition), the exact target (a specific video clip), and the edges affected (start, end, or both), plus a read-back of the placement. It is clearly the single-clip counterpart to add_transition/batch_add_transitions, though it never names those siblings.

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

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

The 'EXPERIMENTAL (undocumented QE DOM)' prefix signals a caveat but gives no routing rule: it does not say when to prefer this over add_transition, batch_add_transitions, or list_available_transitions (which supplies valid transition_name values). Usage is only implied by the 'specific clip' wording.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, and idempotentHint=false, so the safety profile is mostly covered. The description adds real value by naming the exact property mutated and stating that Essential Sound Amplify automation is untouched, but says nothing about prerequisites, keyframe interaction, or the availability of the idempotency_key retry semantics.

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, the action front-loaded and the scope exclusion immediately after. Nothing is wasted or buried.

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

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

An output schema exists and the input schema is fully documented, so return and parameter details are covered elsewhere. What the description leaves unaddressed is the interaction with sibling volume tools, whether it works on both audio and video clips, and keyframe/automation behavior beyond the Essential Sound exclusion.

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, level_db, idempotency_key, and the guard objects are all documented in structured data, including the dB sign convention. The description adds no parameter-level 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?

States a specific verb and target property path ("Adjust a clip's Volume > Level in dB"), which is more precise than a generic volume setter. It does not, however, differentiate itself from close siblings such as set_clip_volume, set_clips_volume, or set_clip_pan, so an agent cannot tell from the description alone 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?

The negative scope ("Does not read or change Essential Sound Amplify automation") gives one exclusion, which is useful. But there is no positive when-to-use guidance and no pointer to an alternative for reading level, for Essential Sound Amplify adjustments, or for batch volume changes.

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 information beyond the annotations: it declares the analysis is deterministic, makes no model calls, does not persist transcript text, and does not mutate Premiere — the persistence and no-model claims are not in the annotation set. It stops short of saying the call is bounded by maxItems/timeouts or that results reflect only the supplied segments with no host inspection.

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 no filler, and the core purpose is front-loaded ahead of the negative guarantees. It is efficiently sized, though the compressed adjective stack ('caller-supplied, revision-bound') costs a little readability for a schema this large.

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 nested guard parameters are fully described in the schema. What is missing is where the candidates go next and why an agent would pick this over review_dialogue_candidates — the one real completeness gap for a tool with so many close 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?

With 100% schema description coverage, the schema already documents segments, filler_words, silence_ranges, minimum_silence_seconds, and the CEP guard parameters in detail. The description only restates the two headline inputs ('transcript segments' and 'optional local silence ranges') and adds 'revision-bound', so it contributes marginal semantics beyond the schema.

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

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

The description pairs a specific verb ('analyze') with a concrete resource ('caller-supplied, revision-bound transcript segments') and states the output class ('deterministic dialogue-edit candidates'). It is clear in isolation, but it never distinguishes itself from the near-identical sibling review_dialogue_candidates or from plan_filler_word_removal/plan_pause_tightening, which consume similar inputs.

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?

'Caller-supplied' plus 'never calls a model' implies the caller must already hold transcript text (e.g. from get_clip_transcript_uxp) and that this is a pure-compute step, which is useful implied context. However, there is no explicit when-to-use, no when-not-to-use, and no reference to the obvious alternatives review_dialogue_candidates or the planning tools the candidates feed into.

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

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

The description adds real context beyond annotations: the exact measurement standard (EBU R128), what is measured, and that no audio is altered and Premiere state is untouched. However it sits in tension with readOnlyHint=false and never explains why an ostensibly analysis-only tool carries idempotency_key and CEP identity guard parameters, leaving the agent uncertain about actual side effects (subprocess spawn, temp files, job dedup).

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 definition front-loaded and the critical scope caveat ('Analysis only') placed immediately after. Nothing in it is redundant with the name or 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 no explanation, and the required parameters are all optional. But for an 8-parameter tool with nested CEP guard objects, the description omits how target/threshold parameters change the result and why identity/idempotency guards exist on an analysis operation, leaving meaningful agent-facing gaps.

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

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

Schema description coverage is 100%, so every parameter is already documented inline, including media_path vs project_item_id and the idempotency_key contract. The description adds no parameter-level meaning on top of that, notably omitting that target_lufs/tolerance_lu/max_true_peak_dbfs turn the call into a compliance evaluation, which is the baseline-3 outcome.

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 plus resource plus units: 'Measure integrated loudness (LUFS), loudness range (LU), and true peak (dBFS) from a local media file using FFmpeg's EBU R128 filter.' It implicitly separates itself from the normalization sibling ('it does not normalize audio') but never names normalize_loudness_file, so an agent must infer the pairing rather than read 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 negative scoping sentence ('Analysis only: it does not normalize audio or change Premiere') implies when to pick this over a normalize tool, but there is no explicit when-to-use, no prerequisite (FFmpeg availability, media must be online/local), and no named alternative. Usage is inferable 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 delivery preflight' while the annotations declare readOnlyHint=false, which directly misleads an agent about whether the call mutates state. The presence of an idempotency_key described for 'this intended edit' further muddies the read-only claim, and the description resolves none of it.

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, zero filler, with the operation and its output classes front-loaded ahead of the usage context.

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 purpose and method are complete. However, for a tool carrying idempotency, CEP identity guards, and caching options, the description says nothing about sample scope, cost, or mutation semantics, and its read-only claim conflicts with the annotation.

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, sample_seconds, use_cache, and the guard parameters are already fully documented. The description adds no parameter-level meaning beyond what the schema provides, which is acceptable at baseline 3.

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

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

States a specific verb ('Classify'), the exact resource ('decoded video frames'), the enumerated output categories, and the underlying mechanism (FFmpeg idet). This is clearly distinguishable from siblings like analyze_video_qc or detect_source_scene_changes.

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 in which to reach for it, but no explicit when-to-use versus alternatives (analyze_video_qc, inspect_media_streams) is given and there are no exclusions.

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

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

The description states 'Read-only: it does not contact Premiere or modify the file', while the annotations declare readOnlyHint=false. The engine (FFmpeg), the local-only scope and the non-mutation claim are all useful behavioral context, but they directly conflict with the structured safety hint the agent will weight. This is an Annotation Contradiction.

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 what is analyzed and finished with the safety constraint. Nothing is redundant or padded.

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

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

With an output schema present and full schema coverage, the description only needs to orient the agent, and 'black/frozen detection on a local file via FFmpeg' does that. The remaining gap is that it never tells the agent how the Premiere-oriented guard parameters relate to a purely local analysis.

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 explains media_path, the two threshold defaults and the full CEP/idempotency guard machinery. The description adds no parameter meaning at all — notably it never says the expected_cep_target/expected_project_path guards are inert for this local-only tool. 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 description names a concrete verb and target ('Analyze a local video delivery') plus the exact defects it looks for ('sustained black and frozen sections with FFmpeg'). That makes it distinguishable from near-neighbors like detect_scene_edits or inspect_rendered_video_scopes, though no sibling is named 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 context is only implied: 'local video delivery' plus 'does not contact Premiere' hints this is for offline QC of a file rather than the open project. There is no explicit when-to-use clause, no exclusion, and no pointer to alternatives such as verify_delivery_file or inspect_rendered_video_scopes.

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

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

Beyond annotations, it discloses that both hosts and file metadata are rechecked, that confirmation is mandatory, and that the one-time token is consumed before dispatch — a real side effect not captured by the hints. It stops short of describing failure modes or what state is left if the import partially fails.

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 action first, then the precondition/side effect, then the exclusions. Every sentence carries distinct information with no repetition of the schema.

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

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

For a mutating cross-host tool with a rich schema and output schema, the description covers prerequisites, guard checks, and side effects well. A minor gap: it never says how the destination bin is determined (presumably carried by the token), which an agent might wonder about.

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 explains preview_token, confirm_import, idempotency_key, and the CEP guard objects in detail. The description only reinforces the 'exactly one' scope and token consumption; it adds no syntax or usage detail beyond the schema, 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?

Specific verb+resource with precise scope: 'Import exactly one previewed completed AE render into its approved Premiere bin.' It also states three explicit non-goals ('Does not save, render, or change a timeline'), which separates it cleanly from preview_after_effects_render_handoff and apply_mogrt_premiere_handoff.

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 preconditions are clear: the render must be previewed/completed and requires confirmation, and the description notes the token is consumed before dispatch, implying the preview step must precede this call. It gives exclusions (no save, render, or timeline change) but doesn't explicitly name the prerequisite sibling tool in prose — that routing is left to the preview_token schema description.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent. The description adds genuinely non-obvious context: that the QE catalog lookup falls back to an exact-name probe when enumeration is empty, and that a component-list readback does not prove rendered audio actually changed. That verification caveat is exactly the kind of nuance annotations cannot convey, though the presence of an idempotency_key parameter alongside idempotentHint=false is never addressed.

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

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

Three short sentences with the purpose front-loaded and no filler. The two trailing sentences are dense jargon ('QE catalog lookup', 'component-list readback') that could be plainer, but they are compact rather than padded.

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

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

An output schema exists and annotations plus 100% schema coverage carry most structural burden, and the description adds a useful verification caveat. However, for a five-parameter mutation tool with nested conditional guards, it omits prerequisites (effect availability), the sibling routing, and any hint about failure modes the guards produce.

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 nested guard objects are documented in-schema, so the baseline of 3 applies. The description touches only obliquely on effect_name resolution via the 'exact-name probe' remark and says nothing about node_id, idempotency_key, or the optional identity guards.

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 names a specific verb (apply) and resource (audio effect on a clip), which is materially more precise than the bare title. It does not distinguish itself from close siblings such as apply_effect, batch_apply_effect, or list_available_audio_effects, so an agent must infer which one to choose.

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

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

There is no statement of when to use this tool versus apply_effect (generic) or batch_apply_effect, and no guidance that effect_name should come from list_available_audio_effects. The follow-up sentences describe internal lookup and verification mechanics rather than invocation conditions.

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