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

Annotations already declare readOnly/openWorld/non-destructive, and the description adds genuinely new context: computation happens server-side, it is free and cached per asset, local files are uploaded automatically, only MP3/WAV are accepted, and analysis is truncated to the first 90 s by default. These are operational traits an agent could not infer from the annotations or schema alone.

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

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

A single dense paragraph, but front-loaded with purpose and output shape before moving to usage and input constraints; nearly every clause carries information. It is packed with nested parentheses and dashed asides, which costs some readability, but nothing is truly 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?

With no output schema, the description does the necessary work of enumerating return fields and their units (ms from file start, constant tempo, strength 0–1), plus format and length constraints. It is slightly incomplete on the mode parameter and on failure behavior (too-long or unsupported files), but an agent can call it correctly as written.

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 83%, so parameters like bpmHint, minGapMs, sensitivity and maxSeconds are already well documented in the schema. The description restates source types and the 90 s default but adds nothing about the 'mode' enum (bpm/peaks/both), which is the one parameter whose trade-off matters most here. Baseline 3 fits given the schema does the heavy lifting.

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

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

Opens with a specific verb+resource: 'Tempo and transient analysis of a music / voice file'. It immediately enumerates the concrete outputs (bpm, firstBeatMs, beats[], downbeats[], peaks[]) so the agent knows exactly what it gets, and no sibling tool (transcribe, generate_music, search_sounds) overlaps with this analysis function.

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 downstream guidance: 'Use beats for metronomic cuts and peaks for cuts on what the ear hears', and names the consuming tools (UPDATE_CLIP startMs/durationMs, CUT_TO_BEAT grid beats|peaks). What is missing is an explicit statement of when NOT to use it (e.g. for speech-to-text use vivid_transcribe instead), so it stops short of a 5.

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

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

Goes well beyond the annotations by disclosing cost (10 credits, refunded on analysis failure), that it consumes the plan's monthly analysis quota, a 30–90 s runtime, and that it waits by default. It also flags an edge case an agent could not infer — the jewelry geometry lock prompting in-app category confirmation and the name being taken from the analysis. These are exactly the operational facts readOnlyHint=false and idempotentHint=false 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?

Single dense paragraph that front-loads the core purpose and outputs before costs, timing, and caveats. Nearly every clause carries information, though the parenthetical field list and the nested cross-references make it feel packed; minor tightening would help readability without losing content.

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

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

With no output schema, the description compensates by enumerating the analysis fields and the render, and the schema covers jobId resume and image sourcing. The main residual gap is timeoutSec and what happens on timeout versus failure (the refund condition is stated only for failure), which an agent managing a 240 s default wait would benefit from knowing.

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 71%, so the schema already explains image (local path vs URL, size limits, CDN caveat), jobId resume semantics, locale, and assetId. The description adds meaning mainly for default waiting behavior and the category-confirmation flow, but leaves timeoutSec entirely undocumented in both schema and description. Baseline 3 is appropriate given the schema does most of the work.

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

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

States a specific verb and resource (analyze a product photo) and enumerates the concrete outputs it produces (name, category, colors, material, finish, style, keywords, plus a clean e-commerce render). It further distinguishes the result by explaining it is persisted as a PRODUCT reference usable in vivid_generate_image, which separates it from siblings like vivid_compare_product and vivid_product_sheet.

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 downstream reason to call it — analyzing so the product can later be featured by name in vivid_generate_image `products`, with vivid_list_references pointed to as the discovery path. It does not explicitly state when to choose vivid_compare_product or vivid_retouch instead, so the sibling differentiation is implied rather than 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 already declare readOnlyHint=true and openWorldHint=true; the description earns credit by explaining why a 'buy' tool is read-only ('never charges anything: the user picks the pack and pays in their browser'), which pre-empts the obvious wrong assumption. It also states the human-in-the-loop requirement. Minor gap: no note on link expiry or re-generation behavior.

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

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

Four short sentences, front-loaded with the core action, followed by triggers and then the operating procedure. No filler or repetition; every sentence carries distinct information.

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

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

For a single-optional-parameter tool with no output schema, the definition covers the action, the trigger conditions, what the user must do, the safety property (no charge), and the post-call workflow. Nothing an agent needs to call or act on 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%, and the schema already explains that creditsNeeded preselects the smallest covering pack. The description adds value by enumerating the actual pack sizes (500 / 1,500 / 5,000) and noting the optional auto top-up toggle, which the schema does not mention.

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?

Uses a specific verb and resource: 'Get the link where the user buys a credit pack.' It also names the pack tiers (500 / 1,500 / 5,000) and the auto top-up option, so the agent knows exactly what the tool returns, distinct from siblings like vivid_whoami or vivid_usage.

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 two explicit trigger conditions: a call that failed for lack of credits, or a big batch the balance from vivid_whoami will not cover. It also names the alternative source of truth (vivid_whoami) and prescribes the follow-up flow: show the link, wait for confirmation, then continue.

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 openWorldHint=true and non-idempotent/non-destructive, the description adds genuinely useful behavior: per-token credit billing at a 50% markup on provider price, non-streaming execution, and statelessness requiring the entire conversation each call. It omits failure modes, rate limits, and what happens on insufficient credits, so it is helpful but not complete.

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 operation and pricing, and nearly every clause carries information an agent needs. The heavy nested parentheticals (provider list, billing formula, model-listing hint, image shape) make it dense to scan, which is the only real cost.

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 covers the return payload anyway (reply text, token usage, credits charged). Combined with pricing, statelessness, model discovery, and multimodal input format, an agent has enough to call it correctly on the first try.

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

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

At 50% schema coverage, the description compensates for the undocumented 'messages' parameter by explaining the stateless full-history requirement and restating the image-part shape qualified by 'on vision models'. It says nothing about maxTokens (default 2000, cap 16000) or reasoningEffort behavior beyond the schema's own notes, leaving one 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 specific verb and resource ('Run one chat completion on VIVID's LLM routing') and enumerates the providers behind it, which cleanly separates it from the image/video/music generation siblings. 'Non-streaming' further pins down the exact operation.

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

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

It gives usable context: list models via vivid_list_models type="llm", expect credit billing at provider price + 50%, and pass the full conversation each call. It never explicitly says when to prefer this over a sibling or what it cannot do, so it stops short of full when/when-not guidance.

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

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

Goes well beyond the annotations by disclosing cost (1 credit per call, retries charged again), latency (~15–25 s), and the non-idempotent billing implication, which is exactly the kind of context the readOnlyHint/idempotentHint flags cannot convey. It also describes the comparison dimensions and the return payload.

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

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

