Plan AI video shots: model picks, sourced prompts, prompting guides and real $/s costs.
Scored across 10 tools
Descriptions do heavy lifting with explicit cross-references ("use this FIRST", "use get_prices", "use get_workflow"), which helps separate find_shot/best_prompt and guide/workflow. However fix_prompt is literally declared an alias of refine_shot, and plan_shots internally performs model recommendation that overlaps with recommend_model, creating genuine boundary ambiguity.
Nearly all tools use a snake_case verb_noun pattern (find_shot, get_guide, get_prices, get_workflow, plan_shots, recommend_model, refine_shot). Minor deviations: best_prompt uses adjective_noun and whats_new breaks the verb_noun form, but the convention is otherwise predictable.
Ten tools is well within the ideal range and each maps to a distinct job (search, full prompt, refine, guides, prices, workflows, planning, model choice, updates). No filler or trivially redundant tools beyond the deliberate alias.
The surface covers the core read-only lifecycle well: discovery (find_shot, whats_new), detail (best_prompt), decision support (get_prices, recommend_model, plan_shots), guidance (get_guide, get_workflow) and recovery (refine_shot). Minor gaps exist, e.g. no direct model-endpoint/capability lookup or way to retrieve a workflow/guide by browsing beyond slugs, but agents can work around these.
Get the full, sourced prompt that best matches a shot (free text or a slug from find_shot), optionally for a target model. Returns the exact prompt text as the creator posted it, the creator credit and source, the model it was made with, and factual adaptation notes when the target model differs (other Atlas shots on the target model and its current supported price). Atlas never claims how a prompt will perform on a model it was not made with; treat adaptation notes as guidance.
| Name | Required | Description | Default |
|---|---|---|---|
| shot | Yes | A slug from find_shot or a plain description of the shot. | |
| model | No | Target model family (optional). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context: it returns verbatim creator text, credit, source, and model, and it explicitly disclaims performance claims, framing adaptation notes as factual guidance only. That epistemic boundary is valuable and not derivable from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and return contents, followed by the adaptation caveat. The closing disclaimer is slightly long but it carries substantive semantic content, so it 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?
With no output schema, the description fully enumerates what is returned (exact prompt text, creator credit and source, source model, adaptation notes) and explains adaptation behavior. Combined with annotations covering safety, 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 baseline is 3, but the description goes further by clarifying what 'model' does — it triggers factual adaptation notes about other Atlas shots and current supported price when the target differs. That adds meaning beyond the schema's terse 'Target model family'.
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 ('Get the full, sourced prompt that best matches a shot') and names the distinguishing attribute (sourced, exact creator text). It is clearly separable from find_shot, which locates shots rather than returning prompt content.
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 accepted inputs (free text or a slug from find_shot) and the optional target-model case, which implies the find_shot → best_prompt workflow. It does not explicitly say when to prefer this over fix_prompt or refine_shot, so exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search AI Video Atlas's library of 106 sourced AI video shots (real prompts that creators posted, with the model used, an estimated cost and a link to the original). Use this FIRST when the user describes a shot, scene, style or job ("product ad with a rotating can", "anime fight", "lip sync dialogue", "drone over mountains"). Filters: shot_type (ads, music, shorts, characters, product, cinematic, lipsync, anime), model (e.g. kling, veo, seedance), max_cost_usd (estimated cost of the clip; when the prompt states no length we use a 5-second clip). Returns prompt excerpts; call best_prompt with a slug for the full prompt. Do not use for prices alone (use get_prices) or for tools/workflows (use get_workflow).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| model | No | Only shots made with this model family (strict; comparisons that merely include it are excluded), e.g. kling, veo, seedance, hailuo, runway, luma, wan, ltx, sora | |
| query | Yes | What the shot should look like or achieve, in plain words. | |
| shot_type | No | ||
| max_cost_usd | No | Max estimated cost per clip in USD |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new behavior: the dataset is a curated 106-shot library, results are prompt excerpts requiring a follow-up best_prompt call, and costs assume a 5-second clip when length is unstated. It does not cover pagination or the limit cap 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?
Dense but front-loaded: purpose and the 'use FIRST' trigger lead, then filters, then return format, then exclusions. Most sentences earn their place, though the parenthetical example list makes it 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?
With no output schema, the description still explains what comes back (prompt excerpts) and how to escalate (best_prompt with a slug), which is the key completeness gap it closes. Missing only limit/result-count behavior and any ordering guarantees.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60%, and the description compensates well: it enumerates shot_type values, gives concrete model examples (kling, veo, seedance), and explains max_cost_usd including the non-obvious 5-second-clip estimation heuristic. Only limit and the plain-words query intent are left unelaborated.
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 (Search) and resource (AI Video Atlas library of 106 sourced video shots) with concrete scope and content details (real prompts, model, cost, source link). It is clearly distinguishable from siblings like get_workflow and get_prices, which it names explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this FIRST when the user describes a shot, scene, style or job' with vivid example queries, and gives two negative exclusions routing to alternatives ('Do not use for prices alone (use get_prices) or for tools/workflows (use get_workflow)'). It also spells out the follow-up path via best_prompt.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Alias of refine_shot. Fix a generated shot that came out wrong. Pass the prompt you used, the model, the mode and what went wrong in plain words ("feet sliding", "face drifted", "line cut off", "too glossy", "label morphing"), plus optional frame notes. Returns a diagnosis, specific prompt changes (from Atlas craft fixes and a per-model failure-mode library, credited), a revised prompt, and an escalation ladder: same-model fixes first (prompt, seed/variation, references, duration), then a mode change, then a model switch only as a last resort with the consistency cost stated. Adapt the revised prompt to the user's voice; no generation is run.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Mode used: text-to-video, image-to-video, reference-to-video, start/end frame, video-to-video, lip sync. | |
| issue | Yes | What went wrong, in plain words. | |
| model | No | Model/endpoint used, e.g. "Seedance 2.5", "Veo 3.1 Fast". | |
| prompt | Yes | The exact prompt you used. | |
| seconds | No | Clip length used (helps check spoken-line fit). | |
| frame_url | No | Optional link to a bad frame (Atlas does not open it; describe it in frame_notes). | |
| frame_notes | No | Optional: what you see in the bad frames. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, it discloses that no generation is run, what the response contains (diagnosis, credited fixes, revised prompt), and the escalation ordering (same-model fixes, then mode change, then model switch with consistency cost stated). That escalation policy is behavior an agent cannot infer from any structured field.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the alias and one-line purpose, then the input expectations and the return/escalation contract. It is a long single paragraph, but nearly every clause carries non-redundant information; the only mild waste is minor repetition between "Fix a generated shot" and the alias sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must describe the return, and it does precisely: diagnosis, specific prompt changes with attribution, revised prompt, and a ranked escalation ladder. Inputs, behavior, and outputs are all covered for a 7-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description earns more by explaining the intended content of `issue` (plain-word symptoms like "feet sliding", "face drifted") and grouping which fields belong together (`prompt`/`model`/`mode`/symptom plus optional frame notes). It adds meaning rather than restating types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ("Fix a generated shot that came out wrong") and, critically, declares itself an alias of refine_shot, which disambiguates it from the sibling of the same function. An agent knows exactly what it does and how it relates to refine_shot without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context (a shot already came out wrong) and tells the agent what to supply: the prompt, model, mode, and the issue in plain words, plus optional frame notes. It never states when NOT to use it versus best_prompt/plan_shots, but the alias declaration does most of the routing work.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prompting guidance from AI Video Atlas, sourced from vendor prompting docs (Google, BytePlus, Runway, Luma, MiniMax, Alibaba, LTX, xAI, fal) plus proven Atlas examples. Pass model (kling, veo, seedance, runway, luma, hailuo, wan, ltx, grok-imagine…) for prompt structure, camera language, what the model responds to, things to avoid and known limits; or topic (shot-vocabulary, tagging, consistent-characters, i2v-vs-r2v, setup-playbooks). Every item carries its source URL; items marked atlas-editorial are our summary, not a vendor claim. Call with no arguments to list what exists. Use before writing a prompt for a specific model.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Optional filter, e.g. camera or avoid | |
| model | No | Model family, e.g. kling, veo, seedance, runway, luma, hailuo, wan, ltx, grok-imagine | |
| topic | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-open-world), so the description earns credit for adding provenance semantics: sourced vendor docs, per-item source URLs, and the atlas-editorial label distinguishing our summary from vendor claims. It omits freshness/pagination behavior, but for a read-only reference tool this is a strong 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-loaded with what the tool is and where the content comes from, then usage. The single long opening sentence is dense but every clause carries information; slightly heavy for a three-optional-param lookup 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?
With no output schema, the description usefully describes return shape — per-item source URLs and atlas-editorial markup — plus the no-arg listing mode. It does not explain how the three optional filters combine (AND vs OR) or overlap, which is the main unresolved question for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, and the description compensates by illustrating model values (kling, veo, seedance, runway, luma, hailuo, wan, ltx, grok-imagine) and topic values (shot-vocabulary, tagging, consistent-characters, i2v-vs-r2v, setup-playbooks). It also maps the model parameter to outcome categories. It never mentions the kind filter or how model/topic/kind interact, 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+resource: it returns prompting guidance sourced from named vendor docs plus Atlas examples, and enumerates the substance returned (prompt structure, camera language, responds-to, avoid, limits). Sibling differentiation is only implicit — "use before writing a prompt" hints it is a lookup rather than a generator like best_prompt/fix_prompt, but no sibling is named.
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 usage context ("Use before writing a prompt for a specific model") and an explicit zero-argument behavior for discovery. However, it names no alternative tools and states no when-not-to-use condition, so routing against the prompting siblings remains inferential.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Vendor-stated AI video prices per second from AI Video Atlas's tracker, each with its source URL and the date we checked it. Filter by model family or host. Legacy, deprecated and discontinued rows are excluded unless include_legacy=true (then they are flagged by status). Use for "how much does X cost", "cheapest model", or before quoting any cost.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | ||
| sort | No | cheapest | |
| model | No | ||
| include_legacy | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: legacy, deprecated and discontinued rows are filtered out by default and flagged by status when included, and each row carries a source URL and verification date. It stops short of describing pagination or result volume.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no filler: what the data is and where it comes from, then how filtering/legacy works, then when to reach for it. Front-loaded with the payload and the provenance.
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 helpfully sketches the returned fields (price per second, source URL, check date, status) and covers the default-filtering behavior. Coverage is good but not exhaustive: the sort options and any result-size limits go unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the load. It does explain include_legacy precisely and implies the host/model filters ('Filter by model family or host'), but the sort parameter and its 'cheapest' vs 'model' enum are never mentioned, leaving one of four parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: 'Vendor-stated AI video prices per second from AI Video Atlas's tracker', with the unit (per second) and provenance named. No sibling tool touches pricing, and the description makes the scope unmistakable.
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 are given: 'how much does X cost', 'cheapest model', 'before quoting any cost'. It also states the default exclusion of legacy rows and how to opt in. It lacks a when-not or an explicit pointer to a sibling, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How-to workflows, tools and model guides for AI video, grouped by job: consistent-character (Keep a character consistent), lip-sync (Lip sync & talking heads), product-ad (Product ads & UGC), camera (Direct the camera), long (Longer & multi-shot videos), i2v (Animate a still image), edit (Edit or restyle footage), upscale (Upscale & smooth), local (Run it on your own GPU), models (Models & hosts). Pass job for a curated list, query for free text (e.g. "comfyui lipsync", "upscale to 4k"), or slug for one item in full. Returns sources, creators, license and price as stated.
| Name | Required | Description | Default |
|---|---|---|---|
| job | No | ||
| slug | No | ||
| limit | No | ||
| query | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds useful context about what comes back ('sources, creators, license and price as stated'), but says nothing about pagination, limits, or behavior when a slug/job misses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the opening clause, then the job taxonomy, then the three access modes, then the return fields — a logical progression. It is dense but every clause earns its place, with the only redundancy being the job list repeating the schema enum (offset by the parenthetical glosses).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description usefully names the return fields (sources, creators, license, price), so an agent knows what to expect. Combined with strong enum and annotation coverage the definition is largely self-sufficient; the missing limit/pagination semantics is the remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the full param burden and largely does so: it explains job (curated list), query (free text, with two concrete example queries), and slug ('one item in full'). The limit parameter (default 8, max 25) is never mentioned, so one of four params remains undocumented in both schema and 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+resource — returns how-to workflows, tools and model guides for AI video — and enumerates the job taxonomy with human-readable glosses, so the agent knows exactly what content this surfaces. It does not, however, differentiate itself from near-siblings like get_guide or recommend_model, which likely overlap in scope.
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 mode-selection context: 'Pass job for a curated list, query for free text (e.g. "comfyui lipsync", "upscale to 4k"), or slug for one item in full.' That is concrete invocation guidance with examples. It stops short of stating when to prefer this tool over alternatives, and offers no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Goal: a usable take on the first generation, so fewer paid generations per shot. First review and rewrite the beat list (see brief_review): Atlas parses briefs with rules, so fix non-shots, missing subjects, placeholder lines and generic coverage before writing prompts. If the user names a model or mode, pass it in model/mode (it is kept for every shot unless the docs rule it out). Returns a GUIDANCE PACKAGE, not final prompts: you (the agent) write each full video prompt yourself from it. Per shot: model + mode decision with reasons, the per-model/per-mode prompt structure and tips, 2-3 credited proven example prompts, capabilities/limits/prices with sources, techniques and director rules (practitioner hints at low weight), required assets with image-gen guidance, an 11-section quality checklist, and a starter draft (starting point only, never paste it as-is). If the user names a model or mode, pass it in model/mode (or keep it verbatim in description): Atlas keeps it for every shot unless the vendor docs rule it out, and explains why in user_named. Write each final prompt as flowing, sectioned prose sentences (subject/action, camera/lens/movement, location/light/color, style, audio), never field labels like speaker_id: or Subject:, and without stock filler phrases. Also returns intake (questions to ask the user + stated assumptions) and package_markdown (readable). Plan a multi-shot AI video from a plain description (deterministic, built only from Atlas data; no AI generation). Output is staged: decide (model/mode/clip length/aspect/cost with reasons and capability checks), direct (shot list with per-model prompts), assets (every reference/frame with status needs-generation|user-supplied|approved), image_prompts, and steps, which include a STOP: get the user to approve assets before generating any video. Global directives (same X in every shot, vertical, no text, style) apply to all shots; questions and request wording are never planned as shots; an explicit shot count is honored; clips longer than an endpoint's documented max are split. The description is split into beats (sentences, clauses, and cues like "then", "cut to", "close-up", "wide"). For each beat it returns a shot type; a recommended model endpoint with its current vendor-stated $/s and source; the generation mode to use (t2v, i2v, reference-to-video, start/end frame, v2v, lip sync; only modes the vendor docs confirm) with a one-line reason; image prompts for any input frames, plus a shared character/product reference sheet when shots must match; an adapted prompt built from the best-matching sourced example (credited and linked), an estimated cost (5 s per shot by default), and a how-to workflow when one applies (lip sync, consistent character…). It also returns a total. budget_usd (total) and/or max_per_shot steer it to cheaper supported endpoints; each shot also offers a cheaper alternative with its cost, and the plan says if the budget can't be met. Use this for "plan / storyboard / make me a video of…" requests; use find_shot for a single shot. Before presenting, adapt the wording to the user's voice, context and brand (names, tone, product details), but keep the prices, models, modes, clip lengths and reference tags exactly as returned.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Generation mode the user named. Kept for every shot unless the model cannot do it. | |
| model | No | Model the user named (e.g. "Seedance 2.5"). Atlas keeps it for every shot unless the vendor docs rule it out, and then says why. Always pass it when the user names one. | |
| style | No | Optional look applied to every shot, e.g. "35mm film, warm grade" or "anime". | |
| retries | No | Optional retry allowance as a cost multiplier (e.g. 1.5 = budget 50% extra generations for rejected takes). | |
| budget_usd | No | Optional total budget in USD. | |
| force_plan | No | Return a shot plan even when the request reads as a pricing-only question | |
| description | Yes | What the video should show, in plain words. Several beats are fine. | |
| clip_seconds | No | Seconds per shot (default 5). | |
| max_per_shot | No | Optional maximum USD per shot. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare a safe, deterministic, idempotent read. The description adds substantial behavior beyond that: deterministic output built only from Atlas data with no AI generation, the staged decide/direct/assets/image_prompts/steps output, a mandatory STOP for user asset approval, sourced vendor pricing, and the statement that returned prices/models must be kept verbatim. This is exactly the extra context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The lead ('Goal: a usable take on the first generation…') is front-loaded and useful, but the body is an undifferentiated wall of text. The model/mode instruction is repeated nearly verbatim ('If the user names a model or mode, pass it in model/mode…' appears twice), which is wasted ink in an otherwise long 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?
With no output schema, the description carries the full burden and largely does: it enumerates the staged return (model/mode decision, prompt structure, example prompts, assets, checklist, draft, intake, package_markdown, totals) and the budget behavior. It is complete, though the density makes the return shape harder to parse than it needs to be.
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: model/mode are 'kept for every shot unless the vendor docs rule it out' with an explanation surfaced in user_named, budget_usd/max_per_shot steer to cheaper supported endpoints and report when the budget can't be met, and retries acts as a cost multiplier. That goes beyond the schema's wording.
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: it plans a multi-shot AI video from a plain description and returns a 'guidance package, not final prompts'. It explicitly distinguishes itself from a sibling ('use find_shot for a single shot'), so an agent can route between them 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?
It names the trigger phrases ('plan / storyboard / make me a video of…') and routes single-shot requests to find_shot. It also explains steering via budget_usd/max_per_shot and force_plan. No explicit 'do not use when' beyond the sibling split, so not quite a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recommend which AI video model to use for a shot, with the evidence: how many sourced Atlas shots of that kind were made with each model, the cheapest supported vendor-stated $/s, and an estimated total for the clip length and number of clips. Pass budget_usd (total) and/or max_per_shot to drop models whose estimate exceeds it; over-budget models are listed with their cost. Each row includes the generation modes the vendor docs confirm (t2v, i2v, reference-to-video, start/end, v2v, lip sync; unknown where docs do not say). Legacy, deprecated and discontinued models are never recommended. Filters by the required mode FIRST (detected from the shot text or the mode argument; endpoints whose docs say unknown are excluded), then ranks the cheapest qualifying endpoint first and notes when a pricier one has more proof. Includes each endpoint's max clip length and splits long clips.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Required generation mode; detected from the shot text when omitted | |
| shot | Yes | ||
| clips | No | ||
| budget_usd | No | Total budget for all clips | |
| clip_seconds | No | ||
| max_per_shot | No | Max USD per clip |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent annotations: it discloses the filter-first-then-rank pipeline, exclusion of unknown-doc endpoints, the never-recommend rule for legacy/deprecated models, that over-budget models are still listed with cost, and clip splitting. These are non-obvious behaviors an agent could not infer from annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and the evidence list are front-loaded in the first sentence, and subsequent clauses each carry a distinct behavioral fact. It is dense and clause-heavy, but nearly every clause earns its place with a testable rule rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with no output schema, the description fully covers the return shape (rows with proof counts, cheapest $/s, modes, max clip length, split-clip handling) and the ordering/filtering behavior. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 50% schema description coverage, the description compensates materially: it clarifies budget_usd is a total across clips, max_per_shot is per clip, mode is auto-detected from shot text when omitted, and clips/clip_seconds feed the estimate. It adds real semantics beyond the terse schema, though the enum and defaults are already schema-documented.
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 — 'Recommend which AI video model to use for a shot' — and enumerates the evidence returned. It is immediately distinguishable from siblings like get_prices (raw pricing) and get_workflow (process), so an agent knows this is the recommendation engine.
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 when the tool's filters engage ('Pass budget_usd and/or max_per_shot to drop models whose estimate exceeds it') and the ordering rule that applies otherwise. It gives clear context for invoking it but never names a sibling as the alternative to use when this recommendation is not what's wanted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get to a usable take in as few further generations as possible when a shot came out wrong. Pass the prompt you used, the model, the mode and what went wrong in plain words ("feet sliding", "face drifted", "line cut off", "too glossy", "label morphing"), plus optional frame notes. Returns a diagnosis, specific prompt changes (from Atlas craft fixes and a per-model failure-mode library, credited), a revised prompt, and an escalation ladder: same-model fixes first (prompt, seed/variation, references, duration), then a mode change, then a model switch only as a last resort with the consistency cost stated. Adapt the revised prompt to the user's voice; no generation is run.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Mode used: text-to-video, image-to-video, reference-to-video, start/end frame, video-to-video, lip sync. | |
| issue | Yes | What went wrong, in plain words. | |
| model | No | Model/endpoint used, e.g. "Seedance 2.5", "Veo 3.1 Fast". | |
| prompt | Yes | The exact prompt you used. | |
| seconds | No | Clip length used (helps check spoken-line fit). | |
| frame_url | No | Optional link to a bad frame (Atlas does not open it; describe it in frame_notes). | |
| frame_notes | No | Optional: what you see in the bad frames. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this with the high-value statement 'no generation is run', removing a plausible misconception that this tool regenerates. It also discloses process traits beyond annotations: the same-model-first escalation ladder, model switch only as a last resort with stated consistency cost, and that revised prompts are adapted to the user's voice.
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 goal in the first clause before describing inputs and outputs, and every section (inputs, returns, escalation order) carries information. It is dense and runs long in a single sentence block, with the parenthetical issue examples adding bulk, but little is truly 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?
With no output schema, the description carries the full burden of describing returns, and it does: diagnosis, prompt changes with provenance, revised prompt, and a staged escalation ladder. All seven parameters are accounted for and the read-only nature is explicit, so nothing essential to invoking or interpreting the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it shows the expected granularity of 'issue' with concrete examples ('feet sliding', 'face drifted', 'line cut off'), which the schema's 'What went wrong, in plain words' does not convey. Remaining parameters are only referenced, not elaborated.
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 goal verb+resource: recover from a shot that came out wrong by getting to a usable take with minimal further generations. It enumerates exactly what it produces (diagnosis, specific prompt changes, revised prompt, escalation ladder) and explicitly says no generation is run, so an agent can distinguish it from fix_prompt/best_prompt 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 a clear triggering condition ('when a shot came out wrong') and tells the agent which inputs to pass (prompt, model, mode, what went wrong, optional frame notes). It does not name or exclude the sibling fix_prompt, so the boundary between correcting a prompt here vs. there 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.
What is new in AI Video Atlas: the newest sourced shots and guides added in the last N days (default 7), newest first, with X like counts where we have them ("new" otherwise). Use for "what's new in AI video", weekly roundups, or trend questions. For the full weekly digest (new models, price changes, new shots, legacy prices) read https://aivideoatlas.com/digest/latest.json.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| kind | No | all | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, closed-world, non-destructive behavior, so the bar is low. The description still adds real context: window scoping, newest-first ordering, and partial data handling where like counts are missing ("new" when absent).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads what the tool returns before moving to use cases and the alternative digest link. Three sentences, no filler, though the parenthetical about like counts could be tighter.
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 conveys the return shape (newest-first shots and guides with like counts). Annotations cover the safety profile, so the remaining gap is only the undocumented kind/limit parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains days ("last N days", default 7) but says nothing about kind (shots/guides/all) or limit, nor the 60/30 maximums, leaving two of three parameters undocumented anywhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (newest sourced shots and guides) with a scope (added in the last N days) and ordering (newest first). It is clearly a 'recent items feed' tool, distinct from point-lookup siblings like get_guide or find_shot, though it never names a sibling to sharpen the contrast.
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 triggering contexts: "what's new in AI video", weekly roundups, trend questions. It also points at an explicit alternative for a richer need (the full weekly digest JSON URL), which is genuine routing guidance, but it offers no when-not-to-use condition relative to the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
fix_promptrefine_shotplan_shots1 field changedInput schema / properties / retriesAdded value: +{
+ "description": "Optional retry allowance as a cost multiplier (e.g. 1.5 = budget 50% extra generations for rejected takes).",
+ "type": "number"
+}plan_shots2 fields changedInput schema / properties / modeAdded value: +{
+ "description": "Generation mode the user named. Kept for every shot unless the model cannot do it.",
+ "enum": [
+ "text-to-video",
+ "image-to-video",
+ "reference-to-video",
+ "start/end frame",
+ "video-to-video"
+ ],
+ "type": "string"
+}Input schema / properties / modelAdded value: +{
+ "description": "Model the user named (e.g. \"Seedance 2.5\"). Atlas keeps it for every shot unless the vendor docs rule it out, and then says why. Always pass it when the user names one.",
+ "type": "string"
+}best_promptfind_shotget_guideget_pricesget_workflowplan_shotsrecommend_modelwhats_newCreate and edit AI videos from chat: plan shots, generate scenes, and export stories and ads.
Plan, render, fix and publish multi-scene AI videos: scripts, storyboards, cast, narration, YouTube.
Practical filming plans for AI assistants, with tools to draft, check and export shot plans.
Shot breakdowns of video clips, plus logos and brand kits, for any AI assistant.
Add one secure layer between your agents and this server.
