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?

Annotations only declare safety/idempotency hints, and the description goes far beyond them: credit cost (~6.1 credits/min, billed by the second, kept even on failure or deletion), no indexing required, sync-vs-async behavior with the read_video_intelligence handoff and waitSeconds 25, refusal handling (refused requests not stored, resendable corrected), and the untrusted-media caveat. This is unusually rich 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?

Purpose and the key routing decision are front-loaded in the first sentences, and most sentences carry unique operational detail (cost, async fallback, refusal recovery). It is long and repeats a little of what the schema already says for requestId/mediaId, which keeps it short of 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?

For a high-complexity tool with an output schema and 5 required parameters, the description covers what an agent needs to call it correctly: range constraints, cost, sync/async behavior, the follow-up tool, and refusal recovery. 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 80%, so much is already documented, but the description adds real constraints not present in the schema: startSeconds/endSeconds must be 1 second to 1 hour apart, must not pass durationSeconds, and an end under half a second past the duration means the end of the video. The requestId guidance and output-time semantics also echo/reinforce schema and output fields.

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 (ask/summarize) and a precise resource (a range of a Library video), and explicitly distinguishes itself from neighbors: search_video_moments for locating footage first and read_video_intelligence for waiting on a job. An agent can route to it 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?

Gives explicit when-to-use, when-not-to-use, and alternatives: 'only when the user's request needs it', 'For questions that need footage located first, call search_video_moments', 'Skip the search when the user already selected a range', and 'Never run analysis for every upload or every search result.' The routing conditions are fully 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 only mark this as a non-readonly, non-idempotent mutation; the description goes far beyond by disclosing that it writes on a new track, reuses masks/face tracks or runs cutout_person/track_faces (consuming credits), writes the current version, and rolls the effect back with an explanatory answer if the mask can't be made. It also explains the Job ID path for long cutouts.

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 most sentences carry weight for a complex 7-parameter tool, but the prose is dense and slightly rambling in places, with a minor typo ('at is the timeline second'). It is adequately sized rather than tight.

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 mutation with 7 required params and no output schema, the description is complete: it covers side effects, credit costs, mask/face prerequisites, error rollback, and the async Job ID plus preview_frame verification path. 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 baseline is 3, but the description adds concrete value with worked examples ('{"emoji": "😭"}', '{"face": "track_face_2"}', photos by Asset ID like '{"top": "img_a"}') and restates the key null-semantics for duration, region and clipId in prose. It adds useful grounding beyond the schema field docs.

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 ('Put one effect from search_effects into the film') and clearly routes from discovery (search_effects) to application. An agent can distinguish it from siblings like prepare_effect or apply_template 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 real usage guidance ('Use one effect per moment, on a real beat or impact: an effect on every cut reads as noise') and names follow-ups (wait_for_jobs for long cutouts, preview_frame to check). It doesn't explicitly differentiate from the closely related prepare_effect sibling, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds real value on top: it says main.film is replaced, that components are added to the project, and that a rule-breaking slot aborts with the slot named. It stops short of saying whether a failed call partially applies or what the success return looks like.

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

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

Purpose is front-loaded in the first sentence and the remaining sentences cover validation, side effects, failure recovery, and follow-up steps without padding. The branchId restatement slightly duplicates the schema, a minor redundancy in an otherwise tight definition.

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, four-parameter tool with no output schema, the description covers side effects, error semantics, and the verification workflow. It omits what a successful call returns and whether long-running jobs are involved, which would fully close the loop.

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 beyond it: slots must be JSON text matching read_template's shape and carrying this project's Asset IDs. The 'branchId null means the current version' sentence largely duplicates the schema, but the Asset-ID constraint is genuinely new information.

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

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

States a specific verb and resource with scope: 'Build the whole film from a template', and the body clarifies the mechanics (validates slots, adds components, replaces main.film). This distinguishes it cleanly from siblings like replace_film, patch_film, and scaffold_component without needing 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 an explicit workflow: read_template supplies the slot shape, preview_frame verifies the result, patch_film adjusts it, and the failure mode tells the agent to fix the offending slot and re-call. It never explicitly excludes alternatives (e.g. replace_film) or states preconditions, so it falls just 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?

Beyond the annotations (which only declare the read/write/idempotency profile), the description discloses the two-phase workflow, that bytes must not be passed through arguments, retry-forbidden failure modes (proxy 403, connect_rejected, DNS failure), and what the call returns (Asset ID and upload commands). This is rich behavioral context the structured fields do not carry.

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

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

Front-loaded with the action and accepted inputs, then workflow, then failure handling, then the alternative tool. Dense but every sentence earns its place; the parenthetical file-extension lists are long but load-bearing for input selection.

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, and the description compensates by naming the return values (Asset ID plus commands) and the follow-up step. For a 7-parameter, multi-step upload tool it is substantially complete, though it does not explain why video-range parameters are required alongside a generic file upload.

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 57% schema coverage, the description must partly compensate, and it does by tying inputs to file classes ('Supply filename, MIME type and byte size') and stating the type-specific size ceilings (2 MB data, 10 MB font). It does not add meaning for the video-range params, but the schema already describes startSeconds/endSeconds/keepOriginal/projectId.

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 ('Begin uploading a local media file, a data file, or a font file') and enumerates the accepted file classes with size limits. It explicitly names its downstream sibling complete_asset_upload and the alternative upload_files, so an agent can tell it apart 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 explicit sequencing ('run them... in order, then call complete_asset_upload') and a clear alternative rule ('If you have the upload_files tool, call it instead'), plus when-not guidance for failed connections ('do not retry it'). Nothing about selection 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 beyond the annotations by disclosing a real side effect (reserved credits are returned) and the post-condition that completed exports are unaffected. Idempotency is restated in prose, which reinforces rather than contradicts idempotentHint=true. It still omits what happens if the job is not owned or already finished.

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, each carrying distinct information: the action, the credit consequence, the effect on completed exports, and the idempotency guarantee. The core action is front-loaded and 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 an output schema present, return values need no explanation, and the description covers preconditions, side effects, and idempotency for a single-parameter tool. The remaining gap is not telling the agent how to obtain a valid jobId or what error surfaces for a non-owned job.

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 jobId, and it says nothing about it beyond the implied context of a render/export job. The parameter is largely self-explanatory by name and uuid format, but the description never says where the identifier comes from (e.g. render_video or list_renders).

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 (cancel) and a specific resource (an owned pending or running cloud export), and scopes it to the states where cancellation is meaningful. This clearly separates it from render_video (create), list_renders/read_render (inspect), and wait_for_jobs (observe) among 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?