Front-loaded with the purpose and packed with high-value facts, with no filler sentences. It is a single dense run-on paragraph, which slightly hurts scannability of the cost/latency and return-value 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, yet the description enumerates the return shape (match 0–1, verdict pass|review|fail, differences with severity, summary, fixPrompt), plus cost and timing. For a 5-parameter vision comparison tool, 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 coverage is 100%, so candidate, reference, focus, language and skuDescription are already documented in the schema. The description adds the useful constraint that only the product is compared and that skuDescription covers what the reference photo cannot show, but it does not add syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('checks that the product in a generated/retouched image matches the real product photo') and scopes it to product-only comparison with background ignored. This clearly separates it from siblings like vivid_analyze_product and vivid_retouch.

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

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

Gives clear context: use it as visual QC on a generated/retouched candidate against a SKU reference, and it names the downstream consumer of fixPrompt (vivid_retouch). It does not explicitly contrast with vivid_analyze_product, so the alternative-selection guidance is implied rather than stated.

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

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

Annotations establish a write, open-world, non-idempotent safety profile, while the description adds genuine behavioral context: server-side audio analysis is free, commands execute sequentially so later commands can use ids created earlier in the same batch, media is addressable via localId, and speed ramps preserve clip duration unless the source runs out. It does not cover failure/atomicity behavior or auth/rate limits, but against the supplied annotations this is substantial transparency.

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 long, but the tool exposes a large command union and the text is front-loaded with purpose and return value before grouped command references. It is dense and could be more scannable with bullet lists, but most sentences carry substantive semantics 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?

Given the massive input schema, no output schema, and roughly 25 command variants, the description covers essentially all command types, return id usage, media id mechanics, and ordering constraints such as applying recipes after CUT_TO_BEAT. It is nearly complete; the main missing pieces are error/atomicity behavior and explicit project-name semantics.

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

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

With only 50% schema description coverage, the description compensates by explaining media sources and localId semantics, enumerating canvas presets with dimensions, and giving detailed semantics for the command payloads. The required name parameter is not described, but its meaning is self-evident and the schema constrains it.

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

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

The opening sentence names a specific verb ('Create'), resource ('editor project/timeline'), and scope ('new project on the account'), then enumerates the workflow: canvas preset, media import, optional commands, and save. It also states the return value (project id and timeline summary), so the agent knows both what the tool does and what it produces.

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

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

It routes the agent to siblings for specific sub-tasks: vivid_edit_timeline/vivid_render_project for the returned id, vivid_analyze_audio for hand-planned cuts, vivid_transcribe for subtitle cues, and vivid_get_editor_project for ids. It does not explicitly state the when-not boundary versus vivid_edit_timeline for modifying an existing project, so it falls short of full when/when-not/alternatives guidance.

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

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

Adds far more than the annotations: 13-credit cost, free first sheet on free accounts, one free regeneration after a failed vision QC, full refund on a second failure, a 1-3 minute runtime with a wait-then-poll pattern, and de-duplication against in-progress sheets. None of this is inferable from readOnlyHint=false, non-idempotent, non-destructive.

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 every sentence carries an operational fact, with cost and timing up front. Slight cost: the action verb ('Starts a new sheet') arrives after a long definitional clause, and the first sentence is heavily loaded.

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 does not state what the call returns on success (e.g., a job/sheet id or a timeout signal), only that you should poll with vivid_product_sheet afterward. Everything else an agent needs, including cost, refund policy, runtime, and the wait budget, is present.

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

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

Schema coverage is 80%, so the parameters are largely self-documenting; the description's added value is explaining why extraPhotos exists (reconstructing angles the photos never show) and how waitSec interacts with the polling handoff. The language and projectId parameters get no extra treatment, but the schema already covers them.

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

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

States a specific verb and resource: it starts a new product reference sheet, defined concretely as a 2x2 grid (front, two category angles, worn/in use) generated from product photos. It also distinguishes itself from the same-family sibling vivid_product_sheet, which polls and shows price, so an agent can tell the two apart 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?

Names the alternatives and the conditions that select them: vivid_product_sheet for the price preview and for polling after the wait, vivid_list_references for product names, extraPhotos when photos omit side/back angles. It also covers the concurrent-request case (an in-flight sheet is awaited and nothing is charged).

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

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

Annotations only say this is a non-read-only, open-world, non-idempotent, non-destructive call. The description adds what an agent actually needs: 50-credit cost, 1–3 minute runtime, default blocking wait, the returned name (personId) and composite asset, consent recorded with timestamp and IP, and a content policy that refuses nudity or sexual photos.

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

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

Front-loaded with the purpose and the downstream use, and every sentence carries information. It is a dense single paragraph with heavy semicolon chaining and a trailing ellipsis list of attributes, 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?

For an 8-parameter, nested-object, credit-charging tool with no output schema, the description covers cost, latency, blocking behavior, return values, and the legal/ethical gate. The remaining gaps (locale, timeoutSec, projectId) are low-stakes plumbing, not decision-critical.

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?

At 50% schema coverage the description does real work: it explains the three photo views (left profile, front, right profile) as an identity composite, notes gender and age are required for `attributes`, lists the optional look fields, and gives accepted value formats in English (gender "Female", age "25-35"). However, `wait`, `timeoutSec`, `locale`, and `projectId` are never explained in the description, leaving a genuine 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 specific verb and resource ('Create a reusable TESTIMONIAL on the account') and defines what the entity is — a consistent, identity-locked person castable by name in vivid_generate_image. It also names the consuming sibling tool, so an agent can place it in the pipeline without opening anything else.

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 two explicit creation paths (`photos` for a real person, `attributes` for a from-scratch persona) with the conditions selecting each, and states a hard gating rule for `consent`: set true ONLY after the user confirms the pictured person is them or has consented, 'Never assume it.' The only thing absent is an explicit when-not-to-use-this-tool-elsewhere clause.

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

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

The description adds real value beyond the annotations by disclosing the write-to-disk behaviour and the returned local path. However, it does not explain the destructiveHint=true / idempotentHint=true annotations: whether an existing file is overwritten, how filename collisions are resolved, or what happens if the asset is a non-image/video type. Those are the key behaviours for an agent invoking a destructive filesystem write.

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

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

A single front-loaded sentence with zero filler, stating action, scope, destination, and return value. It is efficient, though so terse that it leaves the previously noted behavioural questions unanswered.

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?

