davinci-mcp

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real behavioral value: the mandatory plan/confirm handshake and the fact that clear_transcription is irreversible (asymmetry vs clear_audio_classification). It does not cover permission requirements or what the snapshot/backup actually preserves.

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 purpose, then a tightly formatted action list, then the workflow rule. The closing line 'Calls known in advance (a sequence, the same change on several items): ONE batch_run' is terse to the point of being cryptic but does not waste 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?

For a destructive, nested-schema tool with an output schema this is close to complete: purpose, available actions, per-action params, confirm flow, and bulk alternative are all present. The remaining gap is auth/permission expectations and the reversibility of the audio-classification clear, which is left unstated.

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% for the top-level params, so the baseline is 3; the description does add per-action parameter names (clip, folder, nested) that the loose 'op' object with additionalProperties=true does not enumerate, which is a genuine gain. However, the stated '* = required' convention is never applied — no asterisk appears on any listed param — leaving requiredness per action ambiguous.

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

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

The verb 'Remove' plus the enumerated action list ('clear_audio_classification', 'clear_transcription') makes the resource scope concrete, going beyond the vague 'ai objects' of the first sentence. It distinguishes itself from sibling 'batch_run' for bulk sequences, though it does not contrast with 'ai_read'/'ai_write' directly.

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

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

It states the two-phase calling protocol explicitly (first call returns plan + confirm_token, repeat with the token to apply) and routes pre-planned multi-item work to a sibling: 'ONE batch_run.' What's missing is any guidance on when to choose ai_delete over ai_write for these same objects.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds nothing beyond that: no mention of what happens when a clip has no transcript, whether the transcript can be large/slow to fetch, or what the payload looks like.

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

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

Two short clauses with the purpose front-loaded and no filler. Its brevity is a virtue here, though the space saved is not reinvested in useful detail.

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

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

The tool is structurally simple (one param, nested-free), but there is no output schema, so the description should at least characterize what a 'transcript' returns (plain text vs. segments vs. timestamps). That gap, plus the missing parameter semantics, leaves the definition thin 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 0%, so the description must carry parameter meaning. It only restates the name and type ('clip_id (string, required)'), which the schema already encodes, and adds no format hints, ID source, or constraints.

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 (retrieves) and resource (transcript for a clip), which is unambiguous on its own. It does not differentiate itself from sibling read tools like clip_read, so an agent must infer that this is transcript-specific rather than general clip 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?

No guidance on when to use this versus clip_read or other read tools, and no prerequisites or exclusions. The only directive content is a restatement of the required parameter.

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 by warning that changes 'may overwrite current values' and by explaining the read-back receipt semantics ('receipt.verified=false means it did not take'). It also labels which actions run as blocking versus background jobs and notes side effects such as clip creation for remove_motion_blur.

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 destructive warning and receipt semantics, then a tightly formatted per-action list. Dense but every line carries information; the only waste is the '+2 more' shorthand that partially defers rather than informs.

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

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

For a destructive, multi-action dispatcher this is comprehensive: atomic vs job behavior, Extras requirements, receipt verification, dry_run/snapshot semantics, and escalation to batch_run and describe_action. With an output schema present, return-value details are appropriately delegated.

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

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

The schema allows additional properties in op, so the description carries the real parameter documentation, listing params per action with '*' marking required ones. Minor deduction for the '+2 more' truncation on generate_speech, which leaves two parameters to describe_action.

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 ('Change ai state') and then enumerates every action the tool performs, each with a concrete description. An agent can distinguish this from ai_read, ai_delete, and workflow_write 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?

Explicitly routes the agent: prefer workflow_write.build_vertical_reel for whole tasks, use batch_run for known sequences, use get_transcription to read transcription results, and consult describe_action for parameter details. It also flags prerequisites per action ('needs AI Extras', 'works without Extras') and blocking vs job execution.

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

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

Annotations already declare destructive=true, idempotent=false, openWorldHint=false, so the safety profile is known. The description adds real context beyond that: the first call only returns a plan plus confirm_token, the repeat applies it, and disable_background_tasks is called out as irreversible while quit_resolve terminates the application.

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 the purpose sentence, then a clean bulleted action list with per-action params in a consistent signature style, then the confirm-token rule, then the batch_run pointer. Dense and readable, though the opening 'Remove app objects.' is a terse fragment and the contract sentence sits at the end rather than up front.

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

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

For a destructive, nested-object tool with an output schema and rich annotations, the description supplies what structured fields cannot: the action taxonomy, the confirmation protocol, and the irreversibility flag on one action. Minor gap is that nothing explains when snapshot=true should be preferred over the server policy.

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 baseline is 3. The description does add per-action parameter requirements (delete_preset needs kind* and name*), which the generic 'additionalProperties' op schema does not spell out, but dry_run and snapshot are left entirely to the schema.

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

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

States a specific verb+resource ('Remove app objects') and immediately enumerates the three concrete actions, which pins down the scope far better than the title alone. It is clearly distinguishable from app_read/app_write and from the other domain delete tools by virtue of the application-level action 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 routes multi-step work to batch_run ('Calls known in advance ... ONE batch_run') and explains the two-phase plan/confirm flow needed to actually apply a deletion. It does not say when to prefer app_write or describe_action instead, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so 'no side effects' is largely redundant; the real added value is the per-action disclosure of what each call returns (product/version/edition/current page/keyframe mode; the five preset kinds). No permission or rate-limit context, but the operation is a safe read.

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 framing sentence followed by a tight bulleted action list; the scoping statement is front-loaded and the required-marker convention ('* = required') is declared once. No wasted prose.

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-shape explanation is not strictly needed and is partially duplicated here anyway. Both actions are documented with their parameters, and the escape hatch to describe_action covers the additionalProperties:true nested object, so an agent has enough to call 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 coverage is 100% but the schema only documents the action enum; the `kind` parameter and its allowed values (layout, keyboard, user-preferences, burn-in, Fairlight) exist only in the description, which compensates substantively. Remaining per-action params are deferred to describe_action, which is acceptable but not fully self-contained.

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 ('Read app state') and enumerates both supported actions (get_app_info, list_presets) with their outputs. It is clearly separable from app_write/app_delete by the read framing, though it never names those siblings explicitly.

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

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

'use it to find ids and check results' gives concrete intent-based guidance rather than a bare restatement. It doesn't state when *not* to use it or point to a specific alternative tool, so it stops short of 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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known. The description adds real value beyond that: the read-back verification contract (receipt.verified=false means the change did not take) and the overwrite warning tell the agent how to detect failure and what risk it is taking, though it does not say exactly which state can be clobbered per action.

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

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