Clearly states the conditions under which cancellation is valid (pending or running, owned) and implicitly signals when not to bother (completed exports remain available). It does not name a sibling tool the agent should reach for in a related situation, so it stops short of full alternative routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial extra context: the analysis method (frame sampling + sound levels), the finding structure ('what it saw, when, and what to do'), the Fix vs 'Worth a look' split, and the caveat that partial runs list the areas they left out.

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 completion-gate rule, and every clause carries information. It is, however, a dense run-on paragraph — the ~17-item enumeration of detected faults is long and unbulleted, which costs some scannability.

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

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

With no output schema, the description carries the return-value burden and does so: it explains that findings name what was seen, when, and the suggested action, and that they are split into Fix and 'Worth a look'. Combined with the scoping rules, an agent has everything needed to call and act on this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by mapping parameters to workflow: null areas = check everything before declaring done, named areas = re-check only what changed, and startSeconds/durationSeconds = 'running again on what you changed'. It stops short of adding format/syntax detail beyond that.

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 ('Quality check of the edit') and immediately frames its role as the pre-completion gate ('to run before you say it is done'). It also describes the actual mechanism ('draws frames across the film and reads its sound levels'), distinguishing it from siblings like fix_film, patch_film and 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?

Explicit when-to-use ('Run it on the whole film, every area, before you say an edit is done'), when-not ('a run on some areas says nothing about the others'), and the narrowing case ('name areas only to re-check what you changed'). It also routes the agent to preview_frame/preview_range for inspecting named moments.

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 idempotency and safety, but the description adds genuine behavioral context beyond them: an asset may still be processing after completion and the result reports that state, which is not captured by any structured field.

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

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

Three tight sentences with the trigger condition front-loaded, then the input source, then the fallback path. 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 carries return-value burden and does so by explaining that the result may report in-progress processing. Combined with the workflow routing, 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 only 50%, but the description compensates by explaining where assetId comes from (begin_asset_upload), and projectId is documented in the schema itself including the null/open-project behavior.

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 explicitly scopes it to after the upload commands succeed, distinguishing it from begin_asset_upload and wait_for_asset by name.

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 prerequisites (upload commands must have succeeded), names the required input provenance (Asset ID from begin_asset_upload), and routes to the alternative (wait_for_asset) with the exact condition that selects it.

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

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

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 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 well beyond the annotations (which only say it is a non-destructive, non-idempotent write) by disclosing cost (~5.7 credits per minute, billed per second), that only the passed range is processed, and that the mask is black before startTime and stops at endTime. The null-for-both behavior for video and images is spelled out.

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 what it does and what it returns, then packs the range/cost rules compactly. There is mild redundancy in the trailing "null for both cuts out the whole video. An image takes null for both," which repeats the schema's null notes.

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 names the returned Asset ID and its mask semantics, plus cost and range behavior. It omits whether the call is asynchronous and needs wait_for_jobs, which matters for a job-producing tool in this family.

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 75%, and the description compensates by explaining the intent of startTime/endTime (the source range your shots use so mask= aligns with footage source time) and the null convention for whole-video and for images. It adds meaning rather than restating types.

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

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

States a concrete verb and resource ("Cut a person out of a ready image or video") and names the return artifact (luminance mask Asset ID). It implicitly separates itself from siblings like remove_background and replace_person by declaring its output and its patch_film binding, but never names an alternative 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 real usage context: bind the result with mask= in patch_film, and for video pass the source range your shots use. However it never says when to pick this over remove_background, replace_person, or track_faces, so the choice among mask-producing siblings 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?

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=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?

Annotations only declare the read/write/idempotency profile; the description adds far more: it stores/replaces the beat grid, sound >=8s costs no credits while other ranges bill ~1.1 credits/minute by the second, and range beats replace the grid's beats in that range. It also documents an unusual binding contract ('bind with beats= in film props') not visible in 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?

Well front-loaded (purpose, returns, then when-to-use and cost) and every clause carries semantic payload, but the mid-section is a run-on with an awkward construction ('A sound file of 8 seconds or more was measured when it arrived: its answer also has...'). Dense phrasing costs readability rather than wasting words.

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

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

With no output schema, the description fully compensates by enumerating return payloads (beats, downbeats, sections, hits, fills, big hits, drops, per-second loudness) and covering cost, replacement semantics, null handling, and the film-prop binding. 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 75% and the description adds real meaning on top: startTime/endTime define the read range, drive billing, replace that slice of the grid, and 'null for both reads the whole file,' plus 'times stay seconds into the asset.' It adds little about assetId beyond the schema, keeping it off 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 ('Detect beats and bars in ready music or video; stores the grid') and enumerates the outputs (beat times, downbeats, sections, drum hits, fills). An agent can distinguish this from detect_scenes/analyze_video without opening either 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?

"Do this before cutting to music" gives a clear trigger, and the description spells out the conditional branch (sound >=8s vs. video/shorter sound requiring startTime/endTime). It never names an alternative sibling tool or when *not* to call this, so it falls short of a 5.

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

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

Annotations 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 readOnly, idempotent, and non-destructive, so safety is covered. The description adds genuine behavioral context the annotations do not: the per-file line-diff format, the sign convention, and that each header names its version — important since there is no output schema.

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

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

Three tight sentences, front-loaded with the core comparison semantics, then the argument convention, then the id source. No filler and every clause carries information.

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

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

With no output schema, the description usefully describes the return shape (line diff per file, headers naming versions). Combined with annotations and the schema-documented projectId, an agent has what it needs; only an explicit alternative-tool contrast 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 only 33% (sourceBranch and targetBranch are bare), so the description must carry weight and does: the '-'/'+' sign convention plus 'pass the version it was made from as sourceBranch' defines exactly what each branch argument means. projectId is already documented in the schema.

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

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