It helpfully covers the return value despite there being no output schema, and covers destination semantics via the schema. For a destructive, open-world filesystem-writing tool with three parameters, it omits overwrite behaviour, supported asset types, and failure modes, leaving meaningful 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?

At 67% schema description coverage, the description needs to compensate and does not — it never mentions assetId, filename, or outputDir, nor explains that assetId is the source asset identifier. The only semantic context (directory created if missing, extension inferred) lives in the schema, not the description.

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

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

States a specific verb and resource ('Download an asset'), narrows scope to image/video, and adds the side effect plus return value (saved path). It does not explicitly distinguish itself from siblings like vivid_get_asset or vivid_list_assets, so an agent must infer that this is the local-file-retrieval variant.

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: download when you want the binary on disk. There is no explicit guidance on when to choose this over vivid_get_asset (metadata) or vividly_share_asset, and no mention of prerequisites such as authentication or that a local directory 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 destructiveHint=true, openWorldHint=true and idempotentHint=false, and the description is consistent with that. It adds real value beyond them: audio is analysed server-side for free, commands execute one at a time so later commands can reference earlier-created clips, speed ramps shorten a clip only when the source runs out, and results include warnings for effects that apply but won't be visible. However it never states transactionality or what happens to already-applied commands when one errors.

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 purpose, return shape and the render follow-up, and uses section labels (Timeline, Look, Text, Subtitles, Keyframes, Speed). But it is extremely dense, run-on and separator-choked, making it hard to scan; a fair amount reads as reference manual rather than tool-selection guidance.

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

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

For a tool with ~24 command variants, 4 top-level params and no output schema, the description covers most of what an agent needs, including the return payload (applied/errors, warnings, created ids, updated timeline). Remaining holes are undocumented commands and payloads (ADD_AUDIO_REACTIVE, portions of mask/animation payloads).

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 only 50% schema coverage, the description carries most of the payload semantics: beatInterval meaning (4 = one per bar), grid 'peaks' vs 'beats', mode redistribute vs snap, keyframe t measured from the clip start rather than the timeline, easing options and default, gradient fill presets, canvas preset dimensions. Gaps remain — ADD_AUDIO_REACTIVE is named with no explanation, and SET_MASK/SET_OBJECT_ANIMATION payload semantics are thin.

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 names a specific verb and resource — apply editing commands to a saved editor project, then save it back under the same id — and enumerates the domains covered (clips, trims, speed ramps, transitions, canvas preset, texts, subtitles, masks, keyframes, audio). It also distinguishes itself from siblings by routing rendering to vivid_render_project and id lookup to vivid_get_editor_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?

Explicit alternatives and ordering rules are given: use vivid_analyze_audio and its beats/peaks for hand-planned cuts instead of CUT_TO_BEAT, get cues from vivid_transcribe for subtitles, read ids from vivid_get_editor_project or the previous result's "created", and send APPLY_EFFECT_RECIPE after CUT_TO_BEAT. It even states preferences (recipes "preferred over hand-written effects/keyframes") and batch semantics.

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

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

Beyond the annotations (which only say non-read-only, open-world, non-idempotent, non-destructive), the description discloses the real behavioral facts: credits are charged per image and scale with model, the call blocks by default and polls up to timeoutSec, and it returns asset ids plus download URLs. It does not quantify cost or explain what happens to partial results, but the key operational traits are covered.

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 dense sentences, each doing distinct work: capability, reference modes, cost, and completion behavior. Front-loaded with the core action, no filler, and the routing hints are embedded rather than appended as noise.

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

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

For a 15-parameter generation tool with no output schema, the description is nearly sufficient: it explains the expensive, asynchronous, reference-driven nature of the call and what comes back. The one gap is that it does not explain how the various reference-URL parameters differ in practice, which the schema covers only partially.

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 87%, so parameters are already well documented. The description adds only marginal meaning — that reference URLs must be public and that products/testimonials correspond to the app's # / @ mentions. With the schema doing most of the work, 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 opens with a specific verb and resource ("Generate one or more images on VIVID from a text prompt") and immediately scopes the reference modes. It is unambiguous against siblings such as vivid_generate_video or vivid_retouch, which operate on different 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?

It routes the agent well: list saved references with vivid_list_references, host ad-hoc images via vivid_upload_file, and pick a model slug from vivid_list_models. It never states when NOT to use it (e.g. versus vivid_retouch for editing an existing asset), so it falls short of explicit 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?

Well beyond the supplied annotations, it discloses the credit cost model ('charged only when the track is ready'), per-provider credit amounts, expected render time (20-90 s, up to 3 min), the wait-then-poll contract with status "processing" and a taskId, the 7-day temporary URL, and the alternate download path via outputDir. These are exactly the operational facts an agent needs before spending credits.

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

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

The description is front-loaded with purpose and cost, then provider tradeoffs, then timing/polling, then output — a logical order for an agent. It is dense with parentheticals, nested quotes, and backticks, so it reads more like a spec than prose, but nearly every clause 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?

With eight parameters, no output schema, and a credit-spending mutation, this tool needs a lot of prose and gets it: return values, storage lifetime, polling path, and download option are all stated. There is no output schema to defer to, and the description still tells the agent exactly what a completed and an unfinished call look like.

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 baseline would be a 3, but the description adds genuine meaning: the prompt is the stylistic brief, durationSec is honored within 1-3 s for instrumentals but is only a hint on minimax, vocals without lyrics let Suno choose words and length, and waitSec matters because hosted connectors time out near a minute. Only filename and outputDir semantics remain thinly covered.

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

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

The description opens with a specific verb and resource: 'Generate an original music track from a text brief', then enumerates the brief's dimensions (genre, mood, instruments, BPM, use). This is clearly distinct from the sibling generation tools like vivid_generate_image and vivid_generate_video, and the named providers further pin down what kind of music output to expect.

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

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

It gives real decision criteria: pick suno-v6 by default for two takes and exact-ish duration, or minimax-music-3.0 for higher-fidelity single take without length control. It also routes the agent to vivid_music_status when waitSec elapses. What it lacks is an explicit statement of when not to use this tool, or how it relates to non-music siblings such as vivid_generate_voice.

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

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