Two front-loaded sentences establish scope, risk and the verification contract, then a tight one-line-per-action list carries the detail. Every line is load-bearing; nothing repeats the schema or annotations.

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 shape need not be explained, and annotations cover safety. Given that, the description supplies everything else an agent needs: action inventory, per-action parameters, failure detection, and the batch_run escape hatch.

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

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

The schema only enumerates action names inside a free-form nested object with additionalProperties; the description supplies the missing per-action contract, marking required vs optional parameters and giving accepted values (preset kinds, pages, keyframe modes). It converts a 100%-covered-but-uninformative schema into usable parameter semantics, well above 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 ('Change app state') and then enumerates all eight concrete actions with one-line meanings, so an agent knows exactly what surface this tool covers. It also distinguishes itself from batch_run for multi-call sequences, separating it from the most likely sibling confusion.

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 batched/known-in-advance sequences to batch_run, which is a clear alternative-selection rule. However, it gives no guidance on when to prefer dry_run or snapshot, nor when to consult describe_action versus the inline parameter list, leaving some operational choices to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's main added value is operational: analyze_loudness and detect_silence are flagged as running via ffmpeg 'no Resolve needed', while other actions implicitly require a Resolve session. That is real context beyond structured fields; what's missing is any note on error behavior or cost for the ffmpeg actions.

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 purpose sentence followed by a tight, scannable action list where every bullet earns its place. The only redundancy is 'no side effects', which restates readOnlyHint, and the initial phrase is slightly compressed ('audio state').

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 return values need not be explained, this description covers the action surface, per-action params, required markers, and environment requirements. An agent could select and invoke any of the seven actions from this text alone.

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

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

The schema only enumerates action names and defers params to 'additionalProperties'; the description fills that hole by listing each action's parameter names and marking required ones (item*, analyze_loudness(path, clip)). This is exactly the value the shallow schema cannot 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?

Opens with a specific verb+resource ('Read audio state') and immediately enumerates all seven concrete actions with their inputs, so an agent knows exactly what the tool covers. The sibling contrast with audio_write is clear from the read/write naming plus 'no side effects'.

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?

'use it to find ids and check results' gives a concrete use context, and per-action notes mark which ones work without Resolve. It never explicitly routes mutations to audio_write or other siblings, so the when-not guidance is only implied by the read-only framing.

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 substantial behavior beyond destructiveHint=true: execution is ordered, halts at the first failed or unverified step, all outcomes are reported, and each step is validated/verified/audited like a direct call. The *_delete two-phase plan + confirm_token flow is exactly the kind of consequence disclosure the destructive annotation alone 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?

Front-loaded with the one-line definition, then progressively more specific detail; almost no waste. It is dense — the template-syntax parenthetical is the least readable sentence — but every sentence carries 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?

Return values are covered by the output schema, and the description handles ordering, failure semantics, limits, and the confirm flow. The remaining meaningful gap is whether a mid-batch failure rolls back earlier successful steps or leaves them applied — critical context for a destructiveHint 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 already 100%, so 3 is the floor; the description earns more by explaining what the schema cannot — that a step's `op` is templated from earlier output, the two template roots for writes vs reads (`receipt.result.id` vs `result...`), and that [n]/[*] indexing works. Expected behaviour of dry_run and confirm_token is also implied. Minor gap: `wait` and `snapshot` are left entirely to the schema.

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

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

States a specific verb and resource — batch execution of several domain-tool calls — with the distinguishing scope 'in ONE call, in order, server-side'. That immediately separates it from every single-domain sibling like media_write or timeline_write.

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 a clear routing rule ('prefer it whenever the next calls are known') plus three concrete instance examples (metadata+color on four clips, add markers, rename tracks), and the deletion path is called out separately. It never names a sibling alternative (recipe_run, or the individual tools) or states an explicit 'do not use when', so it stops short of 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?

Annotations already carry destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is known. The description still adds real value beyond that: both actions are 'off by default' (a capability may be unavailable entirely) and the plan + confirm_token handshake is the only way the operation actually applies, which the annotations say nothing about.

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 and front-loaded: purpose sentence, then a scannable bullet list of actions, then workflow and batching notes. The only waste is the first line, which costs accuracy rather than length.

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

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

For a four-parameter, nested-object tool, the description covers the actions, the confirmation workflow, the batch alternative and the disabled-by-default state; an output schema exists so return values need not be explained. Nothing material an agent needs before invoking it 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 top-level params (dry_run, snapshot, confirm_token) are already documented. The description nonetheless supplies the action-level parameter contract — the required code* argument and the resolve/project/fusion globals plus `result` for run_python — which the schema cannot express because op is an open object that explicitly defers to the description.

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

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

The opening sentence says 'Remove code objects,' which reads as a deletion of code artifacts, but the only two actions exposed (run_lua, run_python) actually execute arbitrary code inside the host application. The action list is specific, yet the headline verb points an agent in a different direction than the enum, so the tool is not instantly distinguishable from siblings like fusion_write.

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 explicit routing rule — 'Calls known in advance (a sequence, the same change on several items): ONE batch_run' — and describes the required two-step invocation pattern (first call for plan/token, repeat to apply). It does not, however, say when run_lua should be preferred over run_python or over a typed sibling such as fusion_write.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so the safety bar is lower, yet the description still adds real behavior: the first call returns a plan plus confirm_token and must be repeated to apply, and per-action consequences are disclosed (target grades overwritten, group clips become ungrouped). It does not mention permissions or irreversibility beyond the token gate.

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 front-loaded sentence and bulleted action list are efficient and scannable, but the confirm_token/batch_run guidance sits after the bullets rather than up front, and the trailing 'describe_action' reference partially duplicates the params already listed.

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

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

For a destructive, multi-action, nested-payload tool, the description covers actions, per-action required params, the plan/confirm workflow, and the batch alternative; dry_run/snapshot semantics and the return shape are handled by the schema and output schema. A mention of snapshot recommendation for irreversible reset_all_grades would make it complete.

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

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

Schema coverage is 100% giving a baseline of 3, but the description goes further by naming the required params per action (source*/targets*, name*, item*/name*, target) inside an `op` object that permits additionalProperties. This meaningfully fills in the nested payload the schema only gestures at.

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

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

States a specific verb ('Remove') and resource ('color objects') and enumerates the four destructive operations, so an agent knows this is the deletion counterpart to color_read/color_write. It never explicitly says 'use color_write for non-destructive changes', but the action list makes scope unambiguous.

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

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

