VAR2.ai

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

Annotations cover readOnlyHint=true, so safety is already handled, but the description adds real behavioral traits beyond that: 'One immediate snapshot, never loop' (no polling) and the constraint that jp_ ids start a render elsewhere rather than being accepted here. It stops short of describing the snapshot's shape, hence a 4 rather than 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?

Purpose is front-loaded, but the body is dense and repeats the routing idea in several phrasings ('NEVER answer null', 'pick by MEDIA WORD', the media-word list, the pair line). Useful content, but it reads as a routing memo rather than a tight definition and could be trimmed without losing coverage.

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-param read-only status tool with no output schema, it covers trigger phrases, disambiguation, parameter origin, and the no-loop behavior. What the snapshot actually returns is left implicit, which is a minor gap given the absence of an output schema.

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

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

Schema coverage is 0% with a bare string param, so the description must carry the load — and it does: placeholder_id is the plain-UUID of an already-queued render originating from var2_join_videos or var2_render_timeline, and a jp_… id is explicitly rejected. That is substantive semantics absent from the schema.

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

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

Opens with a specific verb+resource: 'Status check for a join / stitch render.' It explicitly carves itself apart from siblings by naming var2_get_video_result for plain video renders and var2_join_videos as its pair. An agent can route to it without opening a schema.

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

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

Gives explicit when-to-use triggers ('is it ready / done yet', status question with an id/link), explicit when-not ('action verbs ... → the matching create/modify tool, NOT a status tool'), and named alternatives per media type. Exclusions and alternatives are both present.

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

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

With only a title annotation, the description carries the full burden and delivers: it probes the object, deletes rejected bytes on signature/size mismatch, records the asset, and returns a real placeholder_id. The destructive deletion behavior is disclosed up front — a trait no annotation covers.

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 and dense with zero filler; the arrow notation compresses the register→placeholder_id→join_videos flow efficiently. Telegraphic style is slightly terse but every clause earns its place.

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

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

No output schema exists, yet the description explains the return (real placeholder_id) and the alternative output (public_url). For a 4-param validation tool with chaining implications, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds pipeline meaning: it ties `path`/`type` to the request_upload response and explains that the confirmed id feeds var2_join_videos, going beyond the field-level docs.

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

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

States a specific compound verb+resource (validate + register an uploaded file) and immediately scopes it against the sibling that created it (var2_request_upload). The mention of the resulting placeholder_id for var2_join_videos chaining lets an agent place it in the pipeline without opening any schema.

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

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

Explicit when-to-call (with `path` + `type` from the request_upload response AFTER the PUT succeeds) and explicit when-to-skip (optional; skip if you only need `public_url`). Both the trigger and the exclusion are named, leaving nothing 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?

With only a title annotation, the description carries the burden and does add real context: model trade-offs (trellis-2 default/best price vs tripo high-quality/PBR/≤20k faces/pricier) and share-link auto-resolution behavior. It omits async/long-running lifecycle and how results are retrieved (via var2_get_3d_result), which are meaningful gaps for a generation tool.

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

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

Front-loaded with the core capability, then routing rules and model trade-offs in dense arrow notation. Very efficient, though the telegraphic style is terse and slightly hard to parse.

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

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

There is no output schema, so the description should explain what calling it returns (job id? polling?), which it does not. It also leaves resolution/texture_size undefined and only implies the async lifecycle. Adequate for routing but incomplete for correct invocation mechanics.

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

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

Schema coverage is 60%. The description enriches the image param (storage URL, share link, or any https URL — pass the link the user gave) and the model param (default and pricing tiers). But resolution and texture_size enums have no semantics in either schema or description, leaving genuine gaps.

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

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

States a specific verb and resource: produce a 3D mesh (.glb) from ONE image. It explicitly distinguishes itself from siblings — routing image-share-link actions here rather than to a status tool, and naming var2_create_image / var2_upload_asset as prerequisites. An agent can tell it apart from var2_get_3d_result 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?

Gives explicit when-to-use triggers ("Make a 3d model of this image/character"), when-to-use alternatives (no image → var2_create_image first; local file → var2_upload_asset first), and a subtle routing rule for var2.ai/image share links. It even warns against fabricating the URL.

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 supply only a title, so the description carries the full behavioral burden. It does disclose real constraints: the copyright filter (never name real artists or songs), the customMode-dependent prompt semantics, and per-type required fields. However, it never states that generation is asynchronous, that the call yields a job/placeholder id, or how the finished asset is retrieved (var2_get_audio_result / webhook) — the central behavioral trait of an asset-creation tool is left implicit.

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

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

The core purpose is front-loaded in the first clause, and the dense routing rules that follow each map to a real disambiguation need. It is long and mixes caps-lock emphasis with quoted user phrases, which hurts scanability slightly, but there is little filler.

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

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