Goes well beyond the annotations by disclosing cost semantics (credits pre-charged as credits/second × duration), expected latency (1–5 minutes), the default non-blocking return of a jobId, and a backend-resolved mutual-exclusivity warning. However, it never says what wait=true actually returns, and the annotations already cover the side-effect profile, so this is useful added context rather than a complete behavioral picture.

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 most decision-relevant facts are front-loaded (model selection, public URL requirement, credit pre-charge, polling). The dense final sentence about reference videos is information-rich but crams three per-model rule sets into one long line, which slightly hurts scanability.

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 15-parameter, non-idempotent, cost-incurring generation tool with no output schema, the description covers cost, latency, polling flow and URL requirements well. The remaining gap is the return contract: it says a jobId comes back by default but never describes what a blocking wait=true call yields or what the warning response looks like.

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 and the schema already documents most parameters (duration, referenceVideoUrls constraints, resolution defaults). The description adds real value on cross-parameter rules (mutual exclusivity of start/end frames vs reference images, billing for reference videos), but it does not explain several parameters the schema leaves bare, notably projectId and aspectRatio.

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 is a specific verb+resource ("Start a video generation on VIVID"), and the surrounding text makes it distinguishable from vivid_generate_image and vivid_job_status by scoping it to video generation. An agent can identify the tool's role without opening the schema.

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

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

It explicitly routes the agent to siblings: vivid_list_models (type=video) for model selection, vivid_upload_file for local files, vivid_job_status for polling, and states that wait=false is the preferred default. The when-not condition (don't use local files, use upload; don't block, use polling) is articulated rather than implied.

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

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

Annotations only say it is a non-read-only, non-destructive, non-idempotent, closed-world call; the description goes well beyond that by disclosing per-provider credit costs (1 / 1 / 0.5 / free), that output is a public MP3 URL kept only 7 days, and that saved voices require account-holder ownership, biometric consent and 18+ confirmation in the web app. Those are exactly the constraints an agent needs before spending credits or promising persistence, and nothing contradicts 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 the core action and the anti-cloning exclusion, then structured provider-by-provider with costs inline. It is dense and slightly run-on in the provider sentence, but nearly every clause carries actionable information, so little is wasted.

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

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

For an 8-parameter generation tool with no output schema, it covers the return value (public MP3 URL, 7-day expiry, optional local download), cost model, and the consent boundary around saved voices. Missing pieces are secondary input constraints — text length limit, speed range, locale default — which an agent would only learn by reading the schema.

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

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

With schema coverage at 38%, the description carries most of the load, and it does so for the hardest parameters: it defines what `voice` means per provider (preset name, preset id or saved-voice id, model id, English description) and confirms `emotion` is minimax-only. It leaves `speed`, `locale`, `filename` and the 3000-character text cap entirely to an undocumented schema, which is the remaining 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 specific verb and resource ("Synthesize speech from text") plus the accepted voice categories (preset, designed, saved). It explicitly disambiguates from a plausible sibling capability by saying it never clones from an audio file or URL, so an agent can tell what this tool is and is not.

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

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

Gives concrete routing guidance per provider: use vivid_list_voices for MiniMax ids, omnivoice for description-based design, deepgram for free Aura-2, gemini as the cheap default. It also rules out cloning. It stops short of naming alternatives for non-TTS needs (e.g. transcribe, generate_music), but within the TTS decision space the guidance is explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds what the payload contains (type, filename, favorite/public flags, share link, originating job), which is valuable given there is no output schema. It does not disclose error behavior when the ID is unknown or any permission requirements.

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 the resource named first and return fields parenthesized; nothing is redundant. The parenthetical field list is dense but 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 simple one-parameter read tool with safety annotations, the main gaps are the assetId format and failure behavior. The enumeration of returned fields partially compensates for the absent output schema, but the input side remains undocumented.

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 the single required parameter assetId, so the description bears full responsibility — and it provides no information about the identifier's format (UUID, job-derived, slug) or where an agent obtains one. 'One asset' only weakly implies an identifying key.

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

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

The description states a specific resource and scope ('Metadata for one asset') and enumerates the returned fields, which distinguishes it from vivid_list_assets (many assets) and vivid_download_asset (binary content). It is a noun phrase rather than a verb, but the retrieval intent is unambiguous.

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

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

There is no when-to-use guidance and no named alternative. The agent must infer that this is the single-asset lookup versus vivid_list_assets purely from the word 'one'. No prerequisites, no mention of needing an existing assetId.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing exactly what the read returns — nested clips with timing fields, effects, masks, text overlays — which tells the agent this is a read-only reconstruction of project state rather than a mutation.

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 return shape, followed by two short actionable sentences. The parenthetical field enumeration is dense but earns its place by telling the agent what ids and fields are available downstream; no filler sentences.

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 full burden of describing return values, and it does so thoroughly across every major timeline section. For a 2-parameter read tool with annotations covering safety, nothing an agent needs 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 only 50%: projectAssetId is documented in the schema ("Id from vivid_list_editor_projects"), but raw has no schema description. The description compensates by explaining that raw=true returns the full project JSON instead of the summarized timeline, which is the key decision the agent must make.

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 a saved editor project") and immediately enumerates the returned timeline contents: canvas preset, tracks, media library, clips, canvas objects, text overlays. This clearly separates it from vivid_list_editor_projects (listing) and vivid_edit_timeline (mutation).

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?

Routes the agent forward with "Use the ids in vivid_edit_timeline" and offers a clear alternative mode ("Pass raw=true to get the full project JSON instead"). It does not explicitly state when not to use it (e.g. use vivid_list_editor_projects first to discover ids), but the surrounding context makes the reading order obvious.

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 behavior beyond the annotations: the tool performs a side effect (provider status refresh) for video jobs, which fits the readOnlyHint=false declaration and would not be obvious from the schema. It also previews the return payload (status, asset id, download URL), which is valuable since no output schema exists. Missing are polling cadence, whether image jobs are stale without the refresh, and any rate-limit or auth notes.

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 clauses, front-loaded with purpose followed by the key operational caveat and the return shape. Every sentence adds information and nothing is repeated from structured fields.

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 single-parameter status tool with no output schema, the description covers purpose, the important video-refresh side effect, and the return contents. The remaining gap is the provenance of jobId and how often to poll, which an agent needs to call this reliably in a 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?

There is one parameter (jobId) with 0% schema description coverage, so the description carries the full burden and does not meet it. It never says where jobId comes from (generate_image/generate_video/list_jobs) or what format it takes, leaving the agent to guess.

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 ("Check a generation job") and scopes it to image or video jobs, which implicitly separates it from the music, render, and editor-status siblings. It stops short of naming those siblings explicitly, so the 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?

