Vidova

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

Annotations only declare idempotent/destructive/readOnly hints; the description concretizes them — an already-present file returns its existing Asset ID (idempotency), Trash or still-uploading files are returned with a reason instead of failing opaquely, and 'Nothing is copied or charged' rules out billing and duplication side effects.

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

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

Purpose is front-loaded in sentence one, followed by input provenance, return semantics, edge cases, cost, and the required follow-up. Five short sentences, each carrying distinct operational 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?

There is no output schema, so the description must carry return semantics — and it does: Asset IDs returned per file, re-returned for duplicates, and per-file failure reasons. Combined with the follow-up instruction for processing videos, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, including id provenance and the projectId override semantics. The description reinforces that ids come from search_library but adds no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb+resource+destination: add files from the user's Library into the open project. It also implicitly distinguishes itself from search_library (source of ids) and patch_film (placement), so an agent can route without opening sibling schemas.

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

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

Explicitly routes: ids come from search_library, results are placed with patch_film, and if a video is still processing call wait_for_asset before placing. This covers the full before/after workflow rather than just the call itself.

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

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

Goes far beyond the annotations: cost of ~6.1 credits per minute billed by the second, and that an accepted submission keeps its credits even if it later fails or is deleted. It discloses sync vs async behavior (usually answers in-call; long ranges return a processing job to wait on via read_video_intelligence with waitSeconds 25), parallel fan-out across ranges, refusal handling (a refused request is not stored and can be resent corrected, changing only what the refusal names), and a prompt-injection warning to treat answers as observations about untrusted media. The idempotentHint=true annotation is consistent with the stated requestId resume semantics.

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

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

It is one dense but well-ordered paragraph: purpose and routing come first, then inputs, then cost and async behavior, then a safety note. A few sentences duplicate schema text (mediaId's Asset ID/Library id wording, requestId's UUID rule) and the note about answer times largely restates the output schema, so it is slightly over-packed rather than wasteful.

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

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

For a billed, sometimes-async, open-world analysis tool with six required parameters, the description covers everything an agent needs to call it correctly: routing from siblings, range sizing and limits, cost and non-refundability, the sync/async split with the exact follow-up call, and refusal recovery. Return values are covered by the existing output schema, so no gap remains there.

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 83%, so most parameters are already documented, but the description adds constraints the schema lacks: start/end must be 1 second to 1 hour apart, endSeconds must not exceed durationSeconds, and an end less than half a second past means end of video. It also gives requestId resume semantics and tells the agent to preserve the original range after a refusal. projectId is left entirely to the schema, and the mediaId/requestId wording partly restates 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 — "Ask a question about, or request a summary of, a range of a Library video" — with the scoping constraint (a range, not whole corpus by default) front-loaded. It is explicitly distinguished from siblings by naming search_video_moments for locating footage and read_video_intelligence for waiting on long jobs, plus a note that indexing is not required (contrast with index_video).

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

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