States a specific verb+resource ('Show what changes from sourceBranch to targetBranch') and immediately pins down the output convention. It is clearly distinguishable from merge_branch, switch_branch, and list_branches, which are the 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 a concrete usage condition ('To see what a version changed, pass the version it was made from as sourceBranch') and routes the agent to list_branches for ids. It lacks an explicit when-not-to-use contrast with merge_branch/switch_branch, but the directionality guidance 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 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?

Annotations declare non-readOnly, openWorld, non-idempotent, non-destructive, but the description adds the operationally critical facts: it returns a Job ID immediately and renders in the background, requires wait_for_jobs plus patch_film afterwards, and costs ~38 credits/sec (~48 with references). The output-length and playback-placement behaviour (at/offset/duration, offset 0 for a part, in-group placement) is disclosed as well.

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 the edit taxonomy are front-loaded before routing, cost and timing details. It is dense and some sentences chain many clauses (the playback-placement sentence), but almost every sentence carries decision-relevant information rather than filler.

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

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

For a complex, expensive async generation tool with no output schema, the description covers the return shape (Job ID, then Asset ID via wait_for_jobs), follow-up tooling, cost, duration limits and placement semantics. Nothing an agent needs before calling it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: prompt phrasing conventions, how references map to @Video1/@Image1-4, and how the resulting clip must be placed back into the timeline. Some material (3-10s limit, 720px, reference string forms) is duplicated from the schema, so it does not fully escape the 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 concrete verb+resource (change what a video shows from a written instruction) and enumerates exactly what can be changed: colour, clothes, objects, background, weather, time of day, season, whole look. It distinguishes itself from siblings by naming replace_person and copy_motion as the tools to use for other kinds of edits.

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 load builtin-generative-video first for prompt rules and for when to use replace_person or copy_motion instead. It also gives the selection logic between whole-asset, startSeconds/endSeconds part, and group editing, and specifies 3-10 second bounds, so the agent knows exactly when this tool applies.

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

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

Annotations cover the safety profile (destructiveHint=false, openWorldHint=false), lowering the burden. The description usefully adds the return shape ('numbered detections and an image') and default values, but doesn't disclose permissions, cost, or why readOnlyHint is false for what looks like a read/detect operation.

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, front-loaded sentences with no waste; the primary action comes first, followed by output then defaults. Tight and readable.

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 6-parameter tool with no output schema and low schema coverage, the description covers the return value and a prerequisite, but leaves most parameters unexplained. Adequate but with clear gaps for an agent 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 coverage is only 17% (just projectId), so the description must compensate for 6 required params. It mentions threshold 0.15 and maxResults 8 only as defaults, and says nothing about assetId, queries, or the 'at' frame semantics, leaving most parameters undocumented.

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

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

The description gives a specific verb and resource: 'Find named objects on a source frame', which is clearly distinct from pure tracking siblings like track_box or track_detection. It also states the output (numbered detections + image), but doesn't explicitly name which sibling it competes with.

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

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

'Load builtin-object-tracking first' provides a prerequisite/workflow hint, which is genuine usage guidance. However, it never says when to prefer find_objects over track_detection, track_box, or detect_scenes, so alternatives are 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: 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?