"Call it to advance a processing job" gives an actionable operating context, and the note that only video jobs trigger the provider refresh tells the agent when polling is productive. It does not name alternatives (e.g. vivid_list_jobs for discovery, vivid_music_status or vivid_render_status for other job kinds) or state any when-not-to-use condition.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the content taxonomy but says nothing about result ordering, pagination behavior, total counts, or what an empty gallery returns — details an agent would need when iterating pages.

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 compact sentence with the main idea front-loaded and no filler. The trailing parenthetical is dense and the ellipsis after 'video …' signals an incomplete value list, which is slightly sloppy but not 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?

With six parameters, zero schema coverage, and no output schema, the description should explain filtering and paging semantics. It instead covers roughly two of six parameters and leaves result shape, ordering, and pagination entirely unaddressed, which is thin for the tool's complexity.

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 full burden, and it only partially discharges it. It clarifies type (image | video | audio) and gives meaningful values for category (generated | ecommerce | model | context | video), but page, limit, favorite and projectId receive no explanation at all.

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 ('Browse the account gallery') and enumerates what lives there: generated images/videos, uploaded products, testimonials. That lets an agent distinguish it from a fetch-by-id sibling such as vivid_get_asset, though it doesn't explicitly contrast with vivid_list_references or vivid_list_projects.

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

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

There is no explicit when-to-use or when-not-to-use guidance. 'Browse' implies exploration rather than lookup, but the description never says to prefer this over vivid_list_references when hunting for reference material, or over vivid_get_asset when an id is already known.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description's help. The description adds only the downstream id usage for vivid_render_project and says nothing about pagination behavior or result ordering despite exposing a limit parameter.

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 core action is front-loaded before the follow-up hint. Nothing redundant is present.

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

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

For a simple list tool with no output schema and no required parameters, the description covers the action and one downstream use. It omits what the returned items contain beyond ids and how many are returned by default, which the absent output schema leaves unexplained.

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 would ideally compensate for the single 'limit' parameter. However, the parameter is self-describing via its default of 30, minimum 1, and maximum 100 in the schema, and the description adds no constraints or semantics of its own.

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 ('List the saved video-editor projects (timelines) of the account') and clarifies the 'timelines' terminology. It does not explicitly distinguish itself from the sibling vivid_list_projects, which an agent could easily confuse with this 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?

'Use the id with vivid_render_project' gives a useful follow-up path and implies the tool is a discovery step before rendering. It does not state when to use this versus vivid_list_projects or vivid_get_editor_project for details on a single project.

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 a safe, closed read (readOnlyHint true, destructiveHint false, openWorldHint false), so the description's burden is lighter. It adds ordering (newest first) and an implicit recency window, but says nothing about page sizes, total counts, or what a job record contains.

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

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

Two short sentences, front-loaded with the operation and ordering, followed by the filterable fields. No filler and no repetition of the tool name.

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 0% schema coverage, the description should carry more: it omits pagination semantics (page/limit defaults, max 100) and the projectId scoping parameter, which is likely the most common way an agent narrows this list. It is adequate for a simple list tool but leaves real gaps.

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

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

Schema description coverage is 0% across 5 parameters, so the description is the only source for accepted values. It helpfully enumerates type values (image_gen, video_ugc, product_analysis…) and status values (pending, processing, completed, failed), which the schema lacks entirely. However, page, limit, and especially projectId — a strong scoping parameter — go completely unexplained.

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

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

States a specific verb and resource ('List recent generation jobs') plus ordering ('newest first'), which distinguishes it from vivid_job_status and vivid_list_assets. It never names those siblings, so differentiation still requires the agent to compare names.

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

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

Usage is implied by the filter dimensions (type/status) and the word 'recent', giving an agent a reasonable sense of when to call it. There is no explicit statement of when to use vivid_job_status or vivid_list_assets instead, and no note on how far back 'recent' reaches.

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 a safe, closed read (readOnlyHint true, destructiveHint false, openWorldHint false), so the bar is lower. The description still adds real value by disclosing response shape: credit costs, capabilities, and that video models expose durations, resolutions, aspect ratios and support flags like startFrame/endFrame/reference/audio — 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?

Two sentences, both earning their place: the first defines the output, the second routes the agent to the consuming tools. Scope and the key return fields 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?

With no output schema, the description carries the return-value burden and does so for the model catalog, especially video models. It is slightly thinner on what image and llm entries contain, but for a single optional-param listing tool this is close to complete.

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

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

Schema coverage is 100% and the single `type` enum is fully documented in the schema, including the omit-default and the llm case. The description adds no syntax or semantics beyond that, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource ('List the AI models available to this account') and names what the response contains: credit cost and capabilities. No sibling tool lists models, so the purpose is unambiguous without opening any schema.

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

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

It states the downstream condition clearly: use the returned `slug` as the `model` argument of vivid_generate_image / vivid_generate_video, which implies calling this before generation. It gives no explicit 'do not call' case or note about caching, so it falls just 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds value by disclosing the payload shape (credits, capability flags, configuration state), which is the only source of return-value information since no output schema exists.

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

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

A single sentence fragment with zero filler, and the resource identity is front-loaded before the attribute list. Every clause (credits, capabilities, configured status) carries distinct informational weight.

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

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

For a zero-parameter, read-only catalog lookup with no output schema, the description supplies enough: what is listed, what fields to expect per entry, and the configuration flag. Nothing an agent needs in order to call it or interpret the result is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no parameter meaning left to explain. The description correctly adds no parameter prose, avoiding noise.

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 the concrete resource (music generation providers) and the specific attributes returned (credits, capabilities such as exact duration, vocals, max length, and server configuration status). This clearly separates it from siblings like vivid_list_models and vivid_list_voices, though the verb 'list' is only implied by the name 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?

There is no explicit when-to-use guidance, no mention of prerequisites, and no routing to alternatives. An agent must infer that this is a discovery step before vivid_generate_music; nothing in the text states that relationship or says when not to call it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered and the description only needs to add context. It adds the semantic notion of projects as account-scoped 'brand containers', but says nothing about ordering, pagination, or whether the list is complete or truncated.

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 the core action front-loaded and the purpose clause second. No filler, no repetition of the title, nothing that could be cut without losing 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 input parameters, complete annotations, and no output schema, the definition is close to sufficient for correct invocation. The remaining gap is that nothing describes what a returned project entry looks like (id, name, counts), which matters because the stated purpose is to supply an id for later calls.

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 baseline is 4 and there is nothing for the description to disambiguate. The parenthetical noting that project ids group generations is a small amount of useful semantics but no parameter meaning is at stake.

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

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