For a 13-parameter creation tool with no annotations and no output schema, the description covers input-side behavior well: type routing, per-type required fields, prompt constraints, and the placeholder_id convention for follow-up calls. The missing piece is the output lifecycle — the description never tells the agent that a result must later be fetched or that a webhook fires.

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 92%, so the baseline is 3, and the description genuinely adds value on top: it maps user phrasing to the 'type' enum, clarifies that extend targets 'audioRecordId' with the source track's placeholder_id, and spells out the customMode=false vs customMode=true prompt contract (description vs full lyrics). Some of this duplicates the schema, which keeps it out of 5 territory.

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

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

The opening states a specific verb set and resource (create / extend / edit music, song, or track) and names the underlying provider (Suno). It actively differentiates from siblings ('never a video or image tool') and routes cover-art requests to var2_create_image. An agent can place this tool without opening any other schema.

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

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

Usage is mapped from natural-language user utterances to each type value ('make the song longer' → extend-music, 'replace seconds X-Y' → replace-music-section), with explicit exclusions ('never an invented tool'), a follow-up path for cover art, and a rule for resolving 'that track' from conversation context. This is about as explicit as routing guidance gets.

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 carry only a title, so the description bears nearly the full burden and does well: it discloses model defaults, per-model character ceilings, that auto_tag is 'free, limited per hour', tag placement semantics, and webhook signature/retry behavior via schema. The significant omission is that this is an asynchronous job — nothing tells the agent it must poll var2_get_dialog_result instead of expecting media back.

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

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

Dense but front-loaded: purpose and payload shape lead, then defaults, then the sibling exclusion. One weak spot is that the opening '≤5000 chars' and the later 'Combined text ≤10000 chars' sit far apart and are easy to misread as conflicting, though no sentence is outright filler.

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

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

For a 10-parameter, mutation-style tool with no output schema and title-only annotations, the description covers inputs, limits, limits-derived behavior, and locale handling thoroughly. It falls just short on the request lifecycle — it never says the work is queued and must be retrieved via var2_get_dialog_result, which is the one thing an agent needs to complete the flow.

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

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

Schema description coverage is already 90%, so the baseline is 3, and the description earns above that by contributing facts the schema lacks: the concrete default voice ids with human names (Sarah, George), the combined 10000-char budget across lines, and the semantics of where bracketed tags sit relative to words. Model, stability, and language_code semantics are left almost entirely to the schema.

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

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

The description states a specific verb and resource ('TTS / voice-over' creation) and immediately characterizes the payload shape ('dialogue = [{voice, text}, ...]'), so the agent knows this produces multi-speaker speech rather than a generic audio asset. It also actively differentiates itself from var2_get_voice_list ('NOT for voice browsing'), so it is distinguishable from at least one sibling without opening a schema.

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

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

It gives clear context for use (dialogue voice-over, model selection, Hebrew handling, tag writing) and one explicit exclusion that routes voice discovery to var2_get_voice_list, plus tells the agent where voice ids come from. It does not, however, distinguish itself from the other audio-producing sibling var2_create_audio, leaving the agent to infer single-speaker vs dialogue.

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 only a title annotation, the description carries the behavioral burden and does add real context: segment-map is FREE and ignores the prompt, image_refs are ignored by non-ref-aware models, model availability must be checked via var2_list_models rather than inferred from examples. It stops short of disclosing the async job lifecycle (that webhook/polling is needed and that var2_get_image_result retrieves output), which is the one material behavioral 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?

A single dense paragraph, front-loaded with the core capability and then the routing directives. It is information-efficient, though the mode/routing clauses are packed tightly enough that it reads more like a decision tree than prose.

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

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

For an 11-parameter tool with no output schema and no annotations, the description covers modes, model caveats, and sibling routing well enough to call correctly. It omits how the result is retrieved (var2_get_image_result / webhook or idempotency flow), which is the remaining completeness gap.

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

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

Schema description coverage is high (82%), so the baseline is 3. Most of the description's parameter guidance (type semantics, image_url requirement for image-to-image, image_refs locking, resolution not upscaling) is already stated in the schema's own field descriptions, so the description adds little that the agent doesn't already have.

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 ('Create a STILL IMAGE from a text prompt') and immediately enumerates the supported modes (text-to-image, image-to-image edit, storyboard per-frame). It explicitly distinguishes itself from var2_create_video, var2_create_3d, and var2_modify_image, so an agent can route without opening a schema.

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

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