Explicitly routes bulk/known-in-advance sequences to batch_run instead of repeated calls, and the confirm_token instruction defines the two-step invocation. There is no explicit statement of when to prefer color_write over color_delete, but the destructive framing covers the main selection decision.

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 (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the per-action caveats: validate_dctl is 'sensitive to formatting: one-line functions can fail', and list_versions distinguishes local vs remote versions. These are real behavioral notes beyond the annotations, though nothing is said about latency, cost, or error modes.

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 purpose in one sentence, then a tight bulleted action list with no filler. Minor deduction for the slightly cryptic header 'op.action (params; * = required)', which requires an extra read to parse.

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

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

With an output schema present and annotations covering safety, the description only needs to disambiguate the action space, which it does for all four enum values. Small gaps remain, such as list_color_groups mentioning 'in a timeline' without declaring a timeline parameter, and no note on whether remote version listing needs extra auth.

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%, but the schema's op object is a free-form bag with additionalProperties, so the description is doing the real work: it maps each action to its expected parameters (target, item*, source/path) and marks required ones with '*'. Individual parameter meanings (e.g. what 'source' vs 'path' contain in validate_dctl) are left implicit.

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 ('Read color state') and immediately enumerates the four concrete actions it performs, so an agent knows exactly which sub-operations are reachable. The sibling set splits read/write/delete by suffix, and the 'no side effects' framing cleanly separates it from color_write and color_delete.

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 gives the two intended use cases: 'find ids and check results', which is actionable guidance for an agent. It does not name color_write as the alternative for mutations or state any exclusion, so it falls short of a full when/when-not statement.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the warning about overwriting current values is largely redundant with structured data. The description does add genuinely new behavior: changes are read back from Resolve and receipt.verified=false signals the change did not take, plus set_node_lut installs files outside the LUT root. Useful, but the safety profile comes from annotations rather than the text.

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?

Well front-loaded: the overwrite caveat and verification semantics come first, then actions, then shortcuts. The per-action enumeration is long but each line is dense and earns its place across 15 actions; a slight cost is that describe_action is also offered as the parameter reference, creating mild duplication.

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?

Covers a 15-action destructive write tool thoroughly: action inventory, preconditions, verification signal, shortcut alternatives and batching guidance. With an output schema present, no return-value explanation is required, and the receipt.verified note bridges behavior to that output.

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

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

The schema's op object is an open bag (additionalProperties=true, only 'action' enumerated), so the description is the sole source of per-action parameter names and which are required (marked with *). Without this list the agent could not construct a valid call, making it high-value 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?

Opens with a specific verb and resource ('Change color state') and then enumerates all 15 actions with concrete objects (versions, grades, groups, nodes, LUTs). This clearly separates it from color_read and color_delete and lets an agent match an intent to an action 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?

Explicitly routes the agent: whole-task work should go to workflow_write.apply_look, pre-known sequences or repeated changes to batch_run, and describe_action is named as the parameter reference. It also states preconditions that select/deselect actions (add_version and export_lut 'fail from the Edit page').

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 establish read-only, idempotent, closed-world behavior. The description adds useful context about the returned data: compact parameter schemas, action flags, and the tool-only listing behavior. It leaves 'flags' undefined, but the added context is meaningful beyond annotations.

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

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

The description is two compact sentences with no filler. The core function is front-loaded, followed immediately by the tool-only listing 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?

For a read-only introspection tool with full schema descriptions and annotations, the description covers the essential behavior and output nature. It is nearly complete, though it could briefly clarify what 'flags' means and whether `with_result` changes the response shape.

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 schema already documents all four parameters in detail. The description still adds semantic value by explaining the special behavior when only `tool` is supplied. It does not further clarify precedence among `action`, `actions`, and `with_result`.

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 resource and operation: it returns compact parameter schemas for one or several actions, including their flags. It also clarifies the tool-only listing mode. It does not explicitly distinguish itself from execution-oriented sibling tools, but the introspection purpose is clear.

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

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

The description implies discovery usage by explaining that providing only `tool` lists that tool's actions and signatures. However, it does not say when to use this instead of `search_api` or before invoking an action tool, nor does it state 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 already declare destructiveHint=true and non-idempotent, but the description adds real context beyond them: the two-phase plan/confirm_token flow needed to actually apply a change, that delete_tools is a single undo step, that clear_keyframes preserves the current value, and that install_fuse executes Lua requiring code execution to be enabled. It stops short of stating irreversibility guarantees beyond snapshot.

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 purpose sentence, then a compact per-action parameter ledger, then the confirm-flow and batch_run rules. Telegraphic notation is dense but every line carries information an agent needs to construct a call.

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 format need not be described, and dry_run/snapshot/confirm_token semantics are covered. Minor gap: it does not say how dry_run interacts with the confirm_token loop or what happens if snapshot is omitted under server policy.

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% for the four top-level fields, and the nested op object is deliberately opaque in schema (additionalProperties with a pointer to the description), so the per-action parameter list with asterisk-marked required args is genuine added meaning. Above the baseline 3 because the description carries the enum-to-params mapping the schema does not.

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

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

States a specific verb+resource ("Remove fusion objects") and enumerates the four concrete actions with their required parameters, so an agent knows exactly what the tool can do. It does not explicitly contrast with fusion_write/fusion_read siblings, but listing delete-style operations makes the scope readable.

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 actionable routing: use ONE batch_run when calls are known in advance, and consult describe_action for per-action params. It also flags the install_fuse precondition (code execution enabled + confirmation). No explicit when-not-this-tool guidance against fusion_write, so not 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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real behavior detail beyond them — comp_info returns undo stack and selection, tool_inputs resolves values at a time and paginates keyframes, registry_types searches ~1300 ids with limit/offset. It does not mention pagination defaults, result caps, or whether a live Resolve instance is required.

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 one sentence, followed by a compact bulleted action list with a shared legend for required markers. Every line carries a distinct action; 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?

With an output schema present, return values need not be explained, and all five enum actions are covered with their parameters. The remaining gap is domain linkage: it never explains what "item" vs "comp" mean or how to obtain an item id before calling comp_info/tool_inputs.

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

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

The top-level schema is deliberately generic (additionalProperties: true, "see the description or this server's describe_action tool"), so the description is the only place the real per-action parameters appear — and it lists them for all five actions with a "* = required" legend. This is genuine semantic content the schema does not provide, not repetition.

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 sentence gives a specific verb and resource ("Read fusion state, no side effects") and states the intended outcome ("find ids and check results"). The five enumerated actions each name a concrete resource (comp structure, compositions, .fuse files, registry ids, tool inputs), so the tool is clearly separable from fusion_write and fusion_delete.

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?

"use it to find ids and check results" plus "no side effects" tells the agent the situation this tool fits and implicitly contrasts with the write/delete siblings. It never names fusion_write, fusion_delete, or describe_action as the alternative for mutating or for deeper parameter lookup, so the routing is clear but 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 destructive/non-idempotent, but the description adds genuinely new behavior: every change is read back and receipt.verified=false signals the change did not take, disconnect is one undo step with undo restoring the link, load_tool_settings replaces existing parameters, set_inputs runs in one undo step because the comp is not locked, and rename_tool preserves expressions referencing the old name. These are non-obvious side effects and reversibility facts an agent could not get from the structured fields.

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

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

The highest-value content — the overwrite warning and the read-back verification rule — is front-loaded in the first sentence, followed by a scannable one-line-per-action catalog and a separate shortcuts section. The length is justified because the schema does not enumerate action parameters, so every line 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 and the description still flags the key return signal (receipt.verified=false), so return-value explanation is not required. Between the action catalog, the risk warning, the undo semantics, and the shortcut/batch routing, an agent has everything needed to call this destructive multi-action tool correctly.

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

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

The schema's op object is only {action, additionalProperties:true}, so the description carries nearly all parameter knowledge and does so per action, marking required params with '*' and adding meaning where types alone would not suffice (empty expression string clears, keys are (time, value) pairs, sets batches many inputs). The lone weakness is create_text_title's '+2 more', which hides two params, but describe_action is named as the escape hatch.

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+risk statement ('Change fusion state; may overwrite current values') and then enumerates all 17 supported actions with their scope, so an agent knows exactly what class of mutation this tool performs. It is unambiguously distinct from fusion_read, fusion_delete, and workflow_write.

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 whole-task work to the workflow_write.title_overlay shortcut ('One call instead of create_text_title, add_tool, connect, set_inputs, set_keyframes') and multi-step/repeated work to batch_run ('ONE batch_run'). It also points at describe_action as a fallback, so the agent has a decision path for both simple and compound cases.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, so the safety profile is covered. The description adds the non-obvious two-phase plan/confirm protocol, which an agent would otherwise miss and which materially affects correct invocation.

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

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

Front-loaded with the purpose, then action parameters, then the confirm protocol, then the batch alternative. The "(params; * = required)" legend is terse but decodable; nothing is 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 a rich annotation set and an output schema present, the description covers what's left: the single supported action, its parameters, and the plan/confirm workflow. Remaining gaps (scope of "gallery objects", whether album is a name or ID) are modest.

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 op object's own schema defers per-action parameter detail to the description or describe_action. Enumerating "delete_stills(album, stills*)" fills exactly that gap and marks the required item.

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?

"Remove gallery objects" names a specific verb and resource, and the action list makes it concrete: delete_stills(album, stills*). It is implicitly distinguished from gallery_read/gallery_write by the delete verb, but the description never explicitly contrasts them, so a 5 isn't earned.

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 clear operational context: the first call returns a plan + confirm_token and must be repeated to apply, and predictable multi-item sequences should use a single batch_run instead. It does not mention the describe_action sibling that the schema points to, nor any when-not-to-delete 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 annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds some useful action-level context, including defaulting list_stills to the current album, but 'no side effects' largely repeats the annotations and it does not discuss pagination or other operational constraints.

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 purpose and usage, then uses a compact bullet list for actions. Every sentence and bullet adds actionable information with no filler.

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

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

For a read-only tool with two actions, annotations, and an output schema, the description is nearly complete: it enumerates both actions and their parameters. The main omission is explicit routing to sibling tools, but the calling information itself is sufficient.

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?

Although schema description coverage is reported as 100%, the schema itself only defines a generic nested op object with an action enum. The description adds meaningful per-action semantics: list_albums takes no params, list_stills takes an album and defaults to the current album.

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

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

The description uses a specific verb and resource ('Read gallery state') and immediately lists the two supported gallery read actions. The 'no side effects' phrasing and action enumeration distinguish it from sibling write/delete tools such as gallery_write and gallery_delete.

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 a clear usage context: 'use it to find ids and check results.' However, it does not explicitly name alternatives or state when not to use this tool, such as directing mutations to gallery_write or deletions to gallery_delete.

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: warns "may overwrite current values", discloses the read-back verification semantics ("receipt.verified=false means it did not take"), and states the prerequisite that export_stills needs the Gallery panel open in Resolve. These are non-obvious failure modes an agent could not infer from destructiveHint=true alone.

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 the destructive warning before any detail, then presents a scannable bulleted action list, then a clearly labeled shortcuts section. Dense but every line carries either an action contract or a routing rule; nothing is redundant with 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?

A destructive multi-action tool with a polymorphic `op` parameter is fully covered: mutation risk, verification signal, prerequisites, batching escape hatch, and per-action params are all present, and the output schema plus receipt.verified note covers return semantics.

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

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

Although schema coverage is nominally 100%, the `op` schema is an open object that only says "see the description", so the description is the real source of per-action parameter contracts — it names which params each action takes and marks required ones with asterisks. dry_run and snapshot are separately documented in 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?

Opens with a specific verb+resource ("Change gallery state") and then enumerates the seven concrete actions (create_album, export_stills, grab_still, import_stills, rename_album, set_current_album, set_still_label). It is unambiguously the write counterpart to gallery_read/gallery_delete, so an agent can route 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?

Explicitly routes away from itself: "Shortcuts (prefer them for whole tasks)" points to workflow_write.apply_look instead of grab_still, and "Calls known in advance... ONE batch_run" names the batching alternative. It also defers to describe_action for per-action parameter detail, giving a complete decision path.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'no side effects' adds little. The description earns credit elsewhere by disclosing what each parse yields (events, assets/clips/markers, tracks/gaps/markers) and the non-obvious trait that read_marker_csv matches header names leniently. It stays silent on failure behavior for malformed or missing files.

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 line establishes purpose and safety, followed by a compact action list where every bullet adds a distinct parse target. No filler sentences and no repetition of schema detail.

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

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

With an output schema present, the description rightly omits return-value documentation and focuses on action selection, which is the real complexity here (one nested op object dispatching to five behaviors). Remaining gaps are error and path-resolution semantics, which matter for a file-parsing tool but are secondary.

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

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

The schema is 100% described but only at the wrapper level ('{action, ...params}') and explicitly defers to the description or describe_action, so the description is what actually documents that each action takes a single required path*. That per-action required-param listing is real added value. It does not explain what a path is relative to, or any format constraints on it.

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

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

The description gives a specific verb and resource (read/parse interchange files) and then enumerates all five actions with concrete objects: .cube header, CMX3600 EDL, FCPXML, marker CSV, OTIO JSON. An agent knows exactly what it is invoking. It never names interchange_write, so the read/write split is only implied by 'no side effects' 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?

'use it to find ids and check results' gives one concrete use case, which orients an agent toward inspection workflows. There is no when-not guidance, no exclusion for large or malformed files, and no explicit routing to the sibling interchange_write or to describe_action for richer param help.

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

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

The annotations already declare destructive=true, non-idempotent, non-readOnly, and the description confirms and enriches that: values may be overwritten, and every change is read back from Resolve with receipt.verified=false signalling a change that did not take. That read-back verification contract is real information not present in the annotations. Minor gap: it does not describe what the snapshot policy means in practice or which failures leave partial state.

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 behavioral warning is front-loaded in the first sentence, and the per-action bullets are dense but load-bearing. The '+2 more' shorthand saves space at the cost of completeness, which is the only inefficiency.

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 five-way dispatcher with a nested, open op object, the description supplies the action roster, per-action parameters, overwrite semantics, verification semantics, and the batch_run alternative; an output schema exists so return-shape explanation is correctly omitted. The truncated parameter lists and undefined snapshot policy are the remaining 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 coverage is 100% for the three top-level parameters, and the schema itself gives no meaning to the action-specific keys inside the free-form op object; the description compensates by listing the parameters per action (path*, fps, events*, overwrite, etc.), which is genuine added value. However, the '+2 more' ellipses leave those parameters documented nowhere in the description, deferring to describe_action.

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 effect ('Change interchange state; may overwrite current values') and then enumerates the five concrete write actions (write_cube_lut, write_edl, write_fcpxml, write_marker_csv, write_otio), which makes the resource scoped and distinguishable from interchange_read. The umbrella term 'interchange state' is somewhat abstract, but the action list removes the ambiguity.

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

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

It explicitly routes the agent away from this tool when calls are known in advance and repeat over a sequence ('ONE batch_run'), and points at describe_action in the schema for per-action parameter detail. It stops short of stating when to prefer dry_run or snapshot, or when interchange_read is the right 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 already declare destructiveHint=true and non-idempotent, but the description adds the crucial non-obvious behavior: the first call only returns a plan and confirm_token, and the call must be repeated with the token to actually apply. That is real context beyond the structured fields; it could still say more about reversibility/snapshot policy defaults.

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 the verb and action list, then the invocation sequence, then the batching hint — every line earns its place. The telegram-style abbreviation ('item*', bare param lists) is terse 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?

For a destructive, nested-schema tool this covers the essentials: destructive nature (via annotations), the plan/confirm flow, dry_run and snapshot (documented in schema), and where to route batches. An output schema exists so return values need no explanation; only snapshot server-policy defaults and irreversibility go unstated.

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

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

The schema's `op` object is a free-form additionalProperties bag with only the action enum, so the description carries the per-action parameter contract: required markers on item/frame, 'All' as a valid color value, and the 1-based index for delete_take. Without this text the parameters would be unusable.

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

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

States a specific verb ('Remove') plus the resource ('item objects') and enumerates exactly the two sub-actions (delete_item_markers, delete_take), so an agent can tell this apart from sibling deleters like media_delete or timeline_delete. It does not explicitly contrast with item_write, which keeps it from a 5.

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

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

Gives concrete routing guidance: use ONE batch_run when the calls are known in advance / the same change applies to several items, and documents the two-phase plan+confirm_token invocation pattern. It stops short of saying when to prefer this over item_write or a full timeline_delete.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds value by disclosing the return shape per action (timing, source range, track, flags, links; take count and selected index; whether the timeline blanking is used). It does not cover pagination or error behavior, but for a read-only tool this is well above the annotation bar.

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 purpose sentence up front, then a scannable action list with a legend for the '*' required marker. No filler; every line carries an action name, its parameter, and its return 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 a nested polymorphic input, annotations covering safety, and an existing output schema, the description supplies the missing piece (action catalog with per-action params and return hints) and routes the agent to describe_action for deeper detail. Nothing needed to invoke it correctly is absent.

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

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

The schema is a generic nested object with additionalProperties and only names the enum values, so the description is the sole source of action-level parameter semantics — and it delivers, marking `item` as required per action and explaining what each action reads. This is exactly the compensation the schema needs.

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 a scope constraint ('Read item state, no side effects'), then enumerates every supported action. An agent can distinguish this from item_write / item_delete purely from the description, and each action name is paired with what it returns.

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

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

Provides a light use case ('use it to find ids and check results') and points to describe_action for per-action parameters, but never states when not to use it or how it relates to siblings like timeline_read, media_read, or item_write. Usage is implied rather than directed.

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 discloses the read-back/verification contract ("receipt.verified=false means it did not take"), which actions take a timeline snapshot first, that stabilize has no read-back and can be slow, and that smart_switch is synchronous and may take minutes. These are exactly the operational traits an agent needs before committing a destructive write.

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 the risk statement, then a scannable one-line-per-action list, then the batching rule. Given 20 actions encoded in a single free-form object, the length is earned 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 the description still adds the one return-value fact that matters (receipt.verified). Combined with dry_run/snapshot semantics implied by the per-action notes, an agent has everything needed to call any of the 20 actions 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 coverage is technically 100%, but the nested op object is additionalProperties:true and explicitly defers to the description for per-action params. The description supplies that: every action's required (starred) and optional parameters, plus semantics like 1-based take index and frames units for fades.

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 ("Change item state") and immediately qualifies it with the risk ("may overwrite current values"). The enumerated op.action list makes it unambiguous that this is the mutation counterpart to item_read/item_delete, and an agent can pick the right action without opening the schema.

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

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

Gives explicit routing for the multi-change case ("Calls known in advance ... ONE batch_run") and per-action prerequisites such as add_transition needing source handles and add_take creating the take selector if needed. It does not explicitly contrast itself with item_read or timeline_write, so it stops short of full when/when-not coverage.

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 structural hint of being destructive, the description provides complex behavioral logic: it specifies that operations that cannot be interrupted will return WRONG_STATE, and that already finished jobs will not change state. This level of operational detail is not in the annotations.

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

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

The description is detailed, which is necessary given the complexity of the tool's behavior. While slightly verbose, every sentence serves to clarify a specific state transition or dependency and is well-structured.

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

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

The description covers all critical operational context, including pre-conditions (check status first), success paths, and various defined failure/limitation paths (unchanged, WRONG_STATE). It is complete without needing an explicit output 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?

While schema coverage is 100%, the description adds vital semantic context for the 'job_id' by specifying that it must originate from a prior successful 'write' or a 'job_list' call, which is crucial for agent lifecycle management.

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 purpose is stated clearly using a specific verb ('Stop') applied to a specific resource ('a running job'). It immediately distinguishes itself from siblings like job_status by defining it as a destructive action (cancel).

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

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

The description provides explicit usage guidance by advising the user to check job_status first if they are unsure about the job's current state. It also covers failure cases, noting that finished jobs will be returned unchanged and non-interruptible jobs will return WRONG_STATE.

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 establish that this is a safe, idempotent, closed-world read. The description adds useful behavioral scope by saying the list covers all jobs this server started, including running and finished jobs, with their state. It does not mention ordering or retention limits, but the annotations and output schema carry much of the remaining burden.

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, both front-loaded and purposeful. The first defines the result set; the second gives routing guidance. There is 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?

For a parameterless list tool with an output schema and read-only annotations, the description is complete enough. It explains what the list contains and how it differs from job_status, so an agent has what it needs to call the tool correctly.

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

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

The tool has zero parameters, so there are no parameter semantics to clarify. The baseline for a parameterless tool is 4, and the description does not introduce any misleading parameter expectations.

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 resource and scope: every job this server started, both running and finished, with state. It also explicitly distinguishes the tool from job_status, so an agent can identify its purpose 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?

It explicitly says to use this tool to recover a job_id and names job_status as the alternative for one job's details. That gives clear routing guidance between closely related siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so safety is covered. The description adds important non-annotated behavior: it returns at once rather than blocking, and job_wait is the blocking alternative. It does not add further details about progress granularity, but the output schema exists to cover return shape.

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 purpose and immediately followed by the key behavioral constraint and alternative. There is no redundant or 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?

For a read-only status-check tool with full schema coverage, annotations covering safety, and a separate output schema, the description supplies exactly the missing context: current state/progress and non-blocking behavior. Nothing needed to select or invoke it correctly appears to be absent.

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 single job_id parameter is already described in the schema, including where the id comes from. The description adds no further parameter semantics, which is acceptable at baseline 3 when the schema does the work.

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 resource and action: the current state and progress of a long-running job, with concrete examples (render, transcription). It also contrasts itself with the blocking sibling job_wait, so an agent can distinguish its role immediately.

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 says to use job_wait instead when blocking until completion is desired. That is a clear when-to-use/when-not-to-use rule tied to a named alternative, leaving little 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?

The description adds meaningful behavior beyond the annotations: the call blocks, returns final state and result on completion, and returns a still-running state if timeout_s elapses. This is important operational context. It does not cover failure cases or cancellation behavior, but the annotations already establish the safe read-only profile.

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

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

Two tightly written sentences, front-loaded with the core blocking behavior and followed by the timeout fallback. No sentence 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?

Given the output schema and annotations, the description covers the essential call behavior: blocking, timeout handling, and repeat invocation. It could say more about failure or cancellation outcomes, but the core semantics an agent needs are 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 already documents job_id and timeout_s. The description adds useful timeout-outcome semantics ('returns it still running'), but it does not add further meaning to job_id beyond the schema's origin note.

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: 'Block until a job finishes' and return its final state and result. It distinguishes the blocking wait behavior from ordinary status checks implicitly, but does not explicitly name the sibling alternative job_status.

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 explains the timeout loop ('call again to keep waiting'), which implies how to use the tool across multiple calls. However, it does not explicitly say when to use job_wait instead of job_status, job_list, or job_cancel, so the alternative-selection guidance remains 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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the description earns credit for the details annotations cannot carry: clear_clip_metadata overwrites values with empty strings, delete_folders removes folder content, unlink_clips sends media offline. It also implies the plan/confirm two-phase safety model. It does not state irreversibility, permission requirements, or whether the snapshot back-up actually covers media-pool deletions rather than only timeline/project.

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 the one-line purpose, then a scannable action bullet list with required params marked '*', then the confirm-token rule and the batching escape hatch. Nearly every line is load-bearing for action selection or invocation.

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

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

The tool is a multi-action destructive dispatcher with a nested schema, an output schema, and full annotation coverage; the description supplies the per-action parameter map the schema omits plus the confirm workflow, which is everything needed to call it correctly. Return-value description is unnecessary given the output 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%, but the schema leaves op as additionalProperties:true and explicitly defers per-action parameters to the description, so the enumerated action/parameter pairs carry genuine meaning beyond the schema. Minor gap: optional modifiers such as delete_clip_markers' frame/color/custom_data semantics and third_party's effect on metadata are named but not explained.

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 ('Remove media objects') and then enumerates exactly which objects can be removed, so an agent can tell whether its target (clip metadata, markers, mattes, clips, folders, proxy links) is in scope. It does not explicitly contrast with the sibling media_write or item_delete, so the boundary with non-destructive write/delete tools must be inferred from the action 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?

Gives the two-step execution protocol plainly: the first call returns a plan plus confirm_token, and the same call is repeated with the token to apply. It also names an alternative explicitly ('Calls known in advance ... ONE batch_run'), which routes batch intents to the sibling. Missing any statement of when NOT to use it (e.g. in favor of media_write for non-destructive edits).

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 carry readOnly/idempotent/non-destructive, and the description is consistent with them while adding real value: per-action return shapes ("raw JSON string plus parsed value"), pagination on browse_storage, and property selection on get_clip/list_clips. It does not disclose default limits, ordering, or what identifiers look like, which keeps it below 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?

Front-loaded one-line purpose followed by a tight action-indexed list with no filler. The schema-level guidance is delegated to describe_action, which is efficient; the only blemish is the "+1 more" shorthand that hides a parameter rather than naming 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?

For a polymorphic dispatcher over ten read-only actions, the description covers action selection, per-action scope, and required-vs-optional params, and it points to describe_action for full detail; an output schema exists so return values need no prose. Nothing an agent needs to call it 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?

The schema is a generic op wrapper whose coverage is nominally 100% but adds no real detail, so the description must carry the parameter burden — and it largely does, listing params per action with '*' marking required ones. The "+1 more" truncation on list_clips and the absence of value formats (path syntax, keys, clip identifier form) leave a genuine hole.

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 ("Read media state, no side effects") and then enumerates all ten actions with their exact scope, so an agent knows precisely what is reachable here. The read/write/delete sibling triad makes the boundary obvious 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?

"use it to find ids and check results" gives concrete selection guidance, which is the classic pre-step for the mutating siblings (media_write, media_delete). It stops short of naming those alternatives or stating when-not to use it, so it is clear but not fully 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 past the annotations: warns 'may overwrite current values,' documents the read-back verification contract (receipt.verified=false means the change did not take), tags clone_media as a long-running [job], notes version gates (21.1+), collaboration-mode requirements, and preconditions such as auto_sync_audio needing one video and one audio clip.

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 the destructive/verification warning in two sentences, then a single-line-per-action catalog, then shortcuts — a sensible ordering. The 32-line enumeration is long but each line is a distinct discriminator branch, so density is justified 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?

For a 32-branch destructive dispatcher this is complete: mutation semantics, verification receipt, job-tagged actions, version constraints, dry_run/snapshot safety knobs are in the schema, and an output schema exists so return shape needn't be restated.

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

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

The schema's op object is additionalProperties:true, so the enum alone cannot convey per-action arguments; the description supplies exactly that, marking required params with '*' for every action. This adds meaning the schema cannot express, despite 100% schema description coverage.

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

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

States a specific verb+resource ('Change media state') and then enumerates all 32 actions with per-action parameter shapes, so an agent can identify the exact operation it needs. It is clearly the write counterpart to media_read/media_delete and covers every member of the action enum.

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 whole-task work to workflow_write.conform_from_edl ('one call instead of import_media, relink_clips') and known-in-advance sequences to batch_run, which is genuine when-to-use guidance. It lacks explicit 'when not to use' framing versus media_delete/media_read beyond the obvious read/write split.

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 behavior beyond the annotations: the plan + confirm_token two-phase apply, the non-current-project restriction, and that a snapshot can back up the timeline/project first. Annotations already declare destructiveHint=true and idempotentHint=false, so the remaining gaps (permissions, irreversibility of deletion, whether snapshots are recoverable) are smaller but still real.

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 verb phrase, then a compact action table, then the confirmation and batching notes — every line carries information. The telegraphic style ('op.action (params; * = required)') costs a little readability but no sentence is waste.

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

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

For a destructive, polymorphic tool with an output schema and rich annotations, the description covers the action surface, the two-phase apply workflow, and the batching alternative. It does not say what exactly is lost when a folder or settings preset is deleted, or whether the snapshot default is safe, 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 coverage is 100%, so the baseline is 3, but the description adds genuinely new information the schema cannot express: the per-action required parameter (name*) for each of the three actions, which the op object itself leaves as additionalProperties with only a generic pointer. It also flags the '*' = required convention.

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

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

States a specific verb ('Remove') plus the exact resource set via three enumerated actions (delete_folder, delete_project, delete_settings_preset), with a scope qualifier ('non-current project'). That is far more specific than the title alone, though it never names the sibling it is not (e.g. project_write, timeline_delete, item_delete).

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 concrete routing guidance: use ONE batch_run when the calls are known in advance (a sequence, same change on several items), and consult describe_action for per-action params. It also explains the two-step invocation, but stops short of explicit when-not-to-use cases such as preferring project_write for renames.

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 closed-world, so the safety profile is covered; the description reinforces this with 'no side effects' and adds what each action actually surfaces (name, id, folder, database, presets). It says nothing about authentication, permissions, or pagination, which are the remaining behavioral unknowns.

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 the one-line purpose, then a scannable action list with one line per action and no filler. Every line maps to a distinct enum value.

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 shapes need not be described, and the description still summarizes what each action yields. All five enum values are accounted for, so an agent can pick the right action and call it without consulting another 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%, but the schema only lists the action enum strings and defers to the description ('see the description or this server's describe_action tool'). The description therefore earns credit by spelling out each action's behavior and noting that get_settings takes an optional keys list. It stops short of defining the key format or value types.

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 ('Read project state') and immediately enumerates the five concrete actions it exposes, so the agent knows exactly what scope of project data is reachable. The 'read' naming plus the explicit 'no side effects' clause cleanly separates it from the project_write and project_delete 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?

'use it to find ids and check results' gives a concrete motivating scenario rather than leaving usage implicit. It stops short of naming an alternative tool or stating when-not to use it, but the read/write/delete sibling naming makes the boundary largely self-evident.

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 destructiveHint=true annotation, it discloses that changes are read back from Resolve and that receipt.verified=false means the write did not take — a critical behavioral contract. It also surfaces implicit side effects annotations cannot express: current project is saved first, untitled projects are discarded, presets are overwritten.

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 key behavioral warning and the batch_run redirect, and the bulleted action list is scannable — but this is a long wall of text where 19 lines at uniform granularity force the agent to read past many irrelevant actions to find its one. Structure is functional, not lean.

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?

Rich coverage: dry_run/snapshot are schema-described, the return contract (read-back verification, receipt.verified) is explained despite an output schema existing, and per-action prerequisites are stated. Missing only that set_database's database param shape (DbType/DbName/IpAddress) is named but not typed.

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

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

The schema only declares action as an enum with additionalProperties=true, so the description carries the real parameter burden by listing required (*) and optional params for each action — substantial value beyond the schema. The '*' convention is inferable but never stated explicitly, and types for nested params are not given.

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+scope ('Change project state; may overwrite current values') and then enumerates all 19 actions with per-action effects, so the agent knows exactly what class of mutation lives here versus project_read/project_delete. The alternative-route note for batch sequences further sharpens the boundary.

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

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

Explicitly routes known-in-advance repeated changes to batch_run, and embeds situational qualifiers per action ('saved project only', 'needs force=true' on 21.x, 'refused for Untitled Project'). It stops short of stating general when-not-to-use conditions (e.g., preferring dry_run for exploratory changes), which keeps it off 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?

The annotations already state readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds that the result includes built-in recipes, user recipes, and recipes that failed to load, which is useful behavioral context, but it says nothing about pagination, ordering, or result size.

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 purpose and then the routing guidance. Every clause adds information; 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?

For a zero-argument list tool with an output schema and annotations that cover safety, the description provides everything an agent needs: what it lists, what the entries contain, when to call it, and which sibling to use instead for ad-hoc sequences.

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?

This tool takes no parameters, so there are no parameter semantics to explain, and the baseline score for zero parameters is 4. The description does not misrepresent any arguments.

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

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

The description gives a specific verb (List) and resource (recipes that recipe_run can execute), and it enumerates the returned fields: name, description, and parameters. It also scopes the list to built-in recipes, user recipes, and recipes that failed to load, which lets an agent distinguish it from recipe_run and batch_run.

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 usage guidance: call this before recipe_run, and use batch_run instead for an ad-hoc sequence. That names the alternative tool and the condition that selects 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?

Beyond the annotations, the description discloses important behavior: every step is validated, verified, and audited; execution stops at the first failed or unverified step; outcomes are reported per step; and destructive recipes require a confirm_token from a plan call. This is exactly the kind of behavioral context an agent needs for a potentially destructive 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 three short sentences with no wasted wording. It is front-loaded with the core action and then adds execution and destructive-recipe behavior in a logical order.

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, the description need not explain return values. With annotations covering safety hints and 100% schema coverage, the description adds the key behavioral details an agent needs: failure handling, auditing, and the destructive confirmation flow.

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 schema already documents all five parameters. The description still adds useful meaning for confirm_token by explaining that destructive recipes first return a plan with that token. It does not elaborate on params, dry_run, or verbose, but the schema carries those details.

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

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

The description gives a specific verb and resource: 'Run a recipe server-side'. It clearly explains that the tool executes recipes and validates, verifies, and audits every step. It does not explicitly distinguish this from close siblings such as batch_run or workflow_write, but the core purpose is unambiguous.

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

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

The description implies usage context by explaining that recipes are run server-side and that destructive recipes return a plan first. However, it does not say when to choose recipe_run over batch_run, workflow_write, or other execution-related siblings. The guidance is implicit rather than explicit.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, but the description adds the non-obvious two-phase plan/confirm safety flow that no annotation conveys. It does not mention permission requirements or what happens to the underlying media when a preset or job is removed, which would be the next useful layer.

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 the purpose in one line, then a compact bulleted action list with required params asterisked, then the confirm contract. The trailing batch_run sentence is telegraphic and slightly awkward but still carries a real routing instruction.

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

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

For a destructive, nested-object tool this covers the essentials: what each action destroys, the confirm-token protocol, and the batching alternative, while the output schema and annotations handle return shape and risk signaling. A note on snapshot/dry_run interaction with the confirm flow would close the 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 coverage is 100%, so the baseline is 3, but the schema's op object is a free-form bag with additionalProperties=true and only points back to the description for per-action params. The description carries that load by naming the required parameter for each action (job_ids, name), which the schema cannot express.

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 ("Remove render objects") and immediately enumerates the four concrete operations, so an agent knows exactly what surface this tool covers. It does not explicitly disambiguate against the nearby render_read / render_write siblings, which keeps it below 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?

Gives a clear operational instruction: the first call returns a plan plus confirm_token and must be repeated with that token to apply, and defers known-in-advance sequences to batch_run. What is missing is guidance on when to prefer this over render_write (e.g., update_render_preset lives here despite being an overwrite) or other *_delete siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds value by disclosing that progress is 'derived from percentage and error' and that codecs are only returned when `format` is supplied. It does not mention preconditions (e.g. a project needing to be open) or failure modes.

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 scope sentence followed by a dense action:params list with zero filler; every line either names an action, its inputs, or its return 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?

For a five-action read tool with an output schema and full annotations, the description covers what each action returns, so return values are not overloaded. Missing only environmental preconditions and error behavior, which is a minor gap given the structured coverage.

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

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

The schema is effectively a generic `op` bag that explicitly defers to the description, so the description carries real weight by naming each action's parameters (format, codec, audio) and clarifying that 'natural names work everywhere'. What it lacks is any type/format detail for those arguments beyond the natural-name note.

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?

Opening sentence gives a specific verb and resource ('Read render state, no side effects') plus the intent ('find ids and check results'), and the five enumerated actions spell out exactly what can be read. An agent can distinguish this from render_write/render_delete purely from the 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?

The phrase 'use it to find ids and check results' gives a concrete use case, and the per-action list makes selection among its own actions unambiguous. It stops short of naming sibling alternatives (e.g. render_write for changes, describe_action for deeper param docs), so there is no explicit when-not guidance.

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

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

Goes well past the annotations (destructive/not-idempotent): it discloses that values may be overwritten, that every change is read back from Resolve with receipt.verified=false meaning it did not take, that quick_export/render_timeline/start_rendering are long-running and must be polled with job_wait, and that format/codec are validated against the live list. These are operational facts an agent cannot get from structured fields.

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

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

Front-loads the critical overwrite/verify warning, then a scannable bullet-per-action list, then shortcut routing. Dense for 13 actions but nearly every line is load-bearing; only the '[job]' tags and version notes add minor visual noise.

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 13-action polymorphic mutation tool with a nested op object, the description covers action inventory, required vs optional params, long-running/polling behavior, version gating (21.1+), and verification semantics. An output schema exists, so return-shape explanation is correctly omitted.

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% on the three top-level params, but the schema defers per-action params to free-form additionalProperties. The description supplies them per action with '* = required' markers and defaults (e.g. render_timeline's optional format/codec/settings vs required preset/target_dir/name), which is meaning the schema does not 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?

Opens with a specific verb and resource plus scope: 'Change render state; may overwrite current values.' It then enumerates all 13 actions with one-line semantics, so an agent can match intent to action without opening the schema, and the write framing cleanly separates it from the sibling render_read.

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: 'Shortcuts (prefer them for whole tasks)' names workflow_write.deliver and workflow_write.build_vertical_reel with the exact low-level calls each replaces, and 'Calls known in advance... ONE batch_run' covers the batch case. Both alternatives and the conditions that select them are 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 readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond them: it tells the agent this establishes what other tools act on by default, which is critical for sequencing calls. It says nothing about cost/latency, but for a zero-arg local probe that is minor.

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 returned information and followed by the calling rule. Every clause earns its place; nothing is repeated from the schema or annotations.

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 described in prose, and the description still summarizes them at a glance. Zero parameters, safe annotations, and a clear call policy leave no gap an agent must guess at.

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?

Zero parameters, so the schema has nothing to document and the baseline is 4. The description adds the relevant nuance that the returned values act as implicit defaults for the other tools.

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

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

The description enumerates exactly what the tool surfaces (connection state, Resolve version/edition/channel, current project, timeline and page) and clarifies it is a reachability/context probe rather than a data reader. That is enough to separate it from data-oriented siblings like project_read or timeline_read, though it never explicitly names those alternatives.

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

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

'Call it first, and again after an error' gives a concrete, actionable invocation rule that an agent can apply without inference. It lacks any when-not guidance or explicit pointer to a sibling (e.g. job_status for job-level state), so it falls short of a full 5.

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