States a specific verb and resource ('List the account projects') and adds a clarifying gloss that these are 'brand containers'. It does not, however, distinguish itself from the similarly named sibling vivid_list_editor_projects, which an agent could easily confuse it with.

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

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

The trailing clause 'use a project id to group generations' hints at why an agent would call this (to obtain an id for downstream generation grouping), so usage is implied. There is no explicit when-not guidance and no mention of the alternative list_projects-adjacent sibling, leaving selection between them 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 cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower, and the description still adds real behavioral context: results include shared public talents flagged by isPublic, and each entry carries asset ids. It doesn't mention pagination, result limits, or ordering behavior beyond what the schema says.

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 statement of what is listed comes first, followed by the usage hint and the public-talent caveat. The parenthetical field enumerations with ellipses are slightly noisy but they do convey value, so the density is largely earned.

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 return values and does so for both resource types, including asset ids and the isPublic marker. What's missing is ordering/limit behavior and any hint about the `type` filter's effect on results, which matters for a three-parameter lister.

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 67%, and the description maps its subject matter onto the `type` values (products vs testimonials) and hints at isPublic, but it never explains the `type` enum options, the 'all' default, or the ordering effect of `projectId`. It adds modest meaning over the schema rather than compensating for the undocumented enum 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?

The description names a concrete verb (list) and two concrete resources (saved PRODUCTS and TESTIMONIALS/characters) and enumerates the fields returned (name, category, colors, material; name, gender, age, look; asset ids). That is enough to separate it from vivid_list_assets, though the description never names that near-sibling explicitly, so the differentiation is inferred rather than stated.

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

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

It gives a clear downstream purpose: use these names in vivid_generate_image's `products` / `testimonials` parameters to feature them with a locked look, equating this to typing #Product / @Testimonial in the app. There is no explicit when-not guidance or comparison against vivid_list_assets / vivid_get_asset, so it stops short of full 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered elsewhere. The description adds useful context by enumerating what the listing contains and that credit cost is exposed, but it says nothing about the response shape, pagination, or whether the list is static or account-dependent.

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

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

Two short sentences, front-loaded with the verb and resource, with the provider enumeration parenthetical doing real informational work rather than padding. The parenthetical is slightly dense but each named provider earns its place by telling the agent what families of voices exist.

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

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

For a zero-parameter read-only listing tool with annotations covering safety and no output schema, the description supplies the essential context: what is listed, which providers, and that pricing is included. The only modest gap is that the agent does not know the exact shape of each voice entry or whether the list varies per account.

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 there is no parameter meaning for the description to compensate for. The schema is trivially empty and nothing is left ambiguous about invocation.

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 ('List') and resource ('text-to-speech providers and preset voices') and names the concrete providers returned (Deepgram Aura-2, MiniMax HD, OmniVoice, Gemini 3.1 Flash) plus the credit cost field. This is clearly distinguishable from siblings like vivid_list_models or vivid_list_music_providers, which cover different resource domains.

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 tells the agent to call it before vivid_generate_voice, which is a real and actionable sequencing directive that picks out one sibling. It stops short of naming when-not-to-use or alternative discovery paths, but the intended workflow position is unambiguous.

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

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

Beyond the annotations (which only declare idempotent/non-destructive/non-open-world), the description discloses valuable behavior: the call blocks up to waitSec, returns a public URL on 'completed' or the same 'processing' status otherwise, and credits are charged only when the track is ready with failures free. It omits whether a file is written locally when outputDir is supplied, which matters given readOnlyHint=false.

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

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

Three short sentences, front-loaded with the purpose and the gating condition, then the wait semantics, then the billing rule. No redundant restatement of the name or title.

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

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

For a 4-parameter, no-output-schema tool, the description is largely self-sufficient: it explains the return value (public URL vs 'processing') that the missing output schema would otherwise cover, and it explains billing and blocking semantics. The remaining gap is the file-download side effect of filename/outputDir.

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 outputDir is documented in the schema), so the description must compensate. It does add real meaning for waitSec ('Waits up to `waitSec`') and implies taskId comes from vivid_generate_music, but it says nothing about `filename` or the download-to-disk behavior behind `outputDir`.

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

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

The description states a specific verb and resource ('Get the track of a vivid_generate_music call') and scopes the input to a task that previously returned 'processing', which lets an agent distinguish this from a generic job poller like vivid_job_status 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?

It clearly states the triggering condition (a vivid_generate_music call that returned 'processing') and what the wait does, but never names vivid_job_status or vivid_list_jobs as alternatives, so the agent must infer when to prefer this specialized poller over generic job status tools.

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

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

Annotations already cover safety (readOnly/non-destructive/closed-world), but the description adds real behavior: what is returned (four panels plus grid with download links, QC scores, or the failure message), the QC provenance (same vision QC as vivid_compare_product), the cost ('Free'), and the blocking wait. The only gap is that the wait/timeout caveat is carried mostly by the schema rather than here.

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 what the sheet is, then the read-only behavior, then the alternative tool, with no filler sentences. It is dense and semicolon-heavy, but every clause carries information an agent would otherwise have to guess.

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 explains the return value (panels, grid, download links, QC scores, failure message) and the cost/wait behavior. The only missing piece is the meaning of `projectId`, which an agent would have to infer.

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

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

Schema coverage is 67%, and the description reinforces the semantics of `waitSec` ('waits up to waitSec while one is being made') and `product` ('saved product'). However `projectId` is undocumented in both schema and description, so the description does not fully compensate 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 specific verb and resource ('The reference sheet of a saved product... This tool only reads: it returns the current sheet'), and describes the artifact concretely as a 2x2 grid. It explicitly distinguishes itself from vivid_create_product_sheet by naming what it does not do (make a new sheet).

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?

Routing is explicit: 'To make a new sheet use vivid_create_product_sheet.' It also states the read-and-wait pattern covers the case where a sheet is already being made, so an agent knows the call will not always return instantly and does not need to poll a separate status tool 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?

Discloses a lot beyond the annotations: local execution requirements (Chrome/Chromium, ffmpeg for mp4 vs webm fallback), auto-login on VIVID sites only with the session never leaked to other origins, upload-to-VIVID behavior, zero credit cost, and output format resolution. Given destructiveHint=true, it is silent on the fact that clicks/types/evaluate run for real against the target site and can cause irreversible changes there — a meaningful omission but not a contradiction.

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

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