With annotations only covering readOnly/openWorld/idempotent/destructive flags, the description adds substantial behavioral context: the call returns a Job ID immediately while media is produced asynchronously, credit costs vary by size (26/38/57 at 1K/2K/4K), and cost is independent of references. This is exactly the kind of async, cost, and follow-up behavior an agent needs and 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, then references usage, then async workflow, then cost. Every sentence carries information, though the references and cost sentences are dense and the description runs long for a single tool; nothing is wasted but it is not maximally tight.

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, yet the description explains the return (Job ID), how to resolve it (wait_for_jobs -> Asset ID), and the downstream consumer (patch_film). Combined with cost and reference semantics, an agent has everything needed to invoke and follow through 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 60%; the description adds meaning to imageSize by tying each enum value to a credit cost and flagging 1K as standard, and reinforces that references take up to 3 ordered pictures. The prompt and projectId semantics are carried by the schema, and aspectRatio values get no added explanation beyond the enum, so it is not a full 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 an image from a prompt') and immediately scopes the resource further by explaining the references input. It is trivially distinguishable from siblings like generate_video, generate_music, or generate_speech, and the reference types (image assets, frames, contact sheets) make the tool's domain concrete.

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 usage context for references ('keep a person's face', 'copy the style', 'sum up a range') and a full workflow: start generations, keep working, then call wait_for_jobs with the Job IDs to get Asset IDs for patch_film. It does not state when not to use this tool versus alternatives (e.g. generate_video), so it stops short of a 5.

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

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

Annotations declare openWorldHint=true and idempotentHint=false, which already signal a non-repeatable, external-effect generation call. The description substantially extends this: it returns a Job ID immediately with the media made in the background, it costs ~0.95 credits/second (60s = 57 credits), and a credit refusal reports the remaining balance and should trigger a shorter-duration retry. That is real value beyond the annotations. It does not address failure modes beyond credits or whether concurrent generations are capped.

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 content, but the description is a dense run-on that interleaves prompt advice, async job mechanics, the downstream beat/hit metadata, credit pricing, and error handling. It is information-rich rather than padded, though a few clauses about the returned analysis data could be tightened or deferred to wait_for_jobs.

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 tells the agent what comes back (Job ID now, media later, and the Asset ID plus beat/hit/tempo/section metadata via wait_for_jobs), how it plugs into patch_film, and what happens on credit exhaustion. An agent has everything needed to invoke and follow up 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 60%, and the description compensates where it matters: forceInstrumental 'true excludes singing' and hero is explained as the offset that slides the strongest drop or big hit onto a given second. prompt guidance (describe shape rather than exact hit seconds) adds meaning the schema's bare 'up to 2000 characters' does not. durationSeconds and projectId are already well covered by the schema.

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

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

States a specific verb+resource ('Generate music from a prompt') and immediately bounds it by duration and instrumental mode. It names the sibling it is not ('Use generate_sfx for sound effects'), so an agent can route between the two audio generators 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 when-to-use routing ('Use generate_sfx for sound effects'), plus the prompt-shaping rule (describe the shape, give hero rather than asking for hits at specific seconds) and the full async workflow (start every generation, keep working, then wait_for_jobs). It also states the credit-failure retry policy. 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?

Annotations declare readOnly=false, idempotent=false, openWorld=true, destructive=false; the description goes well past that by disclosing the asynchronous job pattern (returns a Job ID at once, media rendered in the background), the credit cost (about 0.76 credits/second), and that each Asset ID carries measured loudest-point placement and volume. This is exactly the extra behavioral context annotations cannot express, and nothing contradicts destructiveHint=false.

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

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

Front-loaded with purpose and concrete sound examples, and the paragraph flows logically into workflow then cost. It is dense but largely earns its length; however, the duration bands and the white-noise word list restate what the schema already carries, which is avoidable redundancy.

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 carries the return-value burden and does so: Job ID immediately, Asset ID later via wait_for_jobs, plus placement and volume metadata and the patch_film handoff. Cost and credit math are also given, leaving no material gap for an agent to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents prompt, loop, projectId and durationSeconds – and much of the description's prompt/duration guidance is duplicative of those field descriptions. The description adds only the marginal constraint that each call produces exactly one sound, so the baseline 3 for schema-driven params 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?

"Generate a sound effect from a description" is a specific verb+resource, immediately distinguishing it from siblings like generate_music, generate_speech and generate_video. The enumeration of target sounds (impact, boom, whoosh, riser, ambience) further pins down the exact output domain, and the async-return model is stated upfront.

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 guidance via loop semantics (true for ambience/bed, false for hit/whoosh/riser) and duration bands per sound type. It also prescribes the workflow: start every generation you need, keep working, then call wait_for_jobs with all Job IDs to obtain each Asset ID for patch_film. That names the sibling handoff explicitly.

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 safety/idempotency flags, but the description adds the async job model (answers at once with a Job ID, media made in background), credit cost (1,000 characters = 7 credits), and the silent-drop behavior for unrecognized tags. These are behavioral traits the annotations do not 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?

Dense but front-loaded: purpose, then workflow, then prerequisites, then cost. Every clause carries operational information, though the run-on single paragraph could be split for easier scanning.

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-required-param generator with no output schema, the description covers the full lifecycle: prerequisite skill, return value (Job ID), follow-up (wait_for_jobs), and handoff (patch_film). Nothing needed to invoke 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 80% (baseline 3), and the description still adds value: it clarifies text is read word-for-word in any written language, gives the default-style voice (Kore), and explains that style governs delivery in plain words while speakers converts "Name: line" text into per-speaker audio. It largely reinforces rather than extends the already-detailed schema 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 concrete verb+resource ("Generate a voiceover") and immediately scopes it (single voice vs. multi-speaker dialogue). It is clearly distinguishable from siblings like generate_music, generate_sfx, and transcribe_asset.

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 prerequisites ("Load builtin-voiceover first"), the async workflow ("start every generation you need... then call wait_for_jobs with all their Job IDs"), the downstream step ("patch_film"), and an alternative (transcribe_asset for word times). It also gives an anti-pattern: put one voiceover or whole dialogue in one call rather than splitting.

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 mark it as a non-idempotent, open-world write; the description adds the operationally critical behaviors: it is asynchronous (returns a Job ID, media produced in background), credits are consumed per second at quality/resolution-dependent rates, impossible quality/silence combinations are silently upgraded and charged at the higher tier, and silent video is irreversible. That is far beyond what annotations 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 three modes and dense with useful rules, but the credit costs are restated three times (per-second rates, then worked examples), and the quality guidance duplicates the schema's own quality description. Slightly long, though nearly every sentence earns its place.

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

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

For a 9-parameter async generation tool with no output schema, the description supplies the missing return handoff (Job ID, then wait_for_jobs -> Asset ID for patch_film), cost estimation duties, failure handling, and mode selection. An agent has everything needed to invoke and follow up 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 67% schema coverage, the description meaningfully compensates: it explains quality tier semantics and auto-upgrade behavior, generateAudio's null/true/false meaning plus the irreversibility caveat, the references string formats and ordering rules, and the standard defaults for duration, aspect ratio, resolution and audio. Resolution, duration and aspectRatio are left to their schema enums/bounds, which is adequate.

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

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

The first sentence states a specific verb and resource and enumerates the three distinct generation modes (from prompt, animate an image via referenceAssetId, and compose from up to 5 references). It clearly distinguishes itself from siblings like generate_image and generate_music by naming the medium and its inputs.

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

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

Gives explicit when-to-use rules: the load builtin-generative-video prerequisite, quality selection guidance (standard for B-roll, high for hero shots, highest only on request), when to use references vs referenceAssetId, and when generateAudio may be false. It also prescribes the downstream workflow (wait_for_jobs then patch_film) and the retry policy after a credit refusal.

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 already declare non-readonly, non-idempotent, non-destructive, open-world. The description adds substantive behavior the annotations don't: it returns an Asset ID, may return a processing state, and imposes concrete size limits (2 MB data files, 10 MB fonts). It stops short of warning that repeat imports create new assets rather than overwriting.

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 and return value are front-loaded and efficient. The third sentence, covering data files and fonts with an example CDN URL, is dense and reads as a run-on, mixing two distinct asset types into one sprawl.

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 carries the return-value burden and does so (Asset ID, font family name, processing state). The async follow-up is covered; the only gap is silence on how the required video range bounds affect the imported result.

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% and the schema itself documents projectId, startSeconds, and endSeconds well. The description adds meaning for fileName ('including extension') and url (direct HTTPS), but says nothing about the range-trimming parameters, so it neither compensates nor regresses. Baseline 3 for medium coverage.

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

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

States a specific verb and resource ('Import media from a direct HTTPS URL'), and the 'direct HTTPS URL' qualifier implicitly separates it from local-file tools like upload_files and begin_asset_upload. It does not name a sibling explicitly, so it sits just below the top tier for 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?

Gives conditional guidance for the async path ('If the result says it is still processing, call wait_for_asset with the Asset ID'), which is real when-to-use guidance. It never states when NOT to use this tool versus search_stock, import_stock, or upload_files, so routing for source-type alternatives 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?

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 already declare the non-mutating safety profile, but the description adds real context beyond them: cost behavior ('Nothing is charged'), the side effects of installation (DeviceFrame/DeviceFrameVideo components placed in the project), and the shape of the response for each branch. It does not address idempotency (annotations say idempotentHint=false), which a repeated-import agent would want.

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 required id in the first two sentences, then branches into the two item types. The prose is dense and the template-slot clause is a little run-on, but nearly every sentence carries information an agent needs to call the tool correctly.

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

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

With no output schema, the description does the work of explaining return values (filled-in clip, materials list, 3D clip) and the follow-up routing, which is substantial for a two-branch import tool. It is a bit tangled in the device-frame branch and leaves projectId behavior entirely to the schema, but nothing critical for a correct invocation is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, including the id pattern and the projectId null/default semantics. The description repeats the source-of-id guidance and adds one extra example (the laptop-showcase template taking macbook-pro) but introduces no new syntax or constraints 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?

States a specific verb+resource ('Import one item from search_stock into the project as an asset') and pins the source tool. It also distinguishes the two item classes handled (device frame vs 3D model), so an agent can tell it apart from siblings like import_asset_url, import_gif, and add_from_library.

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?

Clear context: the id must come from search_stock ('Pass its id', 'Do not invent ids'), and it routes the agent onward to patch_film or the template slot after import. However, it never states when to prefer this over sibling importers like add_from_library or import_asset_url, so the exclusions are missing.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds substantial non-obvious behavior: ~22 credits per minute billed by the second, credits retained even if the job later fails or is deleted, no effect on editing, and returns a job to wait on via read_video_intelligence. It also notes free re-indexing when the range is already covered densely.

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 almost every sentence carries useful information, with no filler. However, it is one long paragraph covering many distinct concerns (cost, billing, segment sizing, job lifecycle), so bullet points or clearer structure would improve scannability.

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

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

Covers purpose, usage, cost, billing nuance, job lifecycle, and integration with read_video_intelligence. The output schema means return shape need not be explained, and annotations already cover safety and open-world behavior. For a paid, job-returning indexing tool with three required parameters, the description is complete enough to invoke correctly.

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

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

Schema coverage is 100%, so the schema already documents the three parameters. The description adds semantics beyond schema: mediaId can come from search_assets or search_library, null startSeconds/endSeconds index the whole video, segment length scales with indexed length (2s up to a minute, 6s at three minutes and longer), and a range should be taken from a search moment's start/end plus a few seconds on each side.

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?

Starts with a specific verb and resource: 'Index a Library video'. It states the downstream consumer (search_video_moments) and distinguishes the two core modes: initial indexing and re-indexing a range with shorter segments. An agent can differentiate this from read_video_intelligence or search_video_moments 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?

Provides explicit when-to-use conditions: index only older, disabled, or failed videos because paid accounts auto-index new uploads unless disabled. Also says when to index a range (a search moment too coarse for the question) and the minimum range size (4 seconds). Also explains when a submission is free because existing coverage is dense enough.

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?

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 readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful scope by specifying the signed-in account's projects and that the open project id is included, but it does not add deeper behavioral details beyond 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?

The description is a single, front-loaded sentence with no wasted words. It immediately states the action and the account scope.

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

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

Given the simple zero-parameter nature, rich annotations, and an output schema, the description is nearly complete. It covers account scope and the open project id, so an agent can call it correctly. A stronger definition might explicitly route between this and get_active_project.

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

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

The tool has zero parameters, so there are no parameter semantics for the description to clarify. The schema is empty and the description appropriately does not discuss parameter handling.

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 clear verb and resource: listing the signed-in account's Vidova projects. It also indicates the return includes the open project id, which helps distinguish it from a bare project list. However, it does not explicitly differentiate itself from the sibling get_active_project tool.

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

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

No guidance is given about when to use this tool versus alternatives such as get_active_project or create_project. The context is implied by the name and simple list intent, but there are no explicit when-to-use or when-not-to-use conditions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds useful behavior beyond them: global scope across all projects, newest-first ordering, and cursor-based pagination with null meaning 'start at newest'. No rate limits or pagination end conditions are described, but the added context is real.

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

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

Two tight sentences, with the scope/ordering constraint front-loaded before the pagination mechanics. The phrase 'use next as before' is slightly compressed to the point of ambiguity but wastes no words.

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

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

An output schema exists, so return values including the `next` cursor need not be re-explained. However, for a two-parameter, 0%-coverage schema, leaving `limit` entirely unaddressed makes the definition only minimally complete for a paginated 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?

Schema description coverage is 0% for both required parameters. The description does explain `before` semantically (null begins at the newest job), but says nothing about `limit` — no default, no sensible range — despite the schema allowing a nonsensical span from negative values up to 2^53. The reference to 'next' also assumes an output field name the caller must infer.

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 (list cloud exports) with ordering (newest first) and scope (across all projects), which helps separate it from list_projects and read_render. It does not explicitly name a sibling it excludes, but the scope phrase does the differentiation work.

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

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

Usage is implied by 'list this account's cloud exports' plus pagination instructions ('use next as before to fetch the next page'). There is no explicit when-to-use-vs-alternative guidance (e.g. read_render for a single job) or any note about when the list would be empty.

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. The description adds genuinely non-obvious session semantics — a loaded skill 'stays loaded for the conversation' and must not be re-loaded — which is operational context beyond the structured hints. It loses a point only for not clarifying error behavior or what happens if an id is invalid.

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 purpose in the first sentence, then guardrails. The trailing imperatives ('Do not write from a catalog line. Do not poll.') are terse and earn their place as failure-mode prevention, though there is mild repetition of the load-once rule.

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-param read tool with full schema coverage, no annotations gap, and no output schema, the description covers purpose, batching, timing relative to writes, and session lifetime. 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 description coverage is 100%, so both skillId and projectId are already documented, including the comma-separated syntax and the null-falls-back-to-open-project rule. The description reinforces the comma-separated example but adds no parameter meaning the schema lacks. Baseline 3 is correct.

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 ('Load the full body of AI Skills by skillId') and immediately contrasts it with the sibling catalog ('The system prompt catalog is titles only. It is not the body.'). An agent can distinguish this from read_film or patch_film 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 when-to-use and when-not-to-use: batch all needed ids in one call, load each named skill 'before the first write that needs it', never reload a loaded skill, and don't load unneeded skills. It even names the sibling writers (patch_film, replace_component, scaffold_component) that signal a load is required.

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

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

Annotations already declare 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?

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?

With annotations already declaring readOnly=false, destructive=false, idempotent=false, the description goes well beyond them: build and type-check failures reject the write before committing, the previous source and revision remain intact, warnings do not block the build, and the return is the Asset ID. It also discloses the project-wide compile blast radius and the animation-API restrictions (atTime only; animate/animateIn/animateOut generators refused).

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 operation, which is good, but the body is a dense wall that mixes several concerns (skill-loading order, import lists, animation API, shared modules, cross-component wiring). Most sentences carry real constraints, yet the skill-loading enumeration and import guidance are verbose and could be tightened or delegated to the skill docs themselves.

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 covers the return value (Asset ID), the rejection behavior, revision retention, the shared-module alternative for name, and the cross-component compilation implications. For a mutation tool with 4 required params and a project-wide side effect, nothing essential 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 75%, so the description partly compensates: it clarifies that replacements are applied together 'in one compile', that an empty replace deletes a span, and that branchId writes a version without switching the editor. Some of this restates the schema descriptions, but the atomic-application framing and the Asset ID return add meaning beyond the field-level docs.

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 — 'Apply exact source replacements to an existing component in one compile' — and immediately contrasts with named siblings ('Use import_element for an unchanged library element and scaffold_component for a skeleton'). An agent can distinguish this from replace_component, scaffold_component, and import_element 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?

Explicit routing: alternatives are named for adjacent cases (import_element, scaffold_component, patch_film placement), and the preconditions are spelled out (which builtin skills to load before the first component write, first fontFamily, first DataSrc prop, first flex layout). It also states when to use branchId vs. the current version.

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 that writes repair certain mistakes automatically and report each repair, that a non-compiling write writes nothing (atomic), that branchId writes a version without switching the editor, and the skill-loading contract. These are exactly the behavioral traits an agent needs and none are derivable from readOnlyHint/destructiveHint/idempotentHint.

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 purpose, repair and branchId semantics are front-loaded and tight, but the long inline catalogue of eleven skills and their triggers bloats the description considerably. Most of it is actionable, yet it reads as a reference list rather than lean routing text.

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

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

For a three-parameter, no-output-schema mutation tool this covers a lot: atomicity, auto-repair reporting, skill prerequisites, branchId behavior, and a note that film is XML rather than TS/JSX. What is missing is explicit differentiation from sibling edit tools and any mention of limits on replacement size or count.

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 schema coverage at 67%, the description usefully reinforces and extends parameter meaning: find must match byte-for-byte, replace empty deletes the span, all=false requires a unique match, branchId null means current version. It largely duplicates the branchId schema text but adds real semantics for the replacements sub-object.

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: apply exact replacements to main.film in one compile. It also conveys the atomic/repair mechanism that separates it from a plain text replacer. It does not explicitly contrast with close siblings like fix_film or replace_film, 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?

Provides real precondition guidance: load required skills before the first write that touches a given feature, all in one load_skill call, and explicitly exempts value-only patches from any skill. Also clarifies branchId null vs a list_branches id. However it never states when to choose patch_film over fix_film/replace_film/check_film, which is the most consequential routing decision here.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial value beyond them: it explains the mechanism (reads every frame and surrounding sound, a model picks the first frame), the exact return content (source second to millisecond, frame, frame rate, what the frame shows, sound-onset flag, numbered sheet), and a per-call cost (~0.34 credits). Gaps like rate limits or failure behavior keep it from a 5.

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

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

Front-loads purpose and is generally information-dense, with each sentence carrying mechanism, output, or usage. Slight redundancy (the cut/slow-down/sound-on-action idea appears in both the third and seventh sentences) and heavy illustrative flourishes cost it a point.

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 specifies the return payload, the mechanism, the cost, and the usage trigger, and pairs cleanly with the 80%-documented input schema. An agent has everything needed to call and interpret it.

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

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

Schema description coverage is 80%, so the parameters are largely self-documenting. The description contextualizes 'around' as 'a time you know roughly' with ~half-second prior precision, but adds no syntax or format detail beyond the schema and never explains 'window'. 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 ('Find the exact frame of a moment in a ready video') and immediately differentiates from siblings by naming briefs, transcripts, search_video_moments and contact sheets as coarse (~half-second) alternatives. An agent can tell this apart from those tools 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?

Explicit when-to-use ('A cut, a slow-down or a sound on an action needs its frame') plus an imperative to apply it ('Pin every cut, slow-down and sound that must land on an action'). It also names the alternative sources and their precision limit, so the routing decision is fully specified.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), it discloses credit consumption, that an already-running job is joined and not charged again, that a long cutout returns a Job ID to poll with wait_for_jobs, that results can be checked with preview_frame, and that missing photo/footage is surfaced for the user to set rather than guessed. That is substantive behavioral context not available in 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?