Gives explicit when-to-use and when-not-to-use rules: upscale/'sharper' → var2_modify_image, animate → var2_create_video, 3D → var2_create_3d, model list → var2_list_models. It also pre-empts a common misclassification by declaring a multi-panel storyboard is N still-image calls, not a video.

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 contain only a title, so the description carries the full behavioral burden. It discloses model-specific capabilities (kling-3-omni edits up to 4K, ltx-2.3 always renders native audio, heygen-avatar-iv is 1080p only) and the 7-day draft-upgrade window, but never says the call is asynchronous or how a finished asset is retrieved via var2_get_video_result — the single most important behavior for a 35-param generation tool.

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

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

Front-loaded with the verb and the sibling exclusion, which is good, but the body is one long arrow-chained paragraph that duplicates the enum guidance already present in the `type` property description and ends with a 22-item model list also enumerated in the `model` enum. Information-dense but wasteful and hard to parse.

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

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

For a 35-parameter tool with no annotations and no output schema, routing is covered thoroughly but the description never explains what a successful call returns or how to poll for the result. That lifecycle gap is material, though the exceptionally rich schema partly compensates.

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 97%, so the baseline is 3, and the description adds genuinely new cross-field meaning: the input→`type` decision rule, which model each param pairing applies to, and the note that any https URL the user pasted is usable as-is. This is more than a restatement of the schema's per-param text.

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

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

Opens with a clear verb+resource ('Create video') and then spends the rest of the text distinguishing this tool from named siblings: var2_magic_replace for swap/recast/restyle, var2_get_image_result for ambiguous 'animate this image' cases, and var2_create_audio for songs/music. An agent can route to this tool without opening any schema.

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

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

Explicit when-to-use rules are given per input shape (existing clip → video-to-video, one image → image-to-video, 2-3 refs → reference-to-video, portrait+audio → audio-to-video, text only → text-to-video), including negative routing ('NEVER image-to-video for a /video/ link') and the alternative tool for edits. Nothing is left to inference.

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

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

readOnlyHint=true already tells the agent this is a safe, side-effect-free read, so the description's burden is lighter. It usefully implies the estimate applies to *planned* (not executed) calls, but says nothing about estimate accuracy, expiry, or what the response contains. Adequate with annotations carrying the safety profile.

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

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

Two short sentences, zero filler, with the core purpose front-loaded and the trigger condition second. Nothing could be removed 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?

For a batching tool over a 15-value type enum with nested params and no output schema, the description never indicates what the returned estimate looks like (per-item vs. total, currency, units). The readOnly annotation covers safety, but the return-value and input-shaping context are thin.

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% and the single `items` parameter is undocumented in the description beyond the phrase 'one or more planned create_* calls', which hints at batching but not the per-item structure. Nothing explains quantity limits, model_id, or how the 15 enum types map to cost models, so the description does not 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 (estimate) and resource (token cost) with scope ('one or more planned create_* calls'), which cleanly distinguishes it from every sibling that actually creates or fetches assets. An agent can tell immediately that this computes cost rather than producing media.

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 trigger is explicit: 'Use when the user asks "how much".' There are no competing cost-estimation siblings, so no exclusions are needed. It stops short of stating prerequisites, such as whether the params must mirror the intended create call exactly.

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 carry only a title, so the description bears the full burden and does so well: it discloses billing ('Paid per extracted frame through the normal approval/credit flow'), a determinism guarantee ('never estimates the endpoint from FPS'), and retry safety ('stable idempotency_key is required outside the assistant'). These are exactly the traits an agent needs and none are inferable from the schema.

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

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

Three dense sentences with zero filler, and the most important fact — that it extracts the real endpoint frames rather than an FPS estimate — is front-loaded. Every clause adds 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?

For a paid, four-parameter tool with no output schema, the description covers inputs, billing, retry semantics, and the nature of the returned assets. The one notable omission is whether the operation is synchronous or job-based (siblings like var2_get_video_result and var2_check_join_status suggest async patterns), which an agent would want to know before calling.

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 idempotency_key is described in the schema, and name/projectId are undocumented everywhere. The description compensates for video_url by enumerating accepted forms (Share link, ID, storage URL) and for idempotency_key with the deployment caveat, but leaves two of four parameters entirely unexplained, so it only partially closes the 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 ('Extract the ACTUAL first and last image frames') with a clear qualifier ('completed owned video') and states the output artifact ('reusable image assets for shared-frame shot chaining'). An agent can distinguish this from create_image, modify_image, get_image_result, and trim_audio without opening a schema.

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

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

Gives an explicit input condition ('Pass an owned video Share link, ID, or storage URL') and a prerequisite for the failure case ('import external videos first'), plus a deployment condition for idempotency_key ('required outside the assistant'). It does not name a sibling alternative or state when NOT to use it, so it stops short of a 5.

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

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

Annotations only declare readOnlyHint=true; the description adds a real behavioral constraint beyond that: 'One immediate snapshot, never loop,' which tells the agent not to poll. It also asserts a fallback rule ('NEVER answer null'). It stops short of describing what the snapshot contains, but the non-looping guidance is genuinely additive.

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

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