Explicit when-to-use ("only when the user's request needs it"), when-not ("Never run analysis for every upload or every search result"), and named alternatives with their selecting conditions (search_video_moments when footage must be located; skip the search when a range is already selected). It also gives a sizing heuristic: analyze the smallest range that answers the question with enough context around 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 only cover the safety flags (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries real weight here and delivers: it writes on a new track, adds assets, creates masks/face tracks, consumes credits, writes the current version, rolls the effect back on failure, and returns a Job ID for long cutouts. This is exactly the async/rollback/credit context an agent needs and cannot get from 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 purpose is front-loaded, but the body is a dense run-on block that folds parameter explanations into mid-paragraph prose ('at is the timeline second the effect starts. duration null uses...') rather than organizing them. The length is defensible for a complex tool, but the structure makes it harder to scan than it needs to be.

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

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

For a complex, non-idempotent mutation with no output schema, the description covers what an agent must know: async Job ID handling via wait_for_jobs, rollback on mask/face failure, credit consumption, and verification via preview_frame. Nothing critical is left for the agent to discover by trial.

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 goes further: it explains values with concrete JSON examples ({"emoji": "😭"}, {"face": "track_face_2"}, Asset-ID photos), clarifies that region is [x0,y0,x1,y1] fractions and is ignored for person/face effects, and states when clipId is required. These examples add meaning beyond the schema text.

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

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

The first sentence names a specific verb and resource ('Put one effect from search_effects into the film') and immediately describes the concrete side effects (new track, added assets, mask/face creation). It distinguishes itself from siblings by naming search_effects, cutout_subject, track_faces, wait_for_jobs, and preview_frame in their proper roles. An agent can tell what this tool does 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 gives stylistic usage advice ('Use one effect per moment, on a real beat or impact: an effect on every cut reads as noise') and routes effectId lookup to search_effects, but never contrasts itself with the sibling prepare_effect or states explicit when-not-to-use conditions. Usage is implied rather than specified as a selection rule.

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

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

Annotations only declare the generic write profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds real behavior beyond them: size limits per file type, an explicit 'do not send bytes through tool arguments' constraint, connection-failure signatures (403 from proxy, connect_rejected, refused, DNS failure) and a no-retry rule, and the fact that missing parts are surfaced by complete_asset_upload.

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

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

Purpose and file-type constraints are front-loaded and nearly every sentence carries operational value (sequence, limits, error handling, alternative tool). It is a long run-on block without bullets or whitespace, which slightly hurts scanability for a dense workflow tool.

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

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

For a 7-parameter, multi-step upload tool with no output schema and no readOnly/auto-explanatory annotations, the description covers the full lifecycle: begin, run commands, complete, handle multi-part uploads, and react to connection failures. 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?

Schema coverage is 57%; the four video/project parameters carry their own schema descriptions (startSeconds/endSeconds range, keepOriginal behavior, projectId scoping). The description only reinforces filename, MIME type and byte size, which the schema already names, so it adds limited meaning beyond structured data.

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

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

Specific verb+resource: 'Begin uploading a local media file, a data file ..., or a font file.' It enumerates the accepted file classes with concrete extensions and size caps, and clearly states the return (a new Asset ID plus upload command(s)). It also distinguishes itself from siblings by steering agents to upload_files and forward-referencing complete_asset_upload.

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

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

Explicit when-to-use and when-not: 'If you have the upload_files tool, call it instead' for device-side uploads. It lays out the required sequence (run the returned commands in order, then call complete_asset_upload) and the >95 MB multi-part path, plus a rule not to retry unreachable commands.

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

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

Adds real context beyond the annotations: a credit hold is released, completed exports are untouched, ownership is required, and repeated calls are safe. The annotations already declare idempotentHint=true and destructiveHint=false, so the description's contribution is the side effect (credit refund) and ownership constraint — genuinely useful. It stops short of saying whether cancellation is synchronous, what errors occur for a non-owned or already-failed job, or whether list_renders must be polled afterwards.

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

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

Three short sentences, front-loaded with the action and scope, then the credit effect, then the idempotency reassurance. Every clause carries information; 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?

An output schema exists, so return values need not be explained. The description covers preconditions, side effects and idempotency for a single-parameter mutation, but omits error conditions (not found, not owned, already failed) and whether the caller should poll wait_for_jobs or list_renders to confirm the cancellation took effect.

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 single jobId parameter has 0% schema description coverage — only a uuid format and regex. The description never mentions the parameter, leaving the agent to infer that jobId is the export to cancel (plausible but unstated, and it doesn't say where to obtain one, e.g. from list_renders). Minimum-viable given the param is largely self-evident.

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 ('Cancel an owned pending or running cloud export') with scope qualifiers that separate it from read_render and list_renders. An agent knows exactly what operation this performs and on what object.

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

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

Implies the when: only exports that are 'owned' and in pending or running state, with an explicit note that completed exports are not affected. It does not name an alternative tool (e.g. read_render to check status, wait_for_jobs to await completion) or state what to do when the job is not owned, so it falls short of a full when/when-not map.

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

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

Annotations only declare mutation/idempotency/safety hints; the description goes further by disclosing the async processing state and the literal result contract ('says NOT PLACEABLE YET and ends with a NEXT line'). With no output schema, that return-shape detail is real added value. It stops short of describing what a successful, placeable completion returns.

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

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

Three short sentences, front-loaded with the action and precondition, then the edge case and its remedy. Every sentence carries distinct information; the quoted result tokens are precise rather than 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?

For a two-parameter mutation tool with no output schema, the description covers the action, the ID source, the failure-mode branch, and the follow-up tool. The remaining unknowns (idempotency, safety) are already supplied by annotations, so an agent has what it needs 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 50%: projectId is well documented in the schema, but assetId carries no description there. The description compensates by explaining assetId's provenance ('returned by begin_asset_upload'), which is the one piece of semantics an agent couldn't infer. projectId semantics 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 ('Complete an upload') and anchors it in a lifecycle by naming the predecessor tool ('after the upload commands succeed', 'the Asset ID returned by begin_asset_upload'). This clearly separates it from begin_asset_upload and wait_for_asset in the sibling list.

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

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

Gives an explicit precondition for calling (after upload commands succeed) and an explicit branch condition that routes to the alternative ('A video may still be processing ... call wait_for_asset with the Asset ID'). The when-to-use and the when-to-switch-tools case are both spelled out.

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

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

Annotations declare the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false) but say nothing about latency or cost; the description supplies both — the call returns a Job ID immediately with background generation, and it costs roughly 27 credits/second standard and 42 credits/second pro (399 credits for a 15s trend). It also states the 3–30s video constraint, which is behavioral context beyond the annotations.

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

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

One dense paragraph, front-loaded with what the tool does before moving to constraints, workflow, and cost. Every sentence carries information, though the workflow/cost tail is long enough that an agent must read to the end for the credit and wait_for_jobs details.

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?

No output schema exists, so the description must explain the return path — and it does: an immediate Job ID, background generation, and retrieval of the Asset ID via wait_for_jobs for patch_film. Combined with input constraints, credit cost, and the long-video workaround, an agent has everything needed to invoke and follow through.

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 every parameter, including the asset:ID#t= syntax for 'person' and the null semantics for prompt/keepSound/projectId. The description reinforces a few of these (quality tradeoff, trimming for long videos) but adds little the schema does not already say, so the baseline 3 applies.

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

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

States a precise verb+resource ('make the person in a picture do what the person in a video does') and immediately scopes the output ('the new video shows the person and the setting of the picture... for the video's whole length'). This is clearly distinguishable from siblings like generate_video, replace_person, or apply_effect.

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

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

Gives real context: best-case input conditions (one person, full or upper body in view), how to handle longer source videos (download_asset link plus import_asset_url with startSeconds/endSeconds), and the async workflow (start all generations, then wait_for_jobs, then patch_film). It stops short of explicitly naming which sibling to use instead when the source is not a video or when the subject isn't a person, so it isn't a full when/when-not routing guide.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false), and the description adds rich behavior beyond that: model samples one frame a second, details carried between frames, re-checks, per-detail object tracks, black-box region on a new track in front of the clip, and credit cost (~2.3/frame, ~61/minute). This is unusually thorough behavioral disclosure.

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

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

The purpose is front-loaded, and the cost sentence earns its place, but the body is a dense run-on stitched with semicolons that buries the operational details. Structure could be tightened without losing 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?

There is no output schema, but the description explains the return value ("answers each detail with its times and the track and cover it wrote"). Combined with cost, processing model, and full parameter coverage, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all six parameters including the faces/atSpace/projectId semantics. The description reinforces that faces being true also covers people but adds no format or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (find and cover) and resource (private details in what a film clip plays), and enumerates the concrete detail types (labels, receipts, cards, plates, IDs, barcodes, screens, faces). An agent can clearly separate this from siblings like track_faces, track_box, or cutout_subject.

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 for every request to hide, blur, censor, mask or redact private information" plus the condition "when the edit is to be posted" gives explicit when-to-use. It also states when-not: "never cover them by hand with a blur or a fixed box," routing the agent away from manual alternatives.

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

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

Annotations already disclose the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so a write op that is non-idempotent is known. The description adds two useful behavioral facts beyond annotations: the call returns a version id, and switchToBranch must be set explicitly, implying a side effect on the active branch. It does not say what persists or how the new branch relates to sourceBranch 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?

Three short sentences, front-loaded with the action and source, followed by the two facts an agent needs before calling. Every clause earns its place with no 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?

For a 4-required-parameter mutation tool with no output schema, the description covers the return value ('version id') but is thin on the three undocumented parameters and on how created branches interact with the surrounding branch workflow. Adequate but with clear gaps.

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

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

Schema coverage is only 25% – the schema documents projectId but leaves branchName, sourceBranch, and switchToBranch bare. The description partially compensates by tying the creation to sourceBranch and implying branchName is the version's name, but it never explains what switchToBranch actually does beyond 'set it explicitly,' leaving a required boolean under-specified.

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

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

States a specific verb and resource: 'Create a named project version from sourceBranch.' An agent can tell this apart from sibling branch tools like list_branches, switch_branch, diff_branches, and merge_branch, though the description never names them 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?

'Set switchToBranch explicitly' is a parameter instruction, not usage guidance. There is no statement of when to create a branch versus switching or merging, no prerequisites, and no mention of the sibling tools that would be the alternatives.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description's contribution is the two behavioral facts they omit: the project is created empty, and it is automatically opened (changing active-project state, which matters given get_active_project). It says nothing about failure on duplicate names, but the key side effect is disclosed.

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

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

Two short sentences with no filler, and the primary action plus its side effect are front-loaded before the parameter note.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile. For a one-parameter mutation the description is nearly sufficient; only edge-case behavior (e.g., name collision) is unaddressed.

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

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

Schema description coverage is 100% and the single parameter already documents 'null gives the default name.' The description merely restates that fact, adding no syntax or constraint beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create an empty project') and adds the immediate side effect ('and open it'), which distinguishes it from open_project and list_projects. It does not explicitly name a sibling, but the 'empty' qualifier separates it from template/scaffold flows.

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

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

Usage is only implied: an agent can infer this is for starting a new blank project versus open_project for existing ones, but there is no explicit when-to-use or when-not-to-use statement, and no mention of the alternative for creating from a template.

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 far beyond the annotations: it explains the tracking/matting algorithm (found and tracked per frame, matted from one full-visibility frame forward and backward), that off-picture frames are black, that the matte is black before startTime and ends at endTime, and how the result binds via mask= in patch_film. It also discloses billing, which no annotation covers. This is exactly the mutating, cost-incurring context an agent needs.

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 core outcome (what a matte is and the returned Asset ID) before the mechanics and prerequisites. Three dense paragraphs are justified by the tool's complexity, though a few clauses (e.g. repeated null-handling) could be tightened.

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

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

For an 8-parameter, no-output-schema mutation tool, the description covers the return value, the workflow preconditions, time-range semantics, cost, and downstream usage. An agent has everything needed to invoke it correctly without further documentation.

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

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

With 88% schema coverage the baseline is 3, but the description meaningfully extends it: it clarifies that `at` must be a verified full-visibility second, that subject phrases must name one kind of thing (conjunctions find neither), that a video range is cut only inside startTime/endTime while an image takes null, and that nulls mean whole asset. It adds interpretation rather than repeating 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: cut a person or named subject out of a video or image as a soft matte, with the exact output semantics (white = subject, black elsewhere) and the return value (a matte Asset ID). It is very clear about what it produces, but never names the siblings it competes with (remove_background, segment_subject), so an agent must infer the distinction.

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

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

Gives concrete preconditions and a workflow: look at the footage with preview_frame or read_asset first, then pass `at` at a second where the subject is fully visible, and restrict startTime/endTime to the range where the subject is on screen. The cost guidance (about 76 credits a minute, billed by the second) tells an agent when to be careful, though no explicit alternative tools are compared.

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 readOnlyHint=false, so the mutation profile is covered. The description adds genuinely useful behavioral detail beyond that: the two guard conditions that cause refusal, the error payload shape (build output naming the importing component), and that a version-id delete does not switch the editor. It does not discuss irreversibility or recovery, but the refusal semantics are the key risk context.

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

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

Three sentences, all load-bearing: scope, refusal conditions, then branch targeting. Front-loaded with the action and resource. Slightly dense, but no filler; a small structural tweak (bullets for the two refusals) would be the only improvement.

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?

No output schema exists, and the description compensates by describing failure output (build output naming the importer) and the absence of editor state change for version-scoped deletes. Combined with annotations covering safety, an agent has enough to call it correctly; only successful-return shape is unspecified.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including branchId null semantics and projectId behavior. The description restates branchId's non-switching behavior rather than adding syntax or format meaning, so the baseline 3 applies.

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

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

States a specific verb (delete) plus the two exact resource forms it handles: a custom TypeScript component, or a shared module named shared/<name>. This distinguishes it from siblings like patch_component, replace_component, and scaffold_component 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 states two refusal conditions (component placed by the film, component imported by another) and routes the agent to the remedy: remove its <use> and clips with patch_film first. Also explains branchId null vs a version id from list_branches, naming the sibling to call first.

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, and the description adds real behavior beyond that: the refusal conditions, the fact that the error enumerates each importer, and that the rendered video itself does not change. These are exactly the details an agent needs before an irreversible delete.

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 action and its refusal conditions; every sentence carries usable information. The sentence about importers and patch_film is slightly dense 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, non-idempotent tool with full schema coverage and no output schema, the description covers what it deletes, what it refuses, what it leaves untouched, and how versions are targeted. Only the shape of a successful response is left implicit, which is minor.

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

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

Schema coverage is 100% and the property descriptions already document path, branchId and projectId with the same semantics restated here (null/omitted means current version, version id from list_branches). The description adds little beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ("Delete a module film file such as brand.film from the project") and immediately bounds the scope with concrete examples of what it is not (main.film). The example filename makes it distinguishable from delete_component, delete_project and replace_film.

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 an explicit when-not: refused for main.film and refused while a film file imports the module, plus the corrective action (use patch_film to remove the <import> and alias uses first). It does not compare against sibling deletion tools, but the usage context is clear enough to act on without experiments.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavior: deletion propagates to every device (sync scope) and the currently open project is rejected. It stops short of stating reversibility explicitly, but the destructive hint covers that.

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

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

Two tight sentences. Scope (every device) is front-loaded, then the refusal condition and its remedies. 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?

Output schema exists, so return values need no explanation. For a destructive single-param tool, the description covers scope, id provenance, and the blocking precondition — everything needed to invoke it correctly.

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

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

Schema coverage is 0%, so the description must carry the param burden for projectId. It does add real meaning by naming the source of the id ('from list_projects'), but gives no format, prefix, or validity guidance. Partial compensation for a single undocumented parameter.

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

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

States a specific verb+resource ('Delete a project') plus two distinguishing scopes: by id, and 'on every device'. An agent can distinguish it from update_project, list_projects, and open_project 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 names the id source (list_projects) and an explicit when-not case: the open project is refused, with two concrete remediation alternatives (open_project, create_project). Nothing is left to inference.

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

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

Goes well beyond the annotations by disclosing credit economics (no credits for 8s+ audio, ~1.1 credits per minute billed by the second), that the grid is persisted, and that ranged beats replace existing grid beats only within that range. The downstream binding hint ('Beats= in film props') is a useful behavioral detail no schema carries.

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

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

Purpose and side effect are front-loaded, and every clause carries operational information (modes, credits, binding). It is dense to the point of run-on sentences in the middle section, costing some readability without adding fluff.

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

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

For a mutating analysis tool with no output schema, the description covers what is produced, what is stored, what is overwritten, what it costs, and how to consume the result. An agent has everything needed to call it correctly.

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

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

With 75% schema coverage the schema already defines startTime/endTime, but the description adds real meaning: the range should match the shots being built, only that range is read and billed, and times stay in source seconds. projectId is never touched in the description, leaving the schema to carry it alone.

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 (detect beats and bars) plus the side effect (stores the grid) and enumerates the return payload: beat times, downbeats, sections, drum hits, fills. This clearly distinguishes it from neighbors like detect_scenes, detect_geometry, and measure_mix.

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 an explicit sequencing rule ('Do this before cutting to music') and routes between two modes: full-file analysis for an 8-second-or-longer sound vs. a ranged read for video audio or short sounds. It stops short of naming sibling alternatives (e.g., measure_mix) for related analysis needs.

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), and the description adds substantial extra context: determinism ('not a guess'), sub-pixel corner refinement, quad quality scoring, output shape (prose first, one json block after), coordinate spaces returned, cost ('Free') and latency ('under a second'). It even flags a not-yet-implemented capability (overlay returns a note).

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

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