Purpose is front-loaded in the first sentence and every later sentence adds operational value (delegation, credits, job polling, verification). A few clauses are densely packed ('when one covers the seconds the effect plays over'), but there is no filler.

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

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

For a mutation tool with no output schema, the description covers the trigger source, side effects, credit cost, async return shape, and verification path. It is close to complete; only the concrete cost magnitude and exact error conditions are left implicit.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description only restates that clipId is the effect's clip id (from read_film's Effects waiting) without adding format or syntax detail. projectId is not addressed in the description at all, leaving the schema to carry it — baseline 3 applies.

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

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

The description names a specific verb and resource ('Make what an effect already in the film still needs, and link it in: its person mask or its face') and immediately scopes it against the alternatives cutout_person and track_faces. An agent can tell this is the orchestration/wiring tool rather than a raw mask or face generator.

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

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

It states the trigger context (effects listed under 'Effects waiting' by read_film), the decision rule for reusing an existing mask/face versus running cutout_person/track_faces, and that an in-flight run is joined rather than restarted. It stops short of an explicit 'do not use this when…' exclusion, so a 4 rather than 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond them: that zero is a valid timecode, that region renders at a higher resolution rather than upscaling the frame, and that the output image takes the region's shape. It stops short of describing pagination or the concrete return format.

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, each carrying distinct load: what it captures, how to get detail, and the anti-pattern to avoid. The task and its constraint are front-loaded with no filler.

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

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