Purpose and the routing rule are front-loaded, which is good, but the body is a dense run-on of quoted user phrases, arrows, and a repeated example that restates the 'is it ready' case already covered earlier. The signal is present but padded.

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

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

For a single-parameter read-only status tool with no output schema and annotations covering the safety profile, the description covers routing, exclusions, and the non-polling expectation. It omits any hint of what the returned status values look like, which is the only notable gap.

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

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

Schema coverage is 0% and the single param is undocumented in the schema, so the description must carry it. It does convey that the parameter accepts a placeholder_id or a var2 link, and shows the placeholder form in an example, but it never states the expected string format or whether a link is parsed differently.

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

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

Starts with a specific verb+resource: 'Status check for a 3D MODEL / mesh / glb', and explicitly carves itself out from the sibling get_*_result tools by the 'media word' rule. An agent can distinguish it from var2_get_image_result or var2_get_video_result without opening any schema.

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

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

Gives explicit when-to-use ('Is it ready / done yet?' with an id/link), when-not-to-use (action verbs like 'animate it'/'upscale' route to create/modify tools, NOT status tools), and the selection rule among sibling status tools ('pick by MEDIA WORD'). It even supplies a worked example.

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, so the safety profile is covered. The description adds genuinely useful behavior beyond that: 'One immediate snapshot, never loop,' which tells the agent not to poll, and 'NEVER answer null — one var2_get_*_result always matches' sets expectations on the result. It doesn't cover auth or rate limits, but the added context is substantive.

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 densely packed with routing rules; every clause carries actionable content. Slightly repetitive, though — the phrase 'AUDIO: a song / music / track / tune' appears twice and the parenthetical examples are listy.

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, but the tool is a single-shot status check and the description conveys the snapshot behavior plus routing. It stops short of describing what the returned payload contains, though the inline_media schema field covers the rendering choice. Adequate for this 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 coverage is 50% and inline_media is already richly documented in the schema. The description compensates for the undocumented placeholder_id by clarifying it accepts 'placeholder_id or var2 link', which the schema alone does not state.

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

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

Starts with a specific verb+resource: 'Status check for AUDIO: a song / music / track / tune,' and explicitly routes by media word so an agent can distinguish it from var2_get_image_result, var2_get_video_result, etc. The scope 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?

Gives explicit when-to-use ('Is it ready / done yet?', 'check on it', status question with an id/link), when-not-to-use (action verbs like 'upscale', 'extend it' belong to create/modify tools), and names the paired tool var2_create_audio. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, but the description adds genuinely new behavior: what it returns (reference image urls) and how the result is consumed downstream (image_refs / reference_image_urls for look consistency). It does not cover error behavior for an unmatched name, keeping it short of a 5.

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

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

Front-loaded with the verb and scoped tightly to three sentences with no filler. The mid-sentence em-dash insertion of the listing rule is slightly awkward but the content all earns its place.

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

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

For a single-parameter read tool with readOnlyHint and no output schema, the description supplies the missing pieces: the return payload, the downstream parameter names it feeds, and the workflow ordering against regeneration. Nothing needed to invoke it correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the examples ('use my character Dana') show what the name value looks like in practice, and the no-name case is framed as a listing operation rather than an error.

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 (fetch) and resource (saved character/product/style sheet), and enumerates the natural-language phrasings that map to it. The contrast with var2_save_character and var2_create_image is implicit but clear: this retrieves a saved sheet rather than generating one.

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

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

Gives explicit routing rules: omit name to list saved sheets, and 'call this FIRST, never regenerate from a text prompt' for a referenced character. Both the when-to-use and the when-not-to-use (regeneration) cases are covered.

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 a human title, so the safety profile is covered. The description adds genuinely new behavior: 'One immediate snapshot, never loop' tells the agent not to poll, which is not in any structured field. It does not describe the shape of the returned status payload, which would be the 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?

Purpose is front-loaded, but the description is dense with repeated routing heuristics and repeats the media-type phrase twice ('VOICE-OVER / narration / dialog / spoken TTS clip'). Most sentences earn their place as disambiguation, yet the same message (this is the dialog status tool) is restated three times.

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

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

For a read-only status tool with no output schema, the description covers selection, alternatives, and the no-loop behavior, which is what an agent needs to call it correctly. It never explains what the status response actually contains (progress, URL, error states), which is the one remaining unknown.

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

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

Schema coverage is 50%: inline_media is fully documented in the schema, but placeholder_id has no description. The description compensates partially by stating that placeholder_id can be either an id or a 'var2 link', which is useful beyond the schema. With the other half of the meaning carried by the schema, a baseline 3 is appropriate.

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

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