Front-loaded with the core purpose and mechanism, then environment requirements, then tips — a sensible order. It is a dense single block and the tips section is slightly crammed, but nearly every clause carries information an agent needs before calling a 18-parameter tool.

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

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

For an 18-parameter tool with a nested step array and no output schema, it covers runtime prerequisites, output container choice, upload/no-upload behavior, and downstream consumption of durationMs. It leaves the concrete response shape mostly implicit (only durationMs is named) and does not describe failure behavior when a non-optional step's selector never appears.

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

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

Schema coverage is already 78%, and the description still adds value: it frames steps as an action vocabulary, explains pacing via waitMs, explains login seeding semantics for VIVID vs other sites, and calls out the durationMs return the agent must reuse. A few params (locale, stepTimeoutMs, tailMs/leadInMs tuning) get no extra meaning beyond the schema.

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

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

States a specific verb+resource ("Record a screen-capture video") plus the exact mechanism (local Chromium driven by Playwright with a scripted step list). It also names the downstream consumers (vivid_create_editor_project / vivid_edit_timeline) and the return value to pass (durationMs), which separates it cleanly from every sibling generator in the list.

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

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

Gives concrete usage context: one feature per recording, slow pace with waitMs, skip onboarding via a specific testid, and handing durationMs to the editor tools. It never states when NOT to use it (e.g. versus vivid_generate_video for synthetic footage), 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?

Goes well beyond the annotations: it discloses that rendering actually happens in the user's browser, that the job returns an openUrl that must be opened, that the editor uploads the MP4 and marks the job done, that a login on vividai.tv is required, and that phone browsers can abort long renders in the background. None of that is recoverable 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 action is front-loaded, followed by the render flow, the polling pointer, and the prerequisite caveat — each sentence carries new information. It is dense but not padded; the parenthetical about openBrowser is the only mild repetition of the schema.

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

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

With no output schema, the description carries the burden of explaining the return value and does so (openUrl must be opened for the job to progress). The asynchronous contract, the completion signal, and environment prerequisites are all covered, which is what an agent needs 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 80%, so parameters are largely self-documenting. The description only reinforces openBrowser behavior; it adds no guidance on wait vs. polling, timeoutSec trade-offs, or how the name parameter affects the output file.

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 — 'Queue a render (MP4 export) of a saved video-editor project' — and implicitly separates itself from vivid_render_status, which it names as the polling counterpart. An agent can pick this tool 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 the follow-up action ('Poll with vivid_render_status') and prerequisites (must be logged in on vividai.tv, preferably a desktop browser). It doesn't state when a render should not be queued or how it relates to vivid_get_editor_project / vivid_create_editor_project, so it falls short of a full when/when-not 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 declare this is a safe, non-destructive, closed-world read, so the safety profile is covered. The description adds genuine value beyond that by enumerating the possible returns — queued, rendering with progress, completed with output asset and download URL, failed — which is behavioral context the annotations cannot convey and there is no output schema to carry it.

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

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

A single front-loaded sentence with zero filler; the state enumeration is compact and informative. The embedded parentheticals are slightly dense but each clause carries content 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 and no annotations on return shape, the description does the heavy lifting by naming every terminal and intermediate state, which is what an agent needs to decide whether to poll again. The remaining gaps — polling guidance and whether 'failed' carries an error reason — are minor for a one-parameter status lookup.

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% for the single parameter renderJobId, so the schema itself explains nothing. The description partially compensates by tying the id to vivid_render_project, telling the agent where the value comes from, but it says nothing about format, validity, or error behavior for an unknown id.

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

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

States a specific resource ('Status of a render job') and scopes it to jobs 'created with vivid_render_project', which distinguishes it from the generic job endpoints. However, the sibling set contains vivid_job_status and vivid_music_status, and the description never explicitly contrasts itself with vivid_job_status, so the 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?

The phrase 'created with vivid_render_project' implies the natural workflow (call render, then poll this), which is real usage guidance. But it stops short of instructing when to poll versus when to stop, and gives no exclusion against vivid_job_status, leaving the agent to infer the alternative case.

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

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

Annotations already declare readOnly=false, destructive=false, openWorld=true, idempotent=false, so the mutation profile is partly covered. The description still adds genuinely valuable behavior: the ~40–60 s two-pass locate cost for `target`, per-model credit costs, the crop-and-composite pipeline that keeps unchanged pixels byte-identical, and the return value (new asset id + URL). That is meaningful disclosure 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?

Front-loaded with the core invariant (edit only one object, everything else untouched) and packed with useful specifics rather than filler. It is a single dense paragraph, though — the alternatives, cost table, and return info would be easier to scan as separate sentences.

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 supplies the return shape (new asset id + download URL) and the sensible follow-up chain via vivid_compare_product. For an 8-parameter, nested-schema, 88%-covered tool this covers everything an agent needs 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 88%, so the baseline is 3, and the description earns above that by adding economics and routing semantics the schema lacks entirely: model credit costs (6/4/3/2) and the fact that z-image requires region or mask, plus the latency implication of using `target` rather than `region`. It does not describe filename/outputDir, which is a minor omission.

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 (edit one object/area of an image) plus the defining constraint (every other pixel untouched), with a concrete before/after example. That scope makes it clearly distinct from siblings like vivid_generate_image, which regenerate whole frames.

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

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

Explains the three ways to specify location (target, region, mask) and which model needs region/mask, and routes the agent to vivid_compare_product afterwards with fixPrompt fed back. It never states the negative case explicitly — e.g. that a full-frame restyle should go to vivid_generate_image instead — which keeps it off a 5.

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

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

Beyond the safety annotations, it provides critical behavioral information about the results, such as the preview quality (MP3 ~128kbps), the specific licensing requirements for commercial use (attribution line), and warnings against using non-commercial assets in ads.

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 slightly lengthy but effectively front-loads the search function and logically flows through licensing, result format, and suggested workflow.

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

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

The description is highly complete, covering the source of the data, the licensing constraints, the technical specifications of the result (MP3 URL), and the suggested next steps for the resulting assets within the vivid ecosystem.

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

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

Although schema coverage is 100%, the description adds substantial semantic value by defining the implications of the licensing structure and the consequences of setting includeNonCommercial to true (i.e., usage in ads or product videos).

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 clearly states its purpose is to search the Freesound.org library for specific media types (music, loops, sound effects). It further distinguishes itself from generation tools like vivid_generate_music by advising users to use that alternative for briefs.

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 provides explicit guidelines on commercial vs. non-commercial use, detailing the default license filtering (CC0, CC BY). It also gives downstream usage advice by specifying how the resulting MP3 URLs should be passed to other vivid tools.

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

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