For a four-required-parameter tool with no output schema, the description covers purpose, the undocumented timecode param, region/longEdge interaction and the sibling alternative. Only a brief note on the returned image format/type is absent, which is a minor gap rather than a blocking one.

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 75% and notably the required `timecode` parameter has no schema description at all; the description compensates by defining its unit and edge case ('in seconds. Zero is valid.'). It also adds the rationale and interaction for region/longEdge (why to pass region, that it raises effective resolution) beyond what the schema states, going past the baseline 3.

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

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

States a specific verb and resource ('Capture one composed frame'), scopes it to 'a known timecode in seconds', and explicitly distinguishes itself from the two sibling preview tools by naming preview_range as the contact-sheet alternative. An agent can route correctly without opening another 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 positive guidance (pass region to inspect small text, logos, thin lines, edges; longEdge sets size) and an explicit negative exclusion ('Do not loop over this to imitate a contact sheet; use preview_range'). This is exactly the when/when-not/alternative structure the dimension asks for.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real context by disclosing the output modality (contact sheet, spectrogram under each row, text summary of loudness and masking) and the input constraint that durationSeconds must be positive. It stops short of stating frame count, resolution, or cost, which would have made it 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?

Four short sentences, front-loaded with the core action and the output nature, with no filler. The final imperative 'read the pixels' is terse but informative about what to do with the result; slightly compressed phrasing costs it a point.

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 carries the burden of describing the return, and it does: a contact sheet plus optional per-row sound strips and a summary. For a read-only preview tool with annotations covering safety, this is nearly sufficient; only frame density and the meaning of startSeconds remain unstated.

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

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