The first sentence names a specific verb+resource: a status check for a voice-over/narration/dialog/TTS clip. It explicitly distinguishes itself from siblings by media type ('Is the voice-over done?' → THIS tool, never var2_get_video_result or var2_get_audio_result). An agent can route without opening any other schema.

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

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

Explicit when-to-use triggers ('Is it ready / done yet?', 'check on it', status question with an id/link), explicit when-NOT-to-use (action verbs like 'animate it'/'upscale' go to the matching create/modify tool), and the correct sibling pair (var2_create_dialog). It also states the routing rule for the ambiguous case (pick by media word).

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, so safety is covered; the description adds genuinely new behavioral context — 'One immediate snapshot, never loop' tells the agent not to poll, and the inline_media note warns against re-rendering an already-seen asset. It stops short of describing the snapshot payload shape, but that is the main gap.

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

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

The routing rule and the anti-pattern are front-loaded and every clause carries signal, but the slash-and-arrow phrasing is dense and slightly hard to parse compared with plain prose.

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

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

With no output schema, the description does enough: it states the snapshot nature, the non-looping expectation, and the media-word routing needed to pick among many var2_get_*_result siblings. Only the returned status values themselves are unspecified.

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

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

Schema coverage is only 50% (inline_media is fully documented in the schema), yet the description compensates by clarifying that placeholder_id accepts either an id or a var2 link. That is real meaning added beyond the bare schema, though it doesn't spell out format details for the id itself.

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+resource ('Status check for an IMAGE') and pins the routing key ('media word = an IMAGE → THIS tool'), letting an agent separate it from var2_get_video_result / var2_get_audio_result without opening any schema. It even names its create/modify counterparts.

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

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

It gives explicit trigger phrases ('is it ready / done yet', 'where is my …' + placeholder_id or var2 link), an explicit anti-pattern (action verbs → the matching create/modify tool, NOT a status tool), and the fallback rule that one var2_get_*_result always matches. Nothing is left to inference.

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

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

Beyond the readOnlyHint annotation, it discloses meaningful behavior: finished items render instantly while rendering ones fill in, and display=false returns state + URLs as data without rendering for chaining. These are non-obvious operational traits the annotations do not cover.

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, then usage rules, then parameter guidance. Dense and largely waste-free, though the trigger-phrase list and arrow shorthand make it longer than strictly necessary for an agent reader.

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 explaining what display=false returns (states + URLs). Combined with routing rules and item constraints, an agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real context: items accepts 2–24 mixed placeholder_ids and var2 links across images/videos/tracks/3D, and it clarifies the display flag's purpose for chaining rather than merely restating the schema. The empty-items prohibition reinforces the minItems constraint.

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 with scope: 'Show 2+ finished results in one gallery (browse / sort / group / filter)'. It explicitly routes the single-result case to var2_get_<modality>_result, so an agent can distinguish it from the entire var2_get_*_result family without opening schemas.

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

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

Provides concrete trigger phrases, an explicit boundary rule ('2+ existing var2 links or ids = THIS tool, not an upload'), a negative constraint ('Never call with empty items'), and names the correct alternatives for single results, model listing, and voice listing.

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, so the safety profile is covered. The description adds genuine behavioral context beyond that: it is one immediate snapshot and must never be looped, and a status question with an id must never be answered null. It does not describe the returned status values, but the snapshot/no-loop rule is a meaningful non-obvious trait.

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 routing intent is front-loaded and useful, but the text is a run-on packed with quoted example phrases and repeats the '(not a song / voice-over / stitched render)' exclusion twice. It is denser than needed and could be tightened without losing routing 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-parameter, read-only status tool with no output schema, the description covers routing, exclusions, and the no-loop behavior thoroughly. The one remaining gap is that it never hints at what the returned status looks like, though the absence of an output schema lowers that expectation.

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% (the single property is an undescribed string), so the description must carry the burden. It does clarify that placeholder_id accepts either a placeholder id or a var2 link/URL, which meaningfully extends the bare schema type.

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

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

The description names a specific verb+resource (status check for a VIDEO clip) and immediately scopes it against siblings by media word, explicitly excluding song, voice-over, and stitched render. An agent can distinguish this from var2_get_image_result or var2_get_dialog_result 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 gives explicit when-to-use triggers (status questions with an id/link), when-NOT (action verbs like 'animate it'/'upscale' route to create/modify tools), and names the exact alternative siblings (var2_check_join_status, var2_get_dialog_result). It even handles the edge case of a null answer and points to the paired create tool.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description additionally discloses catalog size differences between source modes ('account ~10-50 curated' vs 'library 10K+ searchable') and clarifies that 'he' means Hebrew-verified. It does not mention rate limits or auth requirements, but for a read-only list tool the added context is solid.

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

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