The purpose sentence is front-loaded and every later clause carries real information about precision, output or performance. The 13-argument example call is bulky and slightly crowds the prose, shaving a point off an otherwise efficient structure.

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

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

For a 13-parameter tool with nested objects and no output schema, the description covers enough: it explains the return format, the result spaces, cost and speed, and the availability caveats for text/depth and overlay. Deeper ROI/space composition semantics are left entirely to the schema, which is rich but densely nested.

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; the description still adds meaning by showing a full example call that makes the null-default conventions concrete and by explaining semantic defaults (null time reads a preview's own second, quads carry true aspect when focal is known). It does not individually annotate the more obscure parameters (roi, edgeOf) beyond the schema, keeping it below a 5.

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 names a specific verb and an enumerated set of resources (edges, straight lines, corners, quads, vanishing points, trackability) scoped to 'one frame of an asset, a clip or the composed film'. The subtitle and body make the boundary against siblings like snap, pin_moment, track_plane and find_objects easy to infer.

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 usage: 'Use it before a pin or a surface track to get exact corners, or to check whether a region has enough texture to track', and explains when trackability is the right kind (blank white sign → edges). It also warns that text/depth kinds return a note rather than results. Lacks a direct comparison to other detection-family siblings such as find_objects or track_detection.

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

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

Annotations only declare non-destructive write semantics (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description adds the operation targets the source asset not the timeline, that times are seconds into the asset, that credits are charged per second read, and that long videos return a Job ID requiring wait_for_jobs. It also discloses that read_analysis_range returns the latest run, whole or ranged. This is substantive behavior beyond the annotation set.

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 purpose, then usage, then cost/job semantics, then the read path — a logical order with no filler sentences. It is dense and slightly long, and the parenthetical examples could be trimmed, but nothing is redundant.

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

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

There is no output schema, so the description carries the return-value burden and does: it names the fields returned (time, frame, confidence, scene list), the async Job ID path plus the rendezvous tool, and the read tool for boundaries. Nothing an agent needs to call and consume this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: startTime/endTime clip what is read and billed, and null/null reads the whole asset. It does not, however, explain threshold (documented only in the schema), so it does not fully surpass 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 ('Find where the shots change') and enumerates outputs (hard cuts, dissolves, fades, each with time, frame, confidence, plus the scene list). It is clearly separable from siblings like detect_beats, which it is explicitly sequenced against.

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 when-to-use ('footage that is already edited (vlogs, compilations, screen recordings with cuts)') and a workflow position ('before cutting to the beat or trimming or reframing shot by shot'). It also names the downstream tool for retrieving results (read_analysis_range kind scenes), so the agent knows both entry and follow-up.

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 safety is covered. The description adds genuinely new behavior: diff orientation convention, header naming, and paginated windowing where 'the answer says the offset to read on from' — useful for an agent driving a loop. It doesn't mention diff size limits or truncation caveats beyond paging.

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

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

Four compact clauses, front-loaded with the diff semantics and ending with the paging behavior an agent needs at call time. Slightly awkward phrasing ('A long diff comes a window of lines at a time') costs a little polish but no information 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?

There is no output schema, so the description carries the return-format burden and does so: it explains the +/- convention, per-file headers, and the pagination continuation. Only gaps are error/edge behavior (identical branches, missing ids) which an agent might reasonably wonder about.

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

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

Schema coverage is 60%, with sourceBranch and targetBranch having no schema descriptions at all; the description compensates by defining directionality (source -> target) and how to pick a source for a single-version diff. It also reinforces the offset continuation contract that the schema hints at, adding loop semantics rather than repeating 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?

States a specific verb and resource ('show what changes from sourceBranch to targetBranch') and immediately defines the semantics of the output ('- lines are sourceBranch's, + lines are targetBranch's'). This clearly separates it from sibling tools like merge_branch, list_branches, and switch_branch.

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: 'To see what a version changed, pass the version it was made from as sourceBranch' and 'Get ids from list_branches.' It does not say when not to use this tool (e.g., versus reading a film or transcript), but the positive guidance is strong and actionable.

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 safe-read profile (readOnly, idempotent, non-destructive), yet the description adds real behavioral detail: the link expires after hours, reads only that one file, supports HTTP Range/resume via curl -C -, and can be re-fetched by calling again. This is exactly the value-add expected beyond 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 core outcome, then layers return shape, resume capability, expiry handling, and constraints in order. It is dense but every sentence carries information an agent needs; nothing is redundant 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?

No output schema exists, but the description fully compensates by enumerating the return fields (link, expiresAt, name, MIME type, byte size, curl command). Combined with the prerequisites and anti-pattern warning, an agent has everything required to call and use the result correctly.

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

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

Schema description coverage is 100%, and the schema already explains file/assetId/projectId semantics thoroughly. The description adds return-shape detail but no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource ('Get a temporary download link for an asset's file in the cloud') and immediately clarifies what the link is (a presigned HTTPS URL scoped to one file). An agent can tell this apart from read_asset, which would return content rather than a link.

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

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

Explicitly states when to use it ('give the link to the user when they want to save the file, or run the command from the agent machine'), when NOT to ('Do not fetch the file through tool calls'), and a prerequisite ('a file still uploading or processing cannot be downloaded yet: call wait_for_asset first').

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

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

The description adds substantial behavior beyond the annotations: it explains how corner movement is weighted and propagated, how lost frames are handled, that the fixed frame becomes tracked, what the answer ends with, and that a preview_range check should be run. This is exactly the kind of operational detail an agent needs for a mutation tool.

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

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

The purpose is front-loaded in the first sentence and the rest is relevant. It is dense and somewhat long, but the complexity of the propagation model and the coordinate handling justify most of the length.

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

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

Given twelve required parameters, no output schema, and non-trivial propagation behavior, the description is complete enough to call the tool correctly. It explains the core mechanics, expected result, and how to verify the outcome with preview_range.

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. The description nevertheless adds practical parameter meaning by explaining how corners, box, and points are used together, how preview-space coordinates should be passed with previewId, and how propagate and until control the carried fix.

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: fix one frame of an object track and carry the fix to neighbours without rerunning the tracker. This clearly distinguishes it from tracking tools such as track_points, track_box, or smooth_track.

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 usage context: pass corners, box, or only wrong points, in any coordinate space, and fix the first frame of a flagged range before letting the correction fade. It also tells the agent to check the result with preview_range. It stops short of explicitly comparing when to use this versus offset_track or smooth_track, so it is not a full 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 cover the safety profile (not read-only, not idempotent, open world), and the description adds far more: it returns a Job ID immediately, media renders in the background, and the agent must call wait_for_jobs then patch_film. It also discloses per-second credit cost (38/s, 48/s with references), the 3–10 second constraint, and exactly how to place the returned clip on the timeline.

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?

Long but front-loaded: the core action comes first, then references, then constraints, then job flow and cost. Every sentence earns its place, though the timeline-placement paragraph is dense enough that it could be split for readability.

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

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

For an asynchronous, credit-consuming, open-world generation tool with no output schema, the description supplies the duration limits, cost model, job/asset lifecycle, and placement rules an agent needs to call and use it correctly. Nothing material is missing.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the description adds real meaning: it explains that group clips are edited as one picture, how startSeconds/endSeconds select a part versus the whole asset, and gives prompt examples (colour, clothing, object swap, style). It does not fully restate the references syntax, which the schema already covers in depth.

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 what a video shows from a written instruction — and immediately distinguishes the operation from generate_video, replace_person and copy_motion by naming them explicitly. An agent knows exactly what this produces (an edited video preserving motion, camera, timing, sound) without opening a schema.

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

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

It routes the agent to the builtin-generative-video doc and names replace_person and copy_motion as alternatives, and it explains when to use references versus a plain prompt. However, the when-to-use-which condition is deferred to an external doc rather than stated here, so it falls short of a self-contained 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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, which is slightly surprising for a 'find' operation; the description doesn't clarify what side effect or state change makes it non-read-only, nor any job/latency behavior. It does add genuine context on return shape and coordinate spaces, but the annotation safety profile is left unexplained.

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

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

Front-loads the core action and return format, then terse parameter notes and the doc prerequisite; no filler. The telegraphic phrasing ('at is a source second') is dense but readable and short for the amount of information conveyed.

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

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

For an 8-required-parameter tool with no output schema, the description does cover return structure, defaults, coordinate spaces, and points to reference docs. It still omits the semantics of `queries`, what threshold means, and why the operation isn't read-only — gaps an agent would hit before a first successful call.

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

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

Schema coverage is only 38%, so the description must compensate. It does explain `at` (source vs film seconds), `atSpace`, and gives typical values for `threshold` and `maxResults`, but never explains `queries` (name strings?) or `assetId`, leaving two required parameters undocumented in both places.

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

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

States a specific verb+resource: 'Find named objects on a source frame', and adds what it returns (numbered detections, an image, a json block with boxes in source/film/film_norm). It does not explicitly distinguish itself from sibling detection tools such as track_detection, track_faces or track_box, so an agent must infer 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?

Gives a prerequisite ('Read builtin-object-tracking first') and states standard values (threshold 0.15, maxResults 8), which is useful context for calling it. However, it gives no when-to-use/when-not guidance against the many sibling tracking tools, leaving selection 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?

Goes well beyond the annotations: it discloses the conditional-write guarantee ('writes only when the result has no more errors than before'), the reporting behavior ('reports each repair and what still needs an edit'), and the precise semantics of unsafe including concrete examples of guesses. This is exactly the context annotations cannot carry.

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

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

Front-loaded with purpose and the sibling contrast, then layered behavioral guarantees, then parameter semantics. Dense but every sentence carries distinct information with no filler.

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

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

With no output schema, the description verbally covers the return profile (each repair plus outstanding edits), and it covers the mutation safety story and version targeting. Nothing an agent needs to call this tool safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description still adds value: concrete examples of what counts as a 'guess' under unsafe, and the branchId 'fixes that version' behavior. Some overlap with the schema text keeps it from a 5.

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 ('Autofix main.film') and immediately distinguishes itself from the two closest siblings, patch_film and replace_film, by naming what those tools do and how this one differs. An agent can route between the three 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 gives when-to-use ('problems the film already had, which a write reports and leaves alone') versus when the siblings apply, and adds conditional guidance for the unsafe flag ('Leave it false unless the report names a guess you want'). No inference required.

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

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

Beyond the annotations, the description discloses critical operational behavior: it returns a Job ID immediately, renders in the background, requires wait_for_jobs for Asset IDs, and feeds patch_film. It also gives exact credit costs by image size, which is important for deciding how to call it.

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

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

The description is front-loaded with purpose and when-not-to-use guidance, and most sentences earn their place by covering references, async behavior, and cost. It is dense and somewhat long, but not repetitive.

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?

There is no output schema, yet the description explains the async return flow from Job ID to wait_for_jobs to Asset ID and patch_film. It covers reference usage, size/cost tradeoffs, and the key alternative of reusing source footage, so an agent has enough to call it correctly.

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

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

With 60% schema coverage, the description compensates substantially by explaining reference-image intent and ordering, plus cost differences for imageSize and a default recommendation of 1K. It adds less guidance for aspectRatio choices and does not elaborate on prompt semantics, leaving some gaps.

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

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

The description opens with a specific verb and resource: "Generate an image from a prompt." It clearly distinguishes this tool from video generation and from reusing existing footage, so an agent can identify its role 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 gives explicit when-to-use and when-not-to-use guidance: first consider a frame of the person's own footage for stills, thumbnails, before/after, or text-over-shot edits, and generate only when the picture must show something the footage does not hold. It names alternatives such as a frame found with read_asset and a template slot, and explains reference-image strategies.

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

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

Annotations only declare it as a non-readonly, non-idempotent, open-world write; the description adds the critical operational facts: it returns a Job ID immediately while media renders in the background, requires wait_for_jobs with all Job IDs to obtain Asset IDs, costs about 0.95 credits per second (57 for 60s), and what a credit refusal means. It also discloses the analysis payload returned with the Asset ID (tempo, beats, downbeats, drops, per-second loudness, sections, fills) so the agent knows what it gets back.

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

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

Front-loaded with the core action, duration options, and the search_stock-first rule. It is dense and long, but for a tool with no output schema most sentences (async job flow, cost, returned beat data) are load-bearing; the return-field enumeration is the one stretch that could be tightened.

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

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

A generative, credit-spending async tool with no output schema, and the description covers all the gaps that matter: alternatives, cost, async lifecycle, failure mode on credit refusal, and the full shape of the returned analysis. Nothing an agent needs in order to call it correctly and consume the result 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?

Adds real meaning beyond the 60%-coverage schema: forceInstrumental true excludes singing, hero is explained as the film second the strongest drop must land on plus the returned offset, and the description clarifies that prompts cannot place hits at exact seconds and should describe shape instead. prompt's content strategy and duration are covered; projectId semantics live only in the schema, which keeps this from a 5.

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 ("Generate music from a prompt") plus the constrained output lengths, and explicitly distinguishes itself from search_stock and generate_sfx in the same breath. An agent can tell exactly what this produces versus its nearest 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?

Gives an explicit routing rule with a preferred alternative and its argument: "First search_stock with kind music... generate only when no track fits", and "Use generate_sfx for sound effects." It also states when to use hero versus second-by-second prompt requests, which is a genuine when/when-not 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 mark the tool as not read-only, open-world, non-idempotent, and non-destructive. The description adds substantial context beyond that: asynchronous Job ID returns, background media creation, credit cost (~0.76 credits/second, with a 3-second example), three takes kept by role fit, and automatic measured placement/volume metadata.

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 core action and the library-first alternative, then layers in async behavior, cost, and output semantics. The volume of detail is justified for an async generation tool, though the prose is slightly dense and could be tightened in a few places.

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

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

For a 5-parameter async generation tool with no output schema, the description fully explains the return flow (Job ID, then wait_for_jobs to get Asset ID) and downstream use with patch_film. It also covers cost, role-based take selection, and placement metadata, leaving no major gap for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters in detail, including role, loop, durationSeconds, projectId, and prompt. The description adds only marginal parameter context, such as relating duration to credit cost, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Generate a sound effect from a description') and explicitly distinguishes itself from sibling alternatives by routing library-first to search_stock with kind sound and import_stock. An agent can tell immediately that this is for creating new AI-generated sound effects only when the stock library lacks an option.

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 first try search_stock with kind sound and import_stock at no cost, and to generate only sounds the library does not have. It also lays out the async workflow: start every generation needed, keep working, then call wait_for_jobs with all Job IDs to get Asset IDs for patch_film.

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

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

Annotations already flag openWorldHint=true and idempotentHint=false, but the description adds real behavior beyond them: the call returns a Job ID immediately while media renders in the background, unknown tags are silently dropped, cost is metered (7 credits/1000 chars, 8 credits per cloned-voice call), and cloned text is capped at 600 chars. That is substantive operational context an agent cannot get from 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?

Front-loaded with purpose and alternative routing, then progressively deeper into async flow, cost, and cloning. It is dense and runs long as a single block, but every sentence carries operational information; a small structural loss for length, not for 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 complex 9-parameter, async, credit-metered generation tool with no output schema, the description covers the full lifecycle: input constraints, immediate Job ID return, wait_for_jobs to recover Asset IDs, downstream patch_film and transcribe_asset, and the alternate cloned-voice path. Nothing essential for a correct first call 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 already 89%, covering voice enum roles, style, speakers, language, and voiceAssetId constraints. The description largely restates this ('style directs the delivery in plain words', 'speakers turns "Name: line" text into a dialogue') rather than adding new syntax or format detail, so it sits at the baseline for a well-documented 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: 'Generate a voiceover', and immediately scopes it to speech vs. the sibling media generators (generate_music, generate_sfx, generate_image). An agent can distinguish it from lip_sync, transcribe_asset, and isolate_voice because the description names those as downstream or separate tools.

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

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

Explicit when-to-use rules: 'Read builtin-voiceover first' for tags, 'Put one voiceover or one whole dialogue in one call rather than splitting it', 'start every generation you need... then call wait_for_jobs'. It also names prerequisites (3-15s clean stretch from read_transcript times) for the cloning path and names the alternative API surface (voiceAssetId over voice).

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 that the tool returns a Job ID immediately, generates media asynchronously, and requires wait_for_jobs. It also explains credit charging per second by quality and resolution, quality escalation for impossible combinations, and the irreversibility of silent video, which are important behavioral traits for an agent.

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 content is front-loaded with the main generation modes and every sentence carries useful operational information. However, it is a dense single paragraph and could be easier to scan if the async, credit, and quality rules were separated.

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

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

Despite having no output schema, the description fully explains the asynchronous return path via Job ID and wait_for_jobs, plus the credit and quality constraints. It gives an agent everything needed to invoke the tool correctly and handle common failure modes.

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

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

With 67% schema coverage, the description meaningfully supplements the schema by adding defaults, duration bounds, quality behavior, audio caveats, and the reference syntax with prompt-calling examples. It adds real semantic guidance beyond the structured parameter descriptions.

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 and clearly separates three modes: prompt-only generation, image animation via referenceAssetId, and multi-reference composition via references. This distinguishes it from siblings such as generate_image and render_video without needing to open 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 gives explicit when-to-use rules for the quality tiers, says to set generateAudio to false only when the person asks for a silent video, explains when to use references versus referenceAssetId, and specifies retry behavior after a credit refusal. These are actionable selection and invocation guidelines rather than implied usage.

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 safety behavior is fully covered. The description adds only the 'active project context' nuance and says nothing about what happens when no project is open (e.g. an error or null).

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 short sentence with no filler, and the resource context is front-loaded. Nothing can be trimmed without losing meaning.

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, and annotations carry the safety profile, so the definition is nearly complete for a zero-param read. The only gap is the no-project-open edge case.

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 takes zero parameters, so the schema baseline is 4 and there is no parameter meaning to add. The description is appropriately silent on inputs.

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 'Show' plus the resource 'the Vidova project the editing tools act on' clearly identifies this as a read of the currently active project. It implies the active/current scope without literally naming the sibling it differs from (list_projects, open_project).

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

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

Usage is only implied via 'the editing tools act on', which gestures at the active-project concept but never says when to call this versus list_projects or open_project. No exclusions or prerequisites are given.

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

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

Annotations declare write/openWorld/destructive=false, but the description adds substantial behavioral context beyond them: an async placement state (NOT PLACEABLE YET), the wait_for_asset handoff, size ceilings (2 MB data, 10 MB font), and that fonts return a family name. It doesn't cover auth or failure modes, but the added value is strong.

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

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

Front-loaded with the core action and the key async caveat, which is good. However it is dense and slightly overgrown, with an interstitial example URL and a fragmented sentence ('So does a font file...') that reduce readability without adding much.

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?

No output schema, so the description carries return-value burden and does so: it states an Asset ID is returned, the ready/placeable workflow, and font family naming. Combined with the partial schema it is close to complete, though the start/end range behavior is handled only by the schema, not the description.

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 60%; the two undocumented params (url, fileName) are exactly the ones the description clarifies ('direct HTTPS URL', 'filename including extension'). The projectId/start/end params already carry schema descriptions, so the description fills the real gaps rather than repeating them.

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

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

States a specific verb and resource ('Import media from a direct HTTPS URL') and enumerates the media kinds it accepts (video, data files, fonts). It is clearly distinct from siblings like import_stock or import_gif by being URL-driven, though it does not explicitly name 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?

Gives clear procedural guidance: supply a filename with extension, and if the result says NOT PLACEABLE YET, call wait_for_asset before use. It explains the accepted data-file and font scenarios, but leaves implicit when to prefer this over upload_files or the other import_* 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?

Adds real context beyond the annotations: the idempotent behavior is grounded ('if the element is already in the project, returns the existing Asset ID'), the non-obvious branch semantics (write a version without switching the editor) are disclosed, and the return value is named. The 'returns existing Asset ID' phrasing partly restates idempotentHint=true, but the branch-write behavior is genuinely extra.

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

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

Front-loaded with the core action and the search_elements dependency; each sentence carries routing or behavioral information. A few telegraphic fragments and the 'Bind analysis with transcript=, beats=, audio=, or track=' line are dense and slightly disconnected, keeping it below a 5.

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

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

With no output schema, the description correctly names the return value (Asset ID), covers the idempotent-return case, the branch/version behavior, and the downstream placement step. Nothing an agent needs to invoke this 3-param mutation correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds provenance and a guardrail ('Pass elementId from search_elements', 'Do not invent ids') that the schema does not state. branchId and projectId semantics largely echo the schema rather than extending 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?

States a specific verb+resource ('Import a published library element into the project as-is') and immediately disambiguates from siblings: elementId comes from search_elements, source/inputs are fixed by the library, and replace_component is named as the wrong tool for plain copying. An agent can distinguish this from add_from_library, scaffold_component, and read_element without opening schemas.

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

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

Explicit routing: fetch elementId via search_elements, place the result with patch_film, and a clear when-not ('Do not use replace_component to copy the source unless you need to change it'). The branchId condition (null = current version; version id = write that version without switching the editor) is spelled out rather than left to inference.

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

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

Annotations already declare this is a non-read-only, open-world, non-idempotent, non-destructive operation. The description adds substantial value beyond that by stating the return value (an Asset ID), the placement follow-up (patch_film), looping behavior, a warning against inventing ids, and that credits are not consumed.

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

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

The description is compact and front-loaded: purpose first, then parameter coupling, then return and placement, then behavioral notes. Every sentence contributes practical 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?

Even without an output schema, the description explains the returned Asset ID and how to use it. Combined with complete parameter descriptions and annotations covering safety, an agent has everything needed to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does restate that gifId, query, kind, and offset must match the prior search_gifs call, but this mostly duplicates what each schema parameter description already says.

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 (import), resource (one GIF or sticker), source (search_gifs), and destination (open project as an animated image asset). It cleanly distinguishes the tool from siblings like search_gifs, import_stock, and import_asset_url.

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

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

It specifies the required upstream context: pass the gifId and the same query, kind, and offset as the preceding search_gifs call. It also directs the agent to place the resulting asset with patch_film. However, it does not explicitly name when to choose this over alternatives such as import_stock or add_from_library.

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

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

Annotations already declare this is a non-read-only, open-world write. The description adds value beyond them: it discloses that the domain is re-resolved on this call, that no credits are consumed, and that the result is an Asset ID. It does not address re-import behavior or error cases, but the added operational facts are meaningful.

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?

Six short fragments, front-loaded with the action and resource before the workflow and cost notes. Every sentence carries information, though the staccato style slightly fragments the related constraints.

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

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

No output schema exists, and the description compensates by naming the return value (Asset ID) and the follow-up tool (patch_film). For a three-parameter mutation this is nearly complete; only failure/duplicate behavior is left unspecified.

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 real semantic coupling: 'the same domain' must match search_logo, and ids must come from that search. It adds meaning beyond the schema text without restating projectId, which the schema already explains.

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

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

States a specific verb and resource ('Import one logo ... as an image asset') and names the source tool (search_logo) and destination mechanism (patch_film). An agent can distinguish it from import_asset_url, import_gif, and add_from_library without opening a schema.

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

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

Gives clear workflow context: pull domain and logoId from search_logo, don't invent ids, place the result with patch_film. It stops short of explicitly excluding the adjacent import_* siblings, but the sourcing constraint makes the intended path unambiguous.

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

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

Annotations only declare readOnly=false, idempotent=false, destructive=false; the description goes well beyond by explaining, per asset type, exactly what assets get created, what the answer contains (clip with numbers filled in, bpm/length/loudness/hit second, license/credit requirement), and that 'Nothing is charged'. It does not warn that repeat calls create duplicates (relevant given idempotentHint=false), which keeps it off 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?

The first two sentences are front-loaded and excellent, but the body is one sprawling paragraph of run-on, comma-chained sentences per asset type, mixing internal jargon (<chroma>, <group>, patch_film, 'the action', 'the payoff'). The information mostly earns its place, but a bulleted per-asset-type structure would make it far more scannable.

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

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

For a tool with ten distinct asset-type behaviors, no output schema and a destructive-but-unannotated write, the description does the heavy lifting by describing the return value per type and required follow-up calls. Missing are failure modes (bad id, unsupported type) and the duplicate-on-repeat behavior, but it is otherwise sufficient to invoke correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented, including examples of valid ids and the projectId/open-project behavior. The description reinforces the id source ('Do not invent ids', 'Pass its id') but adds no format or syntax detail beyond the schema. Baseline 3 applies.

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

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

The opening states a specific verb, resource and scope: import one item from search_stock into the project as an asset, and it names the source tool (search_stock). The subsequent per-type breakdown makes the resource concrete. It does not differentiate from near-identical siblings such as add_from_library, import_element or import_gif, so an agent cannot rule those out from this text alone.

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

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

It gives real usage constraints for the input ('Pass its id', 'Do not invent ids', ids come from search_stock) and describes what to do after the call (patch_film, place on action, set offset/volume). However, there is no explicit when-to-use vs when-not guidance against the many sibling import/search tools, so selection is only implied.

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

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

Goes well beyond the annotations: pricing (about 22 credits per minute, billed by the second), the fact that credits are not refunded on failure or deletion, adaptive segment lengths by video duration, the minimum 4-second range, the dedup rule, that it does not block editing, and that it is asynchronous and must be polled via read_video_intelligence with the returned jobId. These are the exact behavioral facts an agent needs before committing spend.

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 and every sentence carries operational information, but the paragraph is dense and long, and the segment-length sentence sits awkwardly between the whole-video rule and the range-selection guidance. A slight restructure would improve scanning without cutting 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?

Output schema exists and the description still names the return type (a job) and the exact follow-up tool and field (read_video_intelligence with jobId). Combined with cost, dedup and safety notes, an agent has everything required to call this correctly and sequence the next step.

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, and the description does add real meaning: mediaId is the Asset ID from search_assets or a Library id, and null/null on both seconds means the whole video. The startSeconds/endSeconds pairing and the 4-second minimum are already in the schema, but the segment-length-by-duration rule is new information 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?

States a specific verb and resource ('Index a Library video') and immediately names the downstream consumer (search_video_moments) so the agent can place it in the pipeline. It also calls out the re-index-one-range variant, which separates it from any sibling that merely reads or searches video.

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 when-to-use logic: whole-video indexing only for an older, disabled or failed video because new uploads are automatic; range indexing only when a search moment is too coarse, with instructions to widen the moment's bounds by a few seconds. It also states the no-op condition (densely covered range returns the existing job) so the agent can avoid a pointless call.

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 disclosing that the call returns immediately with a Job ID, media is produced in the background, output is a new full-length sound asset in sync from the first second, and the exact cost model (0.63 credits/second, ~38 credits for a 1-minute clip). Annotations only cover the read/write and idempotency profile; the description adds the operationally critical async, cost, and output-shape details.

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

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

Purpose is front-loaded in the first sentence, and the remaining sentences cover placement, async behavior, and cost — all functional. It is dense and slightly long, but every sentence carries real information with little 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 an async, cost-bearing generation tool with no output schema, the description is complete: it explains the immediate Job ID return, the background processing model, how to retrieve results (wait_for_jobs → Asset ID for patch_film), and how to integrate the result on the timeline. Nothing an agent needs to invoke and follow up correctly is missing.

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

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

Schema coverage is 100%, so both parameters (assetId, projectId) are already fully documented in the schema, including the 30-minute limit and null-project behavior. The description adds no new parameter-level syntax or format detail, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Clean the speech of a video or a sound: keep the voices and remove the rest') with concrete examples of what gets removed (baby crying, wind, traffic, music, crowd, echo). It clearly distinguishes itself from siblings like split_sound, remove_background, and cutout_person by specifying voice isolation.

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 rich usage context: how to place the output (same at/offset/duration as the source clip, set that clip's volume to 0) and the async workflow (start jobs, keep working, call wait_for_jobs for Asset IDs). It does not explicitly name alternatives or when NOT to use it, 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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false, idempotentHint=false) by disclosing async behavior (returns a Job ID immediately, media is generated in the background), the 5-second silence padding and 60-second ceiling for stills, the ping-pong looping for short dub footage, that the returned sound is already baked into the clip and must not be placed again, and detailed per-second credit costs. These are exactly the traits annotations cannot convey.

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

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

Front-loaded with the purpose and mode split, then workflow, then cost — a sensible ordering with no filler sentences. It is long and duplicates some schema content (the mode and assetId definitions are essentially repeated verbatim), which costs it a point on a tool whose schema is already fully documented.

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

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

With no output schema, the description still covers the return contract (immediate Job ID, later Asset ID via wait_for_jobs for patch_film) and even notes the answer reports where the words end so the silence-padded clip can be trimmed. Combined with cost, duration bounds and mode prerequisites, an agent has everything needed to call and chain it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds cross-parameter semantics the schema cannot express, such as still duration tracking the sound with 5s minimum/60s maximum, dub length being governed by the longer of footage and line, and guidance to pick footage about as long as the line. It does restate much of the mode/assetId schema text, keeping it from a 5.

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 concrete verb+resource ('make a person say a line, their mouth on the sound's words') and immediately splits it into two well-defined modes, still vs dub. It names the sibling tools it composes with (generate_speech, read_transcript, edit_video, patch_film, wait_for_jobs), so an agent can distinguish it from generate_video or replace_person 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 says when to use each mode (still = animate a picture; dub = keep real footage, change only the mouth, e.g. another language) and prescribes the end-to-end alternative path when using a cloned voice. It also adds a hard procedural rule ('tell the person the cost before you start it') and post-call workflow (start jobs, keep working, wait_for_jobs).

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 read-only, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds that the listing includes lineage and current-version information, which is useful, but it does not mention ordering, pagination, permissions, or other operational traits.

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

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

A single front-loaded sentence with no wasted words. It efficiently states the resource, the listed contents, and the current-version marker.

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 low-complexity, one-parameter read tool with rich annotations but no output schema, the description adequately explains what will be returned. Minor gaps remain around ordering and pagination, but the core context 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?

Schema description coverage is 100%, and the projectId parameter is already fully documented in the schema, including the null/default behavior. The description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

The description gives a specific verb (list) and resource (project versions/branches), and clarifies what is included: parent version lineage and current version. It does not distinguish this from sibling tools like list_projects or diff_branches, so it stops short of full sibling differentiation.

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

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

There is no guidance on when to use this tool versus alternatives such as diff_branches, switch_branch, or list_projects. No prerequisites, exclusions, or context for selecting this operation are provided.

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

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

Annotations already declare this as a safe, read-only, idempotent operation. The description adds useful behavioral context by explaining exactly what each listed file exposes: root, size, imports, reverse imports, and module components/constants.

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 definition is front-loaded with the core action and scope, then efficiently lists return contents and the follow-up read path. Every sentence contributes useful information without repetition.

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

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

For a simple read-only listing tool with strong annotations and full schema coverage, the description is complete: it describes the files covered, the returned fields, and how to inspect an individual file. No output schema exists, but the return shape is adequately explained.

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 projectId parameter is fully documented in the schema. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description gives a specific verb and resource: it lists the project's film files, explicitly naming main.film, the project film, and imported modules. It clearly distinguishes this browsing tool from sibling readers like read_film.

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

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

It explicitly routes the agent to read_film for reading an individual file with its path, giving clear next-step context. It does not spell out exclusions versus related listing tools, but the usage context is strong.

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, closed-world, so the safety profile is covered. The description adds genuine context beyond that: deterministic newest-first ordering, per-account scope, and the pagination contract (total/nextOffset, null = last page).

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

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

Three tightly packed sentences, front-loaded with the core action and scope, then pagination. Slightly dense mixing of return-shape and paging instructions, but 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?

Output schema exists, so return values are partly covered, yet the description still clarifies total/nextOffset pagination meaningfully. Annotations handle safety; remaining detail is largely complete for a simple list tool.

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

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

With 100% schema description coverage, baseline is 3, but the description adds cross-parameter linkage the schema lacks: passing nextOffset as offset for the following page, and query matching words of the name. This raises it above baseline.

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

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

States a specific verb and resource (list Vidova projects), scopes it to the signed-in account, and adds ordering (newest first). It stops short of explicitly distinguishing itself from siblings like get_active_project or open_project, even though it mentions returning 'the id of the open one'.

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?

Explains how to use query to find projects by name and how to page via offset, which implies the usage context. But it never names an alternative or states when a different tool (e.g. get_active_project, search) should be preferred.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description usefully adds ordering and cross-project scope, but does not mention page-size behavior, result volume, or any limits—modest added value only.

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

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

Two sentences, front-loaded with purpose then pagination mechanics, with no filler. Slightly compressed to the point that "next" is only resolvable via the output 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?

An output schema exists, so return shape need not be described. But for a two-parameter paginated list tool, the undefined `limit` and absent guidance on page size / how to detect the end of results leave real gaps.

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

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

Schema description coverage is 0%, so the description must carry the load: it does explain `before` as the cursor taken from the response's `next` field, with null meaning start at newest. However, `limit` is left completely undefined (default? max?), so only half the parameters get semantics.

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

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

States a specific verb and resource ("List this account's cloud exports") plus scope ("across all projects") and ordering ("newest first"). It is distinguishable from read_render/cancel_render by being the collection lister, 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?

Gives concrete guidance for pagination ("Use next as before to fetch the next page; null begins at the newest job"), but says nothing about when to choose this tool over read_render for a single job, nor about any preconditions. Usage is implied rather than framed against alternatives.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses the BS.1770 K-weighting standard, that stored levels are combined with volume keys/gains/fades/ducks, the windowing (400 ms momentary, 3 s LRA windows), that parts under 3 s have no LRA, that '-' means silence, and that it uses no credits. These are exactly the computational and cost facts an agent cannot infer from annotations or schema.

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

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

Dense and front-loaded — the core output definition comes first, then behavior, then the null-sentinel rule, then cost, then the sibling pointer. The nested parentheticals ('each value the 400 ms before its time', 'the sounds' levels summed where they are loudest, not a sample peak') make it a single heavy paragraph that could be split or trimmed slightly.

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?

There is no output schema, so the description carries the full burden of describing return values, and it does: per-lane and mix momentary LUFS at 0.5 s intervals, integrated LUFS, LRA in LU, and true peak in dBFS, plus the null/silence conventions. Nothing an agent needs to interpret the result correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: passing null for both startSeconds and durationSeconds reads the whole film (a joint-behavior detail not in either field description), plus the film-seconds unit and the '-' silence sentinel. Only a modest increment above baseline, hence 4.

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 ('Loudness of the composed timeline's sound over time, as numbers') and immediately enumerates the exact readouts produced. It distinguishes itself from the analysis/read siblings by naming read_render as the tool for a finished render's sound.

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 an explicit workflow ('measure, change the keys, measure again') that tells the agent this is a pre-render iteration tool, and names the concrete alternative for post-render measurement ('For the same readout of a finished render's sound, call read_render with loudness true'). When-to-use and when-to-use-something-else are both present.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false), and the description usefully adds the failure behavior ('conflicts fail') and the re-merge-after-edits trait. It omits permission/rate-limit context, but adds meaningful behavior beyond the structured fields.

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

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

Three tight sentences, front-loaded with the core action and constraint, and no redundant restatement of the name or schema. Every clause adds a distinct piece of information.

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

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

For a 4-param mutation tool with no output schema, it covers the merge mechanism, the precondition, the failure mode, and re-merge semantics. Missing only peripheral details like permission requirements or result 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 only 25% (only projectId documented), so the description carries the burden and does so: it defines the sourceBranch→targetBranch relationship and instructs the caller to set switchToTarget explicitly. It still doesn't clarify what switchToTarget actually does, leaving one param partially opaque.

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 (combine sourceBranch into targetBranch) plus the mechanism (three-way file merge). It clearly distinguishes itself from siblings like diff_branches, create_branch, and switch_branch, which share the branch vocabulary.

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 precondition that targetBranch must be the version sourceBranch was made from and points to list_branches to find it, plus notes re-merge is possible after edits. It doesn't explicitly route between merge_branch and diff_branches/create_branch, 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?

Goes well beyond the annotations: it discloses the conflict-resolution rule (better quality score wins per frame), the seam-blending behavior that prevents corner jumps, and that otherTrackId is removed. The one unresolved point is reversibility -- it does not say whether a merge can be undone, which matters given idempotentHint=false and the removal of a track (mild tension with destructiveHint=false).

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

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

The core action is front-loaded in the first clause and every sentence carries operational content. The prose is dense and long-sentenced, and the return-value details plus the preview recommendation could be ordered more crisply, but 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 no output schema, the description usefully summarizes the response (where the merged result still references the removed track, the new quality verdict and flagged ranges) and points at preview_range for visual confirmation. What it omits is failure modes and undo behavior for a non-idempotent mutation.

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 3 is the baseline, but the description earns more by explaining the purpose behind blendFrames ('a few frames are blended so the corners do not jump') and clarifying that trackId is the survivor the merged track is written under. It stops short of restating the 0-12 range, which the schema already covers.

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 ('Join two object tracks of the same asset into one, under trackId') with a concrete example use case (two tracks of one sign seeded at different times). It is unmistakably distinct from neighboring tools like split_track, edit_track and smooth_track.

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 precondition ('Both must be plane tracks or both box tracks') and a recommended verification step ('a preview_range call with overlays ["tracks"] ... run it to check'), plus the 'Free' cost signal. It does not, however, say when to prefer split/merge alternatives or what to do when the precondition fails.

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

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

Annotations only say readOnly=false, destructive=false, idempotent=false; the description adds the important semantics: null newLabel mutates the track in place while a label forks a new track and keeps the original. It also discloses the response contents (quality verdict, flagged ranges) and that the call is free.

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

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

Front-loaded with the verb and scope, then geometry, then the newLabel fork, then the verification step and cost. Every sentence contributes a distinct fact with no restatement of the name or title.

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

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

Ten required parameters and no output schema, yet the description explains the result payload and prescribes a check step, and covers the perspective/UV behavior that makes these parameters non-obvious. 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?

Schema coverage is 100%, so the schema carries the baseline; the description still adds meaning by explaining that scale and inset operate in surface UV and pass through the surface's perspective, so the far side moves less than the near side. That geometric nuance is not fully 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?

States a concrete verb set (move, scale, inset) applied to a specific resource (an object track's corners on every frame). The inset/outer-frame-to-inner-panel example makes the effect unambiguous and separates it from siblings like edit_track or smooth_track.

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 when-to-use scenario and a recommended verification step (preview_range with overlays ["tracks"]), which is real usage guidance. It never names an alternative tool or an exclusion, so an agent must infer when edit_track or smooth_track is the better choice.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, readOnlyHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing the stateful side effect ('the editing tools then act on it') and visible UI behavior ('an open Vidova app shows it on screen'), but it omits what happens on an invalid id or whether it replaces the currently active 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?

Three short sentences with the purpose front-loaded, followed by dependency and observable side effect. No filler, though the phrasing 'An open Vidova app shows it on screen' is slightly awkward and could be tightened.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. The description covers purpose, dependency on list_projects, and the observable effect; only error handling and interaction with an already-open project are unstated, which is a minor gap.

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

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

Schema description coverage is 0%, so the description carries the burden for the single projectId parameter. It usefully tells the agent where the id comes from ('from list_projects'), but says nothing about the expected format (UUID, slug, numeric) or failure behavior for an unknown id, leaving part of the gap unfilled.

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 ('Open a project by its id'), which cleanly separates it from create_project, list_projects and delete_project. It does not, however, distinguish itself from get_active_project or explain how 'open' differs from merely reading a project, so it stops short of full sibling differentiation.

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

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

'The editing tools then act on it' implies the usage context: open this before performing edits. There is no explicit when-not guidance and no mention of the sibling get_active_project as an alternative for inspecting the current project, so the routing is only implied.

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

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

Goes well beyond the annotations: build and type-check failures reject the write before committing, the previous source and revision remain intact, the whole project is compiled and the write is rejected if an importing component breaks. It also discloses hard refusals (animate/animateIn/animateOut generators) and constraints (atTime is the only animation API, no shadowing Node methods, media signals use VideoSrc/AssetSrc).

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

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

The purpose is front-loaded in sentence one, but the body is a dense wall mixing skill-reading policy, import/package rules, API contracts and naming conventions — much of which reads like documentation rather than tool selection guidance. Several clauses duplicate the schema verbatim and could be trimmed without loss.

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

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

For a destructive-ish mutation with no output schema, the description covers everything an agent needs: atomicity, failure/rejection behavior, revision retention, name variants, and the constraint set for generated source. No material gap remains.

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

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

With 75% schema coverage the schema already documents find, replace, all, branchId and projectId in near-identical wording; the description largely restates these ("Empty replace deletes a span", "branchId null means the current version"). Its genuinely additive points — atomic single compile and the shared/<name> naming variant — are useful but modest against a schema doing the heavy lifting.

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

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

Opens with a precise verb+resource: "Apply exact source replacements to an existing component in one compile." It also names the sibling alternatives it is not (import_element for an unchanged library element, scaffold_component for a skeleton), so an agent can route without opening a schema.

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

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

Explicit alternatives and selection rules: import_element vs scaffold_component vs patch_component, plus the shared/<name> variant that writes a plain TypeScript module instead of a component. It also gives error-handling policy ("Fix errors; do not chase warnings unrelated to visible defects") and preconditions (which skills to read before which 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?

Goes well beyond the annotations: it discloses atomicity ('A write that still does not compile writes nothing'), auto-repair behavior with named repairs in the report, the asset-wait and refusal path, and the compile-everything coupling between modules and main.film. These are the failure modes an agent most needs, and none are contradictions of readOnlyHint=false / idempotentHint=false.

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

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

The core operation is front-loaded, but the body becomes a dense run-on covering modules, repair policy, asset waiting, and a long enumerated skills list that reads like reference material rather than rationale for calling this tool. Length is partially justified by tool complexity, yet the skills enumeration and module tutorial crowd out the essential 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 non-idempotent, all-or-nothing XML patch tool with no output schema, the description covers prerequisites (skills to read, asset placeability), failure behavior (refusal reasons and where to look), and version targeting. An agent has everything needed to call it correctly on the first try.

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 80%, so the schema already documents path, branchId, and waitForAssets; the description nonetheless clarifies intent (path null vs module file, branch write without switching the editor) and ties waitForAssets to a concrete scenario an agent will hit. It adds some value but mostly restates the schema's own field descriptions.

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+mechanism: 'Apply one or more exact replacements to main.film, or with path to a module, in one compile.' An agent immediately knows this is a find/replace patch tool over film XML. It does not explicitly differentiate itself from siblings like replace_film, fix_film, or patch_component, which keeps it short of a 5.

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

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

Gives concrete conditions: path null writes main.film vs a module file name writing that module; branchId null means current version while a listed version id writes without switching; and explicitly exempts value-only patches from the skill-reading requirement. It never names an alternative tool (replace_film, fix_film) or says when not to use it, so it falls short of the 5 bar.

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 explains whole-word/consecutive matching, that replace inherits the time span of the replaced words, that every caption and search updates as a side effect, that the transcript is asset-scoped (hence no branchId), and that the operation is atomic ('All edits apply or none do'). These are non-obvious mutation semantics that the readOnlyHint/destructiveHint flags 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-loads the purpose in the first sentence and packs dense, useful detail into six short sentences. Every sentence carries weight; a slight tightening is possible, but nothing is redundant 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 no output schema and no annotation support for mutation semantics, the description covers the essentials an agent needs: atomicity, side effects on captions/searches, asset-vs-version scoping, and the read-before-edit prerequisite. Nothing material is missing for a correct call.

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

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

Schema coverage is only 33%, so the description must compensate, and it does: it defines what `find` and `replace` mean semantically, that replacement takes over the time span, and it explains why `branchId` is absent. It does not restate the nearSeconds disambiguation rule, but the added meaning on the edit objects is substantial.

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 ('Correct words in a completed transcript') and immediately distinguishes itself from siblings by noting it 'Does not transcribe again' (vs transcribe_asset) and by pointing to read_transcript. An agent can separate this from read/patch component or film tools 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 a clear precondition workflow: 'Read the words with read_transcript first,' and rules out re-transcription. It stops short of explicitly naming transcribe_asset as the alternative for creating rather than correcting a transcript, so it is clear context without formal when/when-not routing.

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

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

The annotations already declare read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond them. It explains the internal process (reads every frame and sound, a model picks the first frame, sound starting there sets the frame), the return information (source second to millisecond, frame, frame rate, what the frame shows, numbered sheet), and the credit cost.

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 and information-dense, covering purpose, alternatives, use case, process, output, and cost without filler. It is slightly repetitive in the imperative 'Pin every cut, slow-down and sound...' and the three-example list, which keeps it from being maximally concise.

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

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

For a complex read operation with no output schema, the description supplies the process, output fields, cost, prerequisite of a ready video, and alternatives. Parameter details are left to a high-coverage schema, so an agent has enough context to invoke it correctly.

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

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

Schema description coverage is high at 86%, so the schema already documents most parameters. The description adds rough-time context for 'around' and the idea that 'what' is the moment as it looks, but it does not add meaning for window, clipId, atSpace, or projectId beyond the schema; baseline 3 applies.

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

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

The opening sentence gives a specific verb and resource: 'Find the exact frame of a moment in a ready video near a time you know roughly.' It explicitly distinguishes this tool from transcripts, search_video_moments, and contact sheets by explaining that those only locate a moment to about half a second, while this finds the exact frame.

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

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

It names the alternatives (transcripts, search_video_moments, contact sheets) and states the condition that selects this tool: when a cut, slow-down, or sound must land on an action. It also implies when not to use it—when half-second placement is sufficient—so the routing guidance is 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?

Adds substantial behavior beyond the annotations: credits are consumed 'as those tools do', an in-flight run 'is joined, not started or charged again', a long cutout returns a Job ID that must be awaited, and photo/footage requirements are surfaced rather than guessed. These are exactly the cost, idempotency and follow-up facts an agent needs before invoking a non-readOnly 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?

Front-loaded with the action and its dependency, then flows into sourcing, cost and follow-up semantics in roughly priority order. It is dense and semicolon-heavy, but no sentence is filler and every clause carries distinct information.

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

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

With no output schema, the description still covers the return contract ('a long cutout answers with a Job ID'), the async follow-up (wait_for_jobs), and result verification (preview_frame). Nothing an agent needs to call this correctly appears to be missing.

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

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

Schema description coverage is 100%, so both clipId and projectId are already documented in the schema (including which project is used when null). The description only restates that clipId is the effect's clip id and never mentions projectId, adding negligible meaning over the structured data. Baseline 3 applies.

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

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

Names a specific verb ('make ... and link it in') and a concrete resource: the person mask or face an effect already in the film is waiting on. It is clearly distinguished from the lower-level siblings it may invoke (cutout_subject, track_faces) by being the orchestrator that resolves the effect's dependency.

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 an explicit trigger ('read_film lists the effects that wait for something under Effects waiting'), the default path (link a pre-existing mask/face when it covers the effect's seconds) and the fallback (otherwise run cutout_subject or track_faces there). It even states the next step for long jobs (wait_for_jobs) and verification (preview_frame).

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