Schema coverage is 50%: audio is exhaustively documented in the schema, while startSeconds and durationSeconds have no schema description. The description adds one genuine constraint not in the schema ('durationSeconds is positive') and clarifies audio's mix/tracks effect, but startSeconds is never explained beyond the vague 'source-time window', so it only partially compensates for the coverage gap.

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

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

States a concrete verb and resource: it returns a contact sheet of a source-time window in the composed timeline. An agent can infer the distinction from preview_frame (single frame) and preview_timeline (whole timeline) from the 'window'/'contact sheet' framing, but no sibling is named explicitly, so differentiation is inferential rather than stated.

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

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

'Use for motion and for lining sounds up with the frames' gives a positive use case, and the audio argument suggests when to enable the spectrogram. However, it never says when NOT to use this versus preview_frame or preview_timeline, nor what prerequisites exist, so guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real value beyond that: it discloses that the tool returns raster output ('Read the returned pixels') and that audio lanes produce a spectrogram plus a sound summary. It doesn't cover output size, cost, or pagination.

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 short sentences, front-loaded with the purpose and followed by the most decision-relevant instruction (audio modes) before the usage trigger. The audio sentence partially duplicates the schema's own audio description, which costs a little.

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 read tool with full schema coverage and no output schema, the description supplies purpose, usage context, and a return-format hint ('timestamped contact sheet', 'returned pixels'). Nothing essential to correct invocation is missing, though framing/resolution details are absent.

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

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

Schema description coverage is 100% and both parameters are documented in rich detail (including null semantics and the mix/tracks/none meaning), so the schema does the heavy lifting. The description only restates that you can 'pass audio mix or tracks', adding no syntax or defaults beyond the schema. 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 ('Look at' / preview) and a concrete resource ('a timestamped contact sheet of the entire composed timeline'), which implicitly distinguishes it from preview_frame and preview_range by scope. It never names those siblings explicitly, so differentiation is left to inference.

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

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

'Use after visual, timing or sound edits' gives a clear triggering context, and the audio mix/tracks instruction tells the agent which argument treats which situation. No alternatives or exclusions are named, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: rows are indexed, both window fields null means whole-asset-by-index, and transcript rows are individual words rather than sentences. It does not discuss limits/errors, but that gap is minor given 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?

Four sentences, all front-loaded and load-bearing: scope, window parameters, paging bounds, and the two routing warnings. Nothing is redundant with the title or 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 7-parameter read tool with no output schema, the description covers windowing, paging, and the shape of transcript rows. It could better describe what a returned row looks like per kind (beats, track, scenes), since there is no output schema to fall back on, but an agent has enough 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 57%, and the description fills key gaps: it explains the startSeconds/durationSeconds interaction (both null = whole asset by row index), that offset 0 starts at the first row, and that limit 1-40 bounds rows per page. These clarify offset/limit, which have no schema descriptions, though the meaning of the tai enum values remains undocumented anywhere.

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

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

States a specific verb and resource ('Read stored analysis rows of an asset') and scopes it with the window/start semantics. It also names the sibling it is not (read_transcript for readable conversation) and points to film props for full data, so an agent can distinguish it from read_transcript and read_film 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 explicit steer-away guidance: 'use read_transcript for readable conversation' and 'bind full data through film props, not these rows.' These are concrete alternatives and exclusions. It stops short of an explicit positive trigger for when raw rows are the right choice, so it is clear context rather than 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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so credit goes to the added context: the description discloses that hasAudio signals a soundtrack, that a call carrying times/range returns a picture plus legend rather than the brief, and what analysis.brief contains. It does not explain how 'readiness' is signaled, a minor gap.

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 purpose and the routing to sibling tools are front-loaded, then the analysis/preview details follow. Sentences are dense and occasionally sprawl (the long analysis.brief enumeration), but nearly every clause carries information an agent needs.

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 carries the return-value burden and does so well: it enumerates brief contents, the picture+legend response mode, and the hasAudio flag. The only lapse is that 'readiness' is mentioned but never explained for a tool whose name implies tracking an async upload.

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 baseline is 3, but the description adds real semantics: that times and startSeconds/endSeconds are mutually exclusive, that times draws up to 4 large frames while the range draws a contact sheet of ~16 tiles, and that the response format differs for those calls. This meaning goes beyond the already-rich schema 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 opening states a specific verb+resource (read an asset), enumerates what is returned (pixels, metadata, readiness, analysis), and names the sibling tools it is not (preview_frame and preview_range draw only the film). An agent can distinguish it from the preview siblings 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 explicitly routes the agent: id comes from search_assets, and for close video inspection it names preview_frame and preview_range as the alternatives that draw only the film, then explains what startSeconds/endSeconds/times do instead. It even gives the motivating use case (timing an action to a tenth of a second, checking a detail).

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that: it discloses the return shape (Asset ID plus numbered source), warns that line numbers are a display map not patch input, and states it does not write source. It stops short of describing the cap size or any limits on large reads.

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 front-loaded with the core purpose and each sentence carries routing or behavioral value. The run of three 'Does not ...; use ...' clauses is slightly repetitive but each maps to a distinct sibling, so waste is minimal.

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

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