Front-loaded with purpose, then triggers, then source modes, then the sibling exclusion — an efficient ordering. The telegraphic fragment style ('THIS, never null') is dense but every clause carries routing or scoping value.

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

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

For a 13-parameter, zero-required, read-only list tool with no output schema, the description covers purpose, routing, source-mode semantics and filtering. Pagination is delegated to the schema (last_sort_id), which is acceptable; only return-shape expectations are left implicit.

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

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

Schema description coverage is 92%, so the schema already documents all 13 parameters thoroughly. The description's filter summary (gender / language / category) and source-mode note largely restate what the schema says, adding only the 'he = Hebrew-verified' nuance. Baseline 3 is appropriate.

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

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

Opens with a specific verb+resource ('Voice catalog (ElevenLabs)') and states the tool lists voices only. It explicitly names the sibling it is not ('speaking is var2_create_dialog'), so an agent can separate it from the create/result tools without opening a schema.

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

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

Provides concrete user-phrasing triggers ('what voices do you have', 'list voices', 'which voice for <language/style>', 'browse voices') and an emphatic routing rule ('→ THIS, never null'). It also names the alternative (var2_create_dialog) for the adjacent action of speaking, leaving nothing 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 carry only a title, so the description bears the full behavioral burden and does so: frame rounding (not whole seconds), no server-side frame extraction or comparison, renders take minutes-to-hours and consume compute budget, plan returns timeline_frames/fps, and plan_id lifecycle (jp_ prefix, resend full args if params changed). These are exactly the traits an agent cannot infer elsewhere.

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 two-pass contract, and most sentences earn their place. It is dense and long, and the duplicate-endpoint guidance is somewhat niche for the opening paragraph, but nothing is redundant filler.

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

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

For a 10-parameter, multi-stage rendering tool with no output schema and no meaningful annotations, the description covers the full lifecycle: planning, review, approval, render, and polling handoff, plus what the plan returns. An agent has everything needed to invoke it correctly end-to-end.

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

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

Schema description coverage is already 90%, so the baseline is 3. The description nonetheless adds real meaning beyond the schema: the plan_id-vs-status-id distinction, the 'call with ONLY {plan_id}' contract, and the 1/30s vs arbitrary-trim rule for duration_seconds. It stops short of covering every parameter (e.g. background_audio_volume), hence 4 rather than 5.

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

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

States a specific verb and resource ('Stitch videos / images / audio into one mp4 on a 30fps timeline'), and the 30fps timeline detail immediately distinguishes it from generic render/mux tools. The scope is unambiguous against siblings like var2_render_timeline or var2_create_video.

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

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

Explicitly prescribes the two-pass workflow (dry_run=true first, review with user, then dry_run=false), states the default, and names the correct polling tool (var2_check_join_status, NOT var2_get_video_result). It also gives a concrete when-to-use rule for the duplicate-endpoint fix. This is close to exhaustive routing guidance.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's job is lighter. It adds real value: it discloses that the response includes pricing, and that the tool is a catalog rather than a generator, which prevents wasted calls. It stops short of describing return shape or pagination, keeping it at a 4.

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 resource and a dense block of trigger phrases that each earn their place by covering a distinct user phrasing. The pipe-separated style is terse, though the middle trigger list reads slightly run-on.

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 one-optional-param, read-only list tool with no output schema and annotations covering safety, the description supplies purpose, routing, and trigger coverage. Return format details are not required since no output schema exists, but pricing/catalog shape could be fleshed out slightly.

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% and there is one enum parameter, but the enum values are self-explanatory strings in the schema. The description restates them ('image | video | audio | 3d | modify') and frames modality as a filter, which is only marginally more than the schema already conveys. Adequate but not compensatory.

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: 'Model catalog + pricing.' It immediately names what the tool returns and explicitly distinguishes itself from generator siblings ('Not a generator') and from var2_get_results. An agent can place it correctly in the toolset 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?

Provides explicit trigger phrases ('What/which models are available', 'show me <modality> models', 'browse models') and an edge-case rule ('even when a modality word like 3d appears'), plus the negative condition routing away from var2_get_results. This is exactly the when/when-not/alternative structure that earns a top score.

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 carrying only a title, the description bears full behavioral burden and delivers: per-engine duration/fps/reference limits, default resolutions, billing rules (per output second; minimax bills output + source), 'always generates sound' on minimax, the no-duration rule, analyze_only being free, per-clip analysis caching, and placeholder polling. This is unusually rich disclosure.

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

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

Front-loads the core purpose and modes before limits and tips, and given 15 parameters the length is largely justified. It is still a dense wall of text, and the trailing 'Reply in ONE short sentence + the share link; do not narrate tool calls' is output-format guidance that sits awkwardly inside the tool description.

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

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