Adds real context beyond annotations: the public link requires no login, revoking breaks the link for everyone who already has it, and the response includes a `disclosure.notice` that must be relayed for AI-generated content. That disclosure requirement is a genuinely non-obvious behavioral contract, though the description doesn't say where the URL appears in the reply.

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 primary action and its consequence, then layers the secondary flag, the usage constraint, and the reply note. Dense and largely waste-free, though the favorite toggle sentence interrupts the share/revoke flow.

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 3-parameter mutation tool with no output schema, it covers consequence, idempotence implications, and the required disclosure relay. The one remaining gap is not naming the response field that carries the shareable URL.

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%, with `public` documented but `assetId` and `favorite` bare. The description compensates by framing `favorite` as an independent toggle and by clarifying that sharing means public-on/off, leaving only the obvious identifier 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?

States a specific verb and resource ('make an asset public and get a shareable URL'), plus the inverse action ('revoke sharing'), and adds the secondary favorite toggle. No sibling tool covers sharing, so the operation is unambiguous against the surrounding asset tools.

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

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

Gives an explicit precondition ('Only change sharing when the user asked to'), which is exactly the guardrail needed for a state-changing share action. It does not explain when the favorite toggle should be used alone versus combined with a share change, leaving that 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 readOnlyHint=false, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: the service is free, local files are uploaded on the caller's behalf, output is capped at 100 MB, and outputPath causes a file to be written to disk. Auth requirements and latency/queue behavior are the only notable omissions.

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 capability, then inputs, then outputs, then options — a logical order. It is dense and parenthetical-heavy in the return-value sentence, but essentially every clause carries information an agent needs; nothing is pure 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, and the description compensates fully by describing the three return shapes (words[], cues[], transcript) and the SRT/VTT alternative with its granularity switch. Combined with the stated input types and size limit, an agent has everything needed to call this correctly on the first attempt.

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

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

With 60% schema coverage, the description carries real weight: it explains format=srt|vtt, granularity=cue|word (including the karaoke/alignment use case), and that outputPath only applies to subtitle formats. It also clarifies the semantic difference between raw `words[]` timing and legibility-stretched `cues[]`, which the schema does not convey. The language parameter is only restated as a list, adding little.

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 ("Speech-to-text") with the engine named (Deepgram Nova-3) and enumerates the accepted inputs (asset id, public URL, local file). It also distinguishes itself from siblings like vivid_analyze_audio or vivid_generate_voice by making clear this produces transcripts/subtitles rather than analysis or synthesized speech.

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 operating context: three source types, three languages, a 100 MB ceiling, and the format/granularity switches that select between JSON and subtitle files. It does not explicitly say when to prefer this over vivid_analyze_audio or when not to use it, so there are no stated exclusions or named 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 write, open-world, non-idempotent, and non-destructive, and the description adds genuinely new behavior: files go to temporary storage, expire after 7 days, while generated results persist permanently in the gallery. That retention difference is operationally important for an agent deciding whether to reuse a URL later. Missing are practical constraints such as file-size limits or failure modes, which keeps 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?

Two sentences, no filler. The core action and its output come first, and the retention caveat follows as a useful second beat. Every clause carries actionable 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 only one parameter and no output schema, the description must explain the return value, and it does: a public URL suitable for the generation tools' URL parameters, plus expiry behavior. The remaining gap is operational limits (max size, accepted formats, failure behavior), which a caller would likely want before attempting an 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 100%, so the single `source` parameter is already documented as an absolute local path or http(s) URL. The description adds meaning beyond that by specifying accepted media types (image, video, audio) and clarifying that the parameter is an input the agent must supply as an absolute path or remote URL. It does not add format-specific guidance (e.g., supported extensions or size caps), so it is a step above the baseline rather than exhaustive.

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 (upload) and resource (local file or remote URL) and scopes the accepted media to image, video, or audio. It also states the output — a public URL — and maps that URL to the exact downstream parameters (startFrameUrl, referenceImageUrls, objectImageUrls, audioFileUrls), which distinguishes it from siblings like vivid_download_asset or vivid_list_references.

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 guidance on when this tool is the right step: upload first so the returned URL can be fed into the generation tools that take start-frame, reference-image, object-image, or audio parameters. It does not name an alternative tool or state exclusions (e.g., when to reuse an existing asset URL instead of re-uploading), so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful disclosure of what data is returned (per-modality usage against plan limits and current credits), but says nothing about the reporting period, timezone, or whether numbers are refreshed live.

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 the resource first and the informative parenthetical enumerating the return dimensions. No filler, no redundancy with the title or annotations.

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

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

For a zero-parameter read tool with no output schema, the description adequately conveys what categories of information come back. Minor gaps remain around freshness and period boundaries, but nothing an agent needs 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies a no-argument, account-scoped call rather than introducing any parameter concepts an agent would need to resolve.

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 the resource and its scope: a monthly usage summary for the account, enumerating the tracked dimensions (analyses, images, videos vs plan limits) plus current credits. That is far more specific than the title 'Monthly usage', though it does not explicitly distinguish itself from the closest sibling, vivid_whoami.

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 use case is only implied: an agent can infer it should call this before or after generating content to check quota. There is no explicit 'use this when' statement and no mention of related tools such as vivid_buy_credits for topping up or vivid_whoami for account identity.

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, destructiveHint=false and a closed world, so safety is covered. The description adds two useful behavioral facts on top of that: the identity scope is the API key, and the call is a safe first step to validate credentials before other operations. It doesn't describe failure behavior for an invalid key, which is the only remaining 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?

Two short sentences with zero redundancy. The payload description comes first and the actionable recommendation ('call this first') is front-loaded where an agent will see it.

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

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

There is no output schema, and the description compensates by naming the four returned fields, which is exactly what an agent needs from an identity call. For a parameterless read tool with full annotation coverage, 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly doesn't clutter itself with input discussion and instead spends its words on what the call returns.

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 ('Return the VIVID account linked to the API key') and enumerates the returned fields (name, email, plan, remaining credits). No sibling tool overlaps this purpose, so the agent can select it unambiguously.

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 ('Call this first to check the connection'), which is the key selection signal for a diagnostics/identity call. It stops short of naming alternatives or exclusions, but none of the siblings plausibly compete with it.

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