For a read-only tool with full annotations and 100% schema coverage and no output schema, the description supplies everything an agent needs: name modes, offset/limit windowing, return contents (Asset ID, numbered source), and next-step placement via patch_film.

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

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

Schema description coverage is 100%, so baseline is 3. The description still adds meaning beyond the schema: it documents the 'shared/<name>' convention with its concrete path (src/components/custom/shared/<name>.ts), the empty-name listing behavior, and the 'null for the standard window' interpretation of offset/limit.

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 states a specific verb and resource: 'Read a TypeScript custom component by class name.' It distinguishes itself from nearby siblings (search_assets for uploaded media, search_elements for the published library, patch_component for editing) so an agent can route without opening the schema.

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

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

It explicitly names alternatives and the conditions that select them: 'Does not list uploaded media; use search_assets' and 'Does not list the published elements library; use search_elements.' It also gives a positive follow-up path ('Place the component with patch_film using the returned Asset ID') and warns against feeding line numbers into patch_component find.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral detail: null semantics for renewsAt/renewalCredits/runsOutAt and the fact that all generation capabilities draw from a single shared balance, which is the key behavior an agent needs to plan 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 in the first clause and every subsequent clause carries information (returned fields, shared balance, invocation timing). The first sentence is long and clause-dense, packing balance, available, renewsAt, renewalCredits and runsOutAt into one run-on structure, which slightly hurts scannability.

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

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

An output schema exists, so the description is not obligated to enumerate return fields, yet it does so with helpful null-case semantics. Combined with the spend guidance and no-parameter signature, an agent has nearly everything needed; the only gap is relationship to the similar read_points sibling.

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

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

The tool takes zero parameters and the schema is empty with additionalProperties=false, so there is nothing for the description to disambiguate. Per the zero-parameter baseline this sits at 4; the field enumeration describes outputs rather than inputs and so adds no parameter-level value.

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 the signed-in user's Vidova plan and credits') and enumerates exactly what is returned, including field-level semantics for balance, available, renewsAt, renewalCredits and runsOutAt. An agent can distinguish it from generic sibling readers like read_points without opening either schema.

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

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

Gives explicit situational guidance: 'Check it before costly work such as a long video or music generation,' and notes that agent/video/images/music/voice/analysis/search/cloud renders all spend from this one balance. It stops short of naming alternatives (e.g. read_points) or stating when not to call it, so it is clear context rather than a full when/when-not 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 already cover safety (readOnly, idempotent, non-destructive), and the description still adds substantial behavior: a throwing TypeScript component is switched off rather than breaking preview and the reason lands on channel scene, decoder failures land on preview-video, failed tool calls land on chat with input, and tracking logs downloads/worker boot/errors. It also discloses defaults (120s, warn+error, newest 40) and how afterSeq pages. This is well beyond what the annotations provide.

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

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

Dense but front-loaded: the channel taxonomy comes first, then the failure modes, then the call conditions, then the defaults and knobs. The channel inventory is long, yet each entry carries real diagnostic routing information rather than filler, so nearly every sentence earns its place.

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

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

For a read-only tool with no output schema, the description conveys the log line formats ([component] lines, 'tool <name> failed: <reason>'), the defaults, and the paging mechanism, which is enough to call and interpret it. It does not describe the overall return structure or ordering beyond 'newest 40 lines', a minor remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds usable intent on top: channels narrows, levels widens to info, sinceSeconds extends the window, and afterSeq pages past a line already seen. That maps each parameter to a practical purpose rather than restating its type.

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

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

States a specific verb and resource ('Read the editor's recent log') and then enumerates exactly which producers feed it (scene, preview, preview-video, web, chat, tracking). No sibling tool reads logs, so the scope is unambiguous and the agent can tell it apart from read_render, read_component, or read_analysis_range.

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 concrete trigger list: component does not appear, preview reports a failure, a tool call fails, or after a write to confirm nothing complained. That is strong when-to-use context, but there are no when-not conditions or named alternatives to compare against (none exist among the siblings).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond that: it bounds scope (no source code, files, or URLs) and discloses the failure mode ("Unknown ids fail"), which an agent needs for error handling.

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

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

Purpose is front-loaded in the first clause and every sentence carries information about scope or capability. It is slightly cluttered by the two consecutive skills clauses and parenthetical examples, which reduce scanability without being 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 read-only doc-fetch tool with no output schema, the description covers what is retrievable (contracts, signatures, behavior notes, skills craft), where valid ids come from, and what is out of scope. Nothing material an agent needs before calling 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 both `id` and `projectId` are already fully documented, including the skills-prefixed examples and the null/omitted behavior for projectId. The description's parameter content largely restates the schema, adding little beyond the 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 (read) plus resource (one API reference/guide page) and enumerates the content types returned: signatures, argument order, layout/text behavior, animation and SkSL shader contracts. It also pinpoints where ids come from (search_docs) and notes the secondary skills path, so an agent can separate it from search_docs without opening the schema. The only soft spot is the unaddressed relationship to the load_skill sibling for the skills path.

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 entry condition (an id from search_docs, a node/symbol name, or a guide name) and explicit negative scope: no implementation source, no arbitrary files or URLs. It does not, however, tell the agent when to pick this over load_skill for reading skills content, so the alternative routing is incomplete.

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