Despite no output schema, it tells the agent it 'Returns a video placeholder (poll with var2_get_video_result),' and covers limits, billing, engine choice, target naming, and reference handling. Nothing needed to invoke this complex tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds practical meaning beyond the schema by explaining engine-selection heuristics ('use the default engine unless the user asks for MiniMax / Hailuo / H3 or 2K'), how to name the swap target, and character-reference best practices. Marginal gain is modest since the schema already documents every parameter thoroughly.

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 an EXISTING video clip, keeping its motion') and names the sibling alternatives it is not (var2_create_video for new footage, wan-2.7, ltx-retake). The three modes are spelled out with concrete examples, so an agent can distinguish this from every related sibling without opening a schema.

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

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

Explicitly says 'Use THIS tool whenever the input is an existing clip and the ask is replace / swap / recast / restyle,' then routes away from it for new footage, free-form prompt edits, and time-range retakes. It also directs the agent to analyze_only for ambiguity/cost and to var2_estimate_cost for a no-analysis estimate.

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 only a title annotation, the description still carries real behavioral weight: it names the available models and their limits (recraft ≤2048px, topaz factor 2–6), discloses that credits scale with output megapixels, and notes var2 share links are auto-resolved. It never says the job is asynchronous or how results are fetched, which is the one notable omission for a generation tool.

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

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

Front-loaded with the two core operations, then candidate triggers, then disambiguation. Dense and slightly overloaded with parenthetical synonyms and arrow chains, but nearly every clause routes or constrains a decision rather than padding.

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

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

For a 5-parameter async image tool with no output schema, the description covers types, models, credit implications, and input URL forms, with the webhook delivery contract documented in the schema. The missing piece is that the result is retrieved asynchronously (presumably via var2_get_image_result), leaving the post-call lifecycle implicit.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds value the schema lacks: it enumerates the valid model names and their resolution constraints, and cites the natural-language triggers that map to each type value. Defaults and factor range largely restate the schema, keeping it out of 5 territory.

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 two specific operations (background removal and upscaling) on a specific resource (an existing IMAGE), and explicitly disambiguates from siblings by media type: audio edits go to var2_create_audio, video to var2_create_video/var2_join_videos, stylistic edits to var2_create_image. An agent can select it without opening any schema.

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

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

Gives explicit conditions for use (upscale cues like 'sharper', 'enhance', '2K/4K/8K'; cut-out for background removal), states the closed type set ('no other type exists'), and routes alternative intents to the correct sibling tools. When-not-to-use is covered via the media-type exclusions.

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

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

Annotations carry only a title, so the description bears the disclosure burden and does well: it names the default mode, states that render=true queues (not completes) the render, and that captions are computed server-side with 'no frame math needed.' It stops short of saying what the call returns or what permissions are required, which is the only notable 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?

Front-loaded with the verb and resource, then mode/default, then the sibling escapes. It is dense with em-dash-heavy clauses but nearly every clause carries distinct information (modes, defaults, alternatives, captions behavior), with little padding.

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

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

For an 8-parameter tool with nested track/caption objects and no output schema, the description covers modes, defaults, input dialects (simplified tracks[] vs raw GUI schema), and how to get render status, which is enough to call it correctly. It could still say what a successful call returns (project id / job id), but the sibling hand-off mitigates that.

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 88%, so the schema documents name, assets, render, schema, tracks, captions, resolution and aspect_ratio in detail. The description mostly restates those fields; its only added semantic is that 30fps frames are canonical and 'seconds fields are converted exactly.' Baseline 3 is appropriate 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?

The description states a specific verb and resource ('Build a PRECISE multi-track video timeline ... save it as an editable project or queue the render') and contrasts itself against siblings by name (var2_join_videos, var2_check_join_status). An agent can distinguish it from var2_join_videos and var2_create_video without opening any schema.

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

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

Explicit routing: 'For simple back-to-back concatenation use var2_join_videos instead' and 'status of a queued render → var2_check_join_status.' It also gives the mode condition (render=false = save project, render=true = queue render) up front, so the when-to-use decision is fully specified.

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

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

With only a title annotation, the description carries the full burden and does so richly: single-use signed PUT, ~2h expiry, bytes never pass through model context, and the concrete host_not_allowed / sandboxed-egress failure mode with silent recovery steps. This is far beyond what any structured field provides.

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, then a numbered flow and a labeled recovery ladder — highly scannable. It is long, but nearly every sentence carries operational detail (PUT example, chunk sizes, anti-downscaling rule) rather than filler, so it mostly earns its length.

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

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

No output schema exists, yet the description explains all return values (upload_url, public_url, user_upload_page, placeholder_id) and the exact downstream fields public_url feeds into. For a multi-step upload tool this is complete enough to drive correct orchestration.

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

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

Schema description coverage is 100%, so the three parameters are already fully documented in the schema. The description restates the call shape {filename, type} and adds that public_url must be passed verbatim to downstream fields, but contributes little parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource: 'Signed URL to upload a LOCAL file straight into var2'. It also distinguishes itself from siblings by naming var2_upload_asset and var2_confirm_upload and clarifying scope ('LOCAL file', 'durable, first-party, no expiry'). An agent can tell it apart from the base64 upload path immediately.

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

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

Explicitly states when to use it ('user references a local/attached file... and you can perform an HTTP PUT') and when NOT ('Not needed when a public https URL already exists... or for tiny ≤1MB files'). It also provides an ordered recovery ladder and names the exact fallback 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?

With only a title in annotations, the description carries the behavioral burden and delivers the important non-obvious facts: images are copied into the in-app element library, durable URLs are returned, and re-using the same name replaces the existing sheet (an overwrite/upsert semantic that is not readable from the schema). It omits permission/auth requirements and any rate or size constraints beyond what the schema encodes.

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, then triggers, then flow guidance, then the sibling disambiguation. It is dense rather than bloated, though the run of example trigger phrases is longer than strictly necessary.

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

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

No output schema exists, but the description discloses the return value (durable URLs) and the overwrite behavior. For a 4-param upsert-style tool with full schema coverage and a title-only annotation set, 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 100%, so the baseline is 3, but the description adds real meaning for the name parameter by explaining the sheet is fetched later by that name and that re-using the name replaces the sheet — behavior the schema does not state. The kind/notes/images params are left to the (already thorough) 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 (save) and resource (character sheet = named set of reference images for reuse across sessions), and explicitly contrasts with the sibling var2_upload_asset for one-off uploads. An agent can distinguish it from upload/asset tools without opening any schema.

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

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

Provides concrete trigger phrases, names the alternative (var2_upload_asset) with the condition that selects it, and sketches the intended UGC pipeline (hero image → upscale → image-to-image angles → save). When-to-use and when-not-to-use are both covered.

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 carry a title, so the description bears the burden and delivers key behavior: it returns NEW asset(s) with url + placeholder_id while the 'original untouched' (non-destructive). It does not mention auth needs, rate limits, or failure handling, but the non-destructive return contract is the most important trait for this operation.

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

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

Front-loaded with the core purpose and the exclusivity claim, then triggers, then modes, then routing — a logical order with no filler. It is dense (a long compound paragraph with many semicolon clauses), which slightly trades readability for completeness.

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 10 parameters, no output schema, and no annotations beyond a title, the description still covers return shape (url + placeholder_id), non-destructive behavior, all three modes, segment caps/defaults, and sibling routing. 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 description coverage is 100% (baseline 3), yet the description adds real meaning beyond the schema: the interplay of start/end vs duration, the SMART lyrics-split guarantee ('never cuts mid-word, prefers line/chorus ends'), and mode defaults. It goes beyond restating field docs.

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

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

States a specific verb(s) and resource ('Cut or SPLIT AUDIO (a song / track / recording) by time') and explicitly claims exclusivity ('the only tool for that'). It also names the sibling tools it is not (var2_create_audio, var2_create_dialog) so an agent can route without opening schemas.

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

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

Provides concrete trigger phrases ('cut seconds X to Y out of my song', 'first 45 seconds'), enumerates the three operating modes, and explicitly routes alternatives: extend/replace music → var2_create_audio, voice-overs → var2_create_dialog. When-to-use and when-not-to-use are both covered.

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 carry only a title, so the description bears the full behavioral burden and delivers: durable storage, a no-expiry first-party url plus placeholder_id, a 100MB per-file cap, the requirement to pass expected_bytes/sha256 with base64 so truncation is rejected, and chunking behavior for large base64. This goes well beyond anything in the annotations.

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

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

Dense but front-loaded: the core distinction from create/modify/get tools and the create_* fallback leads, followed by operational detail. Every sentence is load-bearing for this routing-heavy tool, though the parenthetical-heavy style makes it heavier than strictly necessary.

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

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

For a complex 11-parameter tool with nested objects and no output schema, the description explains the return values (url, placeholder_id) and the full upload/chunking contract, so an agent has everything needed to invoke it correctly and use its result.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters including the chunk-session semantics and the native `file` object. The description reinforces usage (send the returned url verbatim as image_url/audio_url, pass expected_bytes) but adds little that isn't already in the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource ("Upload a file the user ATTACHED to the chat") with concrete examples (photo, logo PNG, voice memo) and explicitly distinguishes itself from the create_* generator siblings and the matching create/modify/get tools. An agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use (attached file, no link yet), when-NOT (link or placeholder_id present → hand to create/modify/get tool), the single pasted-link exception, and the text-only alternative (create_* generator). It also states this is called FIRST and how the returned url feeds later calls.

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