Wandura

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

Adds substantial context beyond annotations: credit spend is charged from the personal wallet only when the breakdown is saved, priced by length band, cached ads are free, the call blocks ~45 s and may return status 'pending', and there is a hard input limit of ~3 minutes. This reconciles the non-read-only, idempotent hints with real billing semantics.

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

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

Front-loaded with the verb and deliverable, then cost, then the pending/alternative workflow — a sensible order. It is dense and reads as one long run-on, with the credit rules packed into a single unwieldy sentence, so a little structure is lost but nothing is redundant.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly (each output artifact, the public page link, the credits field, and the 'pending' status with its follow-up call). Length limits, cost, and handoff to cinematic_ads_guide are all covered.

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% for the two parameters, so the baseline is 3. The description does add useful accepted-source context for 'url' (TikTok, Instagram, Facebook/Shorts, YouTube, Meta Ad Library, TikTok Creative Center, public .mp4) plus the ~3 minute cap, but it never mentions the optional 'video_url' parameter, leaving that half of the parameter surface to the schema alone.

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

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

States a specific verb and resource ('Break down a video ad') and enumerates the concrete artifacts returned: formula, hook, message, CTA, pacing, per-scene timings/jobs, remake tips, creative brief, script template, and public page link. It is clearly distinguishable from ad_breakdown_get (retrieval) and cinematic_ads_guide (remaking), which it names.

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

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

Gives explicit routing conditions: use ad_breakdown_get when status is 'pending', use cinematic_ads_guide to remake for the brand, and 'Ask the user before breaking down a new ad.' It also states the cost-free case (an ad already broken down by anyone) versus the paid case, so the agent knows when to spend.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive closed-world operation, and the description still adds real value: the async lifecycle (pending/ready/failed with failure reason), the polling cadence, the cost, and the payload shape once ready. Fail-state behavior and timing are exactly what an agent cannot infer from the hints.

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 the lifecycle, then the polling instruction — good ordering with no filler sentences. The long parenthetical listing the analysis sections is dense but genuinely helps an agent judge whether the payload is worth fetching.

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

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

There is no output schema and no annotations covering returns, so the description must describe the response itself — and it does, including status values, failure reasons, and the full content set once ready. Polling guidance closes the remaining operational gap for a one-parameter async fetch.

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

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

Schema coverage is 100% and the single parameter is already documented as 'Breakdown id from ad_breakdown.', which the description merely restates. Baseline 3 applies since the schema carries the parameter burden.

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

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

States a specific verb and resource ('Read one Ad Breakdown') and explicitly ties the required id back to the sibling tool ad_breakdown, so an agent can separate this read/fetch step from the creation step. The enumeration of what becomes available once ready further pins down the tool's role.

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 operational guidance: 'Free' and 'Poll every 20–30 s while pending,' which tells the agent exactly when and how to re-invoke. It stops short of naming when not to use it or pointing to an alternative (e.g., a list or batch variant), so it is clear context rather than a full when/when-not rule.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds non-derivable context: shared kinds are identical for all accounts while product/element are account-scoped and 'never show another account's uploads,' plus a 'Free' cost note. It stops short of describing pagination or how the default limit of 30 behaves.

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

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

Front-loaded with purpose, then usage, then scoping and cost, in three tight sentences with no filler. The account-isolation sentence overlaps somewhat with the kind parameter description in the schema, a minor redundancy, but every sentence otherwise earns its place.

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

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

For a read-only, closed-world browse tool with no output schema, the description covers what can be listed, when to call it, and account visibility boundaries. It omits the return shape and limit/pagination behavior, which is a modest gap but not blocking 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%, with q and kind documented but limit carrying only a default and maximum. The description's kind guidance ('shared' vs 'yours alone') largely duplicates the schema's own kind description, so it adds little beyond the structured field. Baseline 3 is appropriate given the schema does most of the work.

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

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

States a specific verb (browse) and resource (the creative library), then enumerates exactly what is browsable: shared creators, hooks, scenes, and the caller's own products and elements. It also differentiates itself from render_video by positioning itself as the lookup step that precedes rendering.

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

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

Gives an explicit trigger condition: 'Call this before render_video when the user wants a specific presenter or a saved product instead of one the model invents.' The alternative (letting the model invent a presenter/product) is named alongside the condition that selects this tool, leaving little 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?

The description adds substantial behavioral context beyond annotations: it spends credits, takes minutes, can run in multiple stretches up to ~10 minutes, returns {status:'running'} after about a minute, keeps running server-side, and must be polled via cinematic_ads_get_project. It also states that re-invoking while a run is active continues instead of restarting, which is crucial for correct agent 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?

The description is front-loaded with purpose and cost, then gives operational details in a logical order. It is slightly dense but every sentence provides necessary behavioral information (cost, duration, polling, continuation), with no obvious filler.

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

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

For a complex, asynchronous, credit-spending tool with no output schema, the description covers what the agent needs: purpose, cost warning, duration expectations, polling mechanism, continuation semantics, and the consequence of long steps. No critical gaps remain 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 100%, so the baseline is 3. The description adds practical meaning for price_only ('use price_only first to quote') and implicitly explains the effect of restart by stating that without it the run continues rather than starting over. It does not explain llmModel or project_id, but those are covered by the schema.

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

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

The description states a specific verb and resource: 'Analyse the original ad and prepare the remake from the user's brief: the cast, products and places (assets) and the clips to make.' It clearly distinguishes the analysis phase from project creation or clip updates, but does not explicitly name sibling tools it replaces (other than the polling tool).

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

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

It gives clear usage context: use price_only first to quote, it spends credits, long runs require polling cinematic_ads_get_project, never restart while running, and if already analysing it continues the run. It lacks explicit comparisons to sibling tools beyond the polling reference, so it is not a full 5.

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

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

Annotations already flag destructive=true and idempotent=true, but the description adds important context: it is free, overwrites project settings, is refused during an analysis, and explains the videoCopied behavior depending on whether the project has already been analysed. This meaningfully goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with the core action and then adds necessary behavioral constraints. Every sentence carries useful information, and the parenthetical details are compact rather than redundant.

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

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

For a destructive mutation tool with no output schema, the description covers the important operational facts: overwrite behavior, refusal during analysis, free status, video-copy semantics, and the alternative sibling for analysed projects. An agent has enough context to use it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description distinguishes saved templates from built-in presets and explains video-copy behavior tied to template contents, but it does not add syntax or deeper parameter-level guidance beyond what the schema supplies.

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: filling a project's settings and brand kit from either a saved template or a built-in preset. It distinguishes this from cinematic_ads_create_project by naming that sibling for the case where a video template should be applied to an already-analysed project.

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

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

The description gives clear usage conditions: use template_id or preset_id, apply is refused while an analysis runs, and for video templates in an analysed project use cinematic_ads_create_project with template_id instead. These are explicit when/when-not/alternative rules.

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

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

Adds substantial behavior beyond the annotations: it costs credits, is a small AI step, can return {status:'running'} after ~a minute and continue server-side, requires polling cinematic_ads_get_project, and must not be re-started while running. This directly complements the readOnlyHint=false and idempotentHint=false flags rather than contradicting them.

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?

Reasonably compact and front-loaded with the purpose before the credit and async-polling details. Three dense clauses; every sentence carries operational information, though the punctuation/abbreviation style is slightly terse.

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

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

For an async, credit-spending tool with no output schema, the description covers cost, expected latency, the running-status response, and the exact recovery action (poll get_project). An agent has everything needed to invoke and follow up correctly.

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

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

Only one parameter (project_id) with 100% schema coverage, so the schema already fully documents it. The description adds no format or sourcing detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource: it finds the original ad's brand mentions and app screens, with the sequencing qualifier 'after analysis' and 'without planning again'. This clearly separates it from cinematic_ads_analyze, though it doesn't name the sibling alternatives explicitly.

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

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

Gives a clear sequencing context ('after analysis', 'without planning again') that tells the agent when this step is appropriate. It also names cinematic_ads_get_project as the polling target, but offers no explicit when-not-to-use condition beyond the running-state warning.

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 flag readOnlyHint=false but not why; the description supplies the reason (it spends credits and writes a verdict), which is real added value beyond the structured fields. It still omits how many credits, latency, or how to retrieve the stored verdict.

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

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

Three short, front-loaded sentences: purpose first, cost warning second, side effect third. No filler or restatement of the name.

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

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

Given one required param, no output schema, and annotations that cover the safety profile, the description covers purpose, cost, and where the result lands. Only the retrieval path for the stored verdict is 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 coverage is 100% and the single clip_id parameter is already documented, so the description adds nothing parameter-specific. Baseline 3 applies since the schema carries the semantics.

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

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

Specific verb ('Check') plus a precise resource ('a finished clip') and an explicit detection target (burned-in text, logos, app screens). It does not name or contrast with the potentially confusable sibling cinematic_ads_brand_scan, so an agent must infer which scan to pick.

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

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

The phrase 'the remake must not carry' implies the QA step happens before a remake, which gives workflow context. But there is no explicit when-to-use statement, no prerequisite, and no comparison against brand_scan or analyze.

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

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

Goes well beyond annotations (readOnly=false, openWorld=true, idempotent=false) by disclosing that creation is free, that paid steps require a paid Wandura plan, and that costs come from either the user's credits or the workspace wallet depending on workspace_id. It also discloses the async contract: long steps return {status:'running'} after about a minute and continue server-side.

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

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

Front-loaded with purpose and cost model, then the flow. It is dense and somewhat long, with the full step list arguably duplicating what cinematic_ads_guide could carry, but every sentence conveys routing or polling information an agent needs.

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

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

No output schema exists, yet the description names the exact polling fields to check (project.status 'ready', production.done, exports[0].status 'done' and exports[0].url) and maps every downstream sibling. Nothing essential to calling this tool correctly within the pipeline is missing.

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

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

Schema coverage is 80%, so baseline is 3, but the description adds value not in the schema: original_ad_url must be MP4/MOV, up to 3 minutes and 300 MB, public https. It also clarifies the payment semantics of workspace_id (owns and pays) versus omitting it for a personal project.

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 ('Create a Cinematic Ads project') and immediately states its distinguishing behavior: optionally loading an original ad for remaking. Sibling tools are named throughout, so an agent can tell this is the pipeline entry point rather than a project mutator or reader.

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 'Call cinematic_ads_guide first' and lays out the ordered flow from create → analyze → poll get_project → optional refine/brand steps → make_images/make_video → export, with the exact stopping conditions. It also warns never to re-start the same step while it runs, which is a real usage pitfall.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so safety is covered structurally. The description adds genuinely new context with the caller-scoped ownership ('one of the caller's saved') and the zero-cost note ('Free.'), but says nothing about irreversibility or post-delete state.

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

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

Two short sentences, front-loaded with the action and resource; nothing is buried. The trailing 'Free.' is a terse fragment whose meaning (no credit cost) is inferable but not explicit.

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-parameter delete whose annotations already convey destructive/idempotent semantics and which needs no output schema, the description is nearly sufficient. It could still state that the deletion cannot be undone, which is the main 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?

Single required parameter with 100% schema description coverage, which already tells the agent the UUID comes from cinematic_ads_list_templates. The description adds no format, sourcing, or constraint detail beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb (Delete) and resource (one of the caller's saved Cinematic Ads templates), which is unambiguous and scopes ownership to the caller. It never names a sibling or explains how it relates to list_templates/get_template, but there is no competing delete tool, so confusion risk is low.

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

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

No when-to-use or when-not-to-use guidance, and no warning that deletion is permanent or how to recover. The only routing hint ('From cinematic_ads_list_templates.') lives in the schema, not the description.

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

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

Beyond the annotations, it discloses that copies are new projects with their own ids, that they arrive already analysed and resume at step 4, the naming convention '<name> (copy n)', the analysis-in-progress refusal, and that the operation is free. It also implicitly explains non-idempotency (each call yields fresh copies) and defers partial-limit behavior to 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?

Front-loaded with the core action and payload, then constraints and an example. Dense but every sentence carries information; the parenthetical example is useful but slightly bulky relative to the rest.

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 implicitly covers return semantics (new project ids, generated copy names) and the refusals/limits, which is enough to call it correctly. It stops short of stating the exact shape of the response (e.g., a list of new project ids and the 'limited' flag).

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description still adds meaningful semantics: copies are independent entities with separate asset ids, which explains what 'count' actually produces and motivates the multi-copy use case in the example.

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

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

States a specific verb and resource ('Make 1 to 5 copies of a project as it is now, in the same workspace') and enumerates exactly what is carried over (ad, analysis, cast/places, clip plan, settings, final-video choices). This clearly separates it from create_project, save_template, and clone_template siblings.

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

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

Explicit exclusions are given ('Never a clip take, a fix or a final video') plus a precondition ('Refused while the project is being analysed') and a concrete follow-up workflow routing to cinematic_ads_update_asset with ids from cinematic_ads_get_project. The agent knows when to pick this and when not to.

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

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

Adds substantial context beyond the annotations: it spends credits, takes minutes, is idempotent across identical option sets (corroborating idempotentHint), and returns {status:'running'} on long steps that continue server-side. It also documents the completion signal (exports[0].status 'done' → exports[0].url), which annotations alone would never convey.

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

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

The critical operational facts (credit spend, duration, idempotency, polling) are front-loaded in short, punchy sentences. The options passage is long and restates a fair amount of what the nested schema already says, which costs some efficiency, though it is organized and each clause carries information.

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

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

With no output schema, the description fills the gap by explaining the exports array status/url contract and the running/poll pattern. Combined with credit cost, idempotency, and inheritance defaults, an agent has everything needed to call this correctly and to interpret the result.

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

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

Schema coverage is already 100%, yet the description still adds real meaning: it explains that omitted options inherit the project preset/template watermark, that omitting a whole section takes the source build's choices for duplicated/templated projects, and advises sending only the delta the user asked for. That is genuine guidance beyond the field-level schema text.

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

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

"Build the final video from the finished clips" gives a specific verb and resource, and the enumeration of what it assembles (captions, watermark, end card, lesson cards, answer marks, cutaways) makes the scope concrete. The phrase "from the finished clips" implicitly separates it from the clip-making siblings like cinematic_ads_make_video and cinematic_ads_update_clip.

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

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

It states the key routing rule: use price_only to quote before spending, and note that cinematic_ads_fix_moment results flow into the next build rather than prompting a separate call. It also gives the concurrency rule (poll cinematic_ads_get_project, never restart a running step). It does not explicitly say when to prefer this over cinematic_ads_make_video or a template-apply path, so it falls just short of full when/when-not coverage.

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

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

Goes well beyond the annotations: it discloses that the call SPENDS CREDITS, that the range may silently grow to the nearest camera cut (a side effect on the output the agent would not otherwise expect), that long steps return {status:'running'} after ~1 minute and continue server-side, and that the fix surfaces later via exports[0].fixIds. The only gap is that it doesn't say what a failed or rejected fix looks like.

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

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

Dense but front-loaded: the action and its constraint come first, cost warning second, prerequisites and polling loop last. Some clauses (the end-card parenthetical, the repeated polling instruction) could be tightened, but every sentence carries operational 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 credit-spending, long-running mutation with no output schema, the description supplies the full lifecycle: prerequisites, cost/quote path, async polling semantics, how to confirm the fix landed, and the retry prohibition. An agent can call this correctly and recover from the async boundary without any outside knowledge.

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 still adds meaning the schema does not: the range becomes the region the system actually re-renders, it may be expanded to a camera cut, and price_only reports the range that will *really* change rather than the one requested. That is genuine semantic value for from_ms/to_ms and price_only.

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 — fix one moment of the finished final video — and defines the moment precisely (a marked range on the final video's own clock, 0.5–10 s, before the end card). It also tells the agent the key property that distinguishes it from `cinematic_ads_refine` and `cinematic_ads_undo_fix`: only that range is remade and the rest stays exactly as it is.

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 preconditions (production.done, one fix at a time), an explicit quoting alternative (price_only), and an explicit follow-up loop: watch production.fixes in cinematic_ads_get_project until status is 'ready', then call cinematic_ads_export again. It also forbids restarting a running step, which is exactly the misuse an agent would otherwise commit.

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 readOnlyHint/idempotentHint already covering the safety profile, the description still adds non-obvious context: that polling advances a running analysis to its next stretch, that the run is billed only once at completion ("Free"), and that images/clips in flight are reported. It does not cover auth needs or error behavior, and the disclosed job-advancement effect sits in tension with the readOnlyHint label, though it is disclosed rather than contradicted.

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

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

The purpose is front-loaded in the first clause, but the body is one very long sentence that packs four nested payload groupings plus billing and polling notes. The density is justified because no output schema exists and the enumeration substitutes for it, but it is not easy to scan.

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

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

With no output schema, the description carries the return-shape burden and does so thoroughly, listing every field group the agent will see plus the status/progress semantics. It also supplies the polling cadence needed to use it correctly, leaving no gap an agent must guess at.

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

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

There is a single parameter at 100% schema description coverage, and the schema already tells the agent where the project_id comes from (cinematic_ads_list_projects or cinematic_ads_create_project). The description adds no format, default, or constraint information beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource — retrieve one Cinematic Ads project — and enumerates the exact payload (project, assets, production, exports), which makes the singular scope unmistakable against cinematic_ads_list_projects and the mutation siblings like cinematic_ads_update_project. An agent can tell what it returns 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?

"Poll this every 30–60 s while something runs" gives explicit operating context and even a cadence, which is exactly the when-to-use guidance an agent needs for a status endpoint. It does not, however, name the alternative for enumerating projects (cinematic_ads_list_projects) or say when not to call it, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context beyond that: the guide covers user prompts, tool order, end-of-step checks, credit estimates, a pre-payment question, and polling/error handling, plus the 'Free' cost signal that annotations do not express.

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 imperative ordering directive, then enumerates the guide's contents in a single compact clause. The em-dash list is dense but every item (tool order, step checks, credit estimate, pre-payment question, polling, errors) is distinct information, with no filler.

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

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

No output schema exists, but the description adequately previews what the guide delivers (sequence, checks, credit estimate, polling/error guidance) so the agent knows what it will get back. For a zero-parameter documentation tool this is essentially complete; only a hint at the guide's format/size 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly spends no words on inputs.

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

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

States a specific resource (a step-by-step guide for remaking an existing video ad with Cinematic Ads) and its positional role relative to every cinematic_ads_* sibling. An agent can immediately tell this is a documentation/orientation tool rather than an action tool.

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

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

Explicitly says 'Read this before any other cinematic_ads_* tool', giving a hard ordering constraint rather than a vague suggestion, and adds that it is free so there is no cost reason to skip it. Among 50+ siblings this routing instruction is exactly what is needed.

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

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

Annotations already declare the safe read-only, idempotent, non-destructive profile, so the description only needed to add context — and it does: newest-first ordering, the exact fields returned per workspace, and the fact that this call costs nothing while downstream production steps draw on a project or workspace wallet.

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, cost and prerequisite are front-loaded, but roughly two-thirds of the text is a product pitch and an eleven-step cross-tool workflow that duplicates cinematic_ads_guide and does not help an agent call this zero-argument list tool. That tail does not earn its place in this definition.

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

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

For a no-parameter, read-only list tool with no output schema, the description covers what is returned (projects, plus workspace id/name/role), the ordering, the cost, and the prerequisite. Only the individual project fields are left unspecified, which is a minor gap.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline is 4. The description correctly adds no pseudo-parameter guidance.

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 clause states a specific verb+resource and even the ordering and returned fields: 'List the caller's Cinematic Ads projects (newest first) and the workspaces whose credits they can spend (id, name, role)'. That is unambiguous and clearly distinct from cinematic_ads_list_templates or browse_library.

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

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

It gives actionable routing guidance ('pass a workspace id to cinematic_ads_create_project to have that workspace pay'), a cost signal ('Free'), and a prerequisite ('Call cinematic_ads_guide first'). It stops short of stating when NOT to use this tool, but the context it provides is genuinely operational.

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

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

Annotations already cover the readOnly/idempotent/non-destructive profile, so the bar is lower; the description still adds non-obvious context: results are a 'display summary only' (so callers shouldn't expect full settings payloads) and the call is 'Free'. It does not mention auth scope or rate limits, but the cost signal and the summary-only caveat are real value-adds.

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?

There is little wasted content, but the text is delivered as one very long run-on sentence loaded with nested parentheticals and em-dashes, making the field semantics harder to parse on first read. Front-loading what is returned is good; the packaging is dense enough to cost readability.

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

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

With no output schema, the description carries the burden and does so well: it documents both returned keys, representative fields (id format like preset:langla, name, appName, iconUrl), and the conditional `video` object with its contents. Only pagination/empty-result behavior is unaddressed, a minor omission for a zero-param listing.

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?

This tool takes zero parameters, which sets the baseline at 4. The description's mentions of preset_id and template_id correctly describe how the returned ids feed *other* tools rather than misrepresenting this schema, which strengthens rather than confuses parameter understanding.

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 both collections returned (`templates` and `presets`) and enumerates their fields, so an agent knows exactly what this retrieves. It implicitly distinguishes itself from get_template and search_templates by framing results as the caller's saved templates plus built-in presets. It never opens with a verb like 'List', but the content 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?

It gives concrete routing: when a user names a brand, look it up in `presets` and pass its id as preset_id to cinematic_ads_create_project or cinematic_ads_apply_template, while a saved template's id goes to template_id. This is explicit downstream usage. It does not state when *not* to call it (e.g., versus search_templates or get_template), leaving a small gap.

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

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

Annotations only declare readOnly=false, idempotent=false, openWorld=true; the description adds critical context those do not carry: it spends credits per image, images are rendered sequentially, a concurrency ceiling stops the batch and names what remains, and long steps return {status:'running'} after ~a minute while continuing server-side. This is materially richer than the structured hints.

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 action and immediately follows with the credit warning, which is the highest-value information. It is somewhat run-on in the later clauses (concurrency, polling, and the no-restart rule all packed into one long sentence), but no sentence is wasted.

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

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

With no output schema, the description still explains the interim {status:'running'} shape, the partial-completion stop behavior, and the follow-up tool. It does not describe what a successful response contains (e.g., which assets got images), which leaves a small gap for a credit-spending mutation.

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

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

Schema coverage is 100%, so asset_ids, price_only, and project_id are already fully documented in the schema. The description reinforces the cost implication of omitting asset_ids ('one image each') but adds no syntax or format detail, and user_request is not mentioned in the description at all despite being an unusual verbatim-quoting requirement. 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 ('draw the images of the assets') and narrows the scope to assets that need one or a supplied asset_ids list. An agent can distinguish it from generic siblings like render_image or story_set_asset_image because it is explicitly scoped to a project's cast/product/place assets.

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 alternatives ('use price_only to quote'), sequencing guidance ('Follow them with cinematic_ads_get_project'), and failure handling ('when too many are being made at once it stops... call again later'). It also states the polling rule and the prohibition on restarting a running step, which is exactly the kind of routing an agent needs.

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

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

Discloses behaviors the annotations don't: that credits are consumed, that the operation takes several minutes, that long steps return {status:'running'} after roughly a minute while continuing server-side, and the polling/anti-duplicate protocol. This is exactly the operational context coordinates a mutation tool needs.

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

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

The cost warning and the polling protocol are front-loaded and every clause carries operational weight. It is dense and reads as one long block, but there is no filler.

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

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

For a long-running, credit-spending mutation with no output schema, the description supplies the cost, duration, interim return shape, and completion signal. The only gap is what a successful (non-running) return looks like, but the get_project handoff largely covers 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 100%, so the baseline is 3, but the description adds real semantic value for price_only ('start nothing, spend nothing') by tying it to the credit-cost warning. user_request is left to the schema, which documents it 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 the specific verb and resource ('make the video') and scopes it to 'every part that is not finished yet', which distinguishes it from make_images and export. 'Remake' is slightly fuzzy but the rest of the sentence pins the intent down.

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

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

Explicitly tells the agent to use price_only for quoting rather than starting a render, names cinematic_ads_get_project as the polling tool, gives the completion condition (production.done), and warns never to restart a running step. This covers when to use, when not to, and which sibling to use instead.

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 give readOnlyHint=false, non-idempotent, non-destructive, but the description adds the decisive context: it SPENDS CREDITS, produces proposals only, and does not mutate assets. The 'small AI step' cost warning and the non-mutating guarantee are exactly the behavioral facts an agent needs and the annotations alone would not convey.

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

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

Front-loads the core transformation, then immediately the cost warning, then the non-mutation guarantee and follow-up tool. Every clause carries information; no filler.

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

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

No output schema exists, so the description carries the return-value burden; it conveys that the result is 'proposed changes' and that the agent must apply them, which is sufficient to drive the workflow. It stops short of describing the proposal payload shape, a minor gap for a 3-param tool.

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

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

Schema coverage is 67%, with project_id and asset_ids documented but instruction undocumented. The description compensates by showing concrete instruction examples ('make the mother younger'), clarifying what the free-text parameter should contain. It does not clarify the asset_ids scoping, leaving a small 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 ('turn a plain-language request into proposed changes to the project's assets') with two concrete examples, and distinguishes itself from cinematic_ads_update_asset, which applies the changes. An agent can tell it apart from its siblings without opening any schema.

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

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

Explicitly defines the when and the what-next: it proposes and changes nothing, cinematic_ads_update_asset applies the accepted proposals, then cinematic_ads_make_images redraws. The alternative tools are named rather than left to inference.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, and the description reinforces the destructive overwrite with 'replacing one of the same name.' It goes beyond annotations by describing exactly what is persisted (original ad, analysis, cast, places, images, modes, descriptions) and the downstream effect that new projects skip analysis. It doesn't cover permissions or error behavior, but the added context is substantial.

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

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

The purpose is front-loaded, and the remaining clauses add useful detail about lifecycle and exclusions. The single long sentence with parenthetical lists is dense and slightly run-on, but every clause carries information relevant to correct use.

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

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

For a two-parameter mutation tool with annotations covering safety and no output schema, the description covers what is saved, what is replaced, and the effect on new projects. It lacks explicit mention of a return value or template identifier, which would help an agent chain calls, but overall it is complete enough to invoke correctly.

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

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

Schema description coverage is 100%, and both parameters (name and project_id) are fully documented in the schema. The description does not elaborate on parameter meaning or formatting beyond what the schema already provides, so it adds no extra value here. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: saving a project's settings and brand kit as a template. It enumerates the saved contents and clarifies the replacement behavior, which distinguishes it from a simple creation tool. It does not explicitly name sibling alternatives like apply_template or duplicate_project, keeping it from a 5.

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

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

It provides a clear usage context: once the project is analysed, the template retains the original ad, analysis, cast, and places so new projects skip analysis. The example use case (keeping one person's image while changing another's) and the exclusions ('Never a clip take or a final video') give practical guidance. It stops short of explicitly stating when to prefer this over apply_template or clone_template.

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

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=false) by disclosing the concrete consequence: replacing clears the previous analysis and clip plan. It also documents input limits (1s–3min, ≤300MB), cost (free), and async behavior ({status:'running'} after ~a minute, server keeps working), which an agent needs to avoid duplicate calls.

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, constraints, then sequencing/polling guidance in order of importance. Every sentence carries weight, though the long-run/polling guidance is somewhat generic boilerplate that could be pushed to a shared guide.

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

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

With no output schema, the description still covers the return shape ({status:'running'}), the async lifecycle, the follow-up tool, and the destructive side effect. Nothing needed to invoke or chain this 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% and both params are documented in the schema, so the baseline is 3. The description nonetheless adds real semantic value the schema lacks: accepted media formats, duration bounds, size cap, and the requirement that the URL be public https.

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

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

States a precise verb+resource ('Load (or replace) the original ad of a project') plus the accepted input forms (public https URL, MP4/MOV). It is clearly distinguishable from siblings like upload_asset and cinematic_ads_create_project, and names the natural follow-up step.

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 sequencing: 'Then call cinematic_ads_analyze' for the next step, 'poll cinematic_ads_get_project' while a long step runs, and 'never start the same step again while it runs.' It also flags the operation as free and describes the replace-vs-load semantics, leaving little to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds the meaningful consequence (the moment returns to its prior state) and the required follow-up export step, plus a 'Free' cost note. It does not cover permissions or rate limits, but the state-change effect is well disclosed.

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

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

Three tight sentences, front-loaded with the action and effect, then the follow-up step and cost note. No filler.

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

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

For a two-parameter mutation with full schema coverage and no output schema, the description covers effect, follow-up, and cost. Only permissions/error behavior is left implicit.

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

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

Schema description coverage is 100%, so both fix_id and project_id are already documented with their sources; the description's mention of 'an id from production.fixes' restates the schema rather than adding format or lookup detail.

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

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

Names a specific verb (undo) plus the resource (one fix of a moment) and clarifies the resulting state ('that moment goes back to how it was'). It is clearly distinguishable from cinematic_ads_fix_moment, its natural counterpart.

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?

States the use case and tells the agent to run cinematic_ads_export afterward to rebuild the final video without the fix. It lacks an explicit 'when not to use' or a named alternative for reverting in bulk, so it falls just short of a 5.

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

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

Annotations already declare destructive=true and idempotent=true, but the description adds concrete consequence: changing the image or look 'sends the clips that show it back to be made again,' which tells the agent exactly what the destructive action triggers. It also discloses cost ('Free'), which no annotation covers. Auth/permission requirements remain unstated.

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 editable fields, then the mode definitions, then the side-effect warning. Dense but every sentence carries information; the parenthetical examples are slightly loose but earn their 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 mutation tool with no output schema and partial schema coverage, the description covers field semantics, the mode enum, cost, and the re-render side effect. Missing only auth/permission context and constraint details, which is minor.

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

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

Schema coverage is only 33% (asset_id and image_url documented), so the description must compensate, and it does by explaining all three mode enum values (keep/new/upload) and how upload is set automatically with image_url. It also names the other editable fields (name, description, voice), though maxLength constraints are left to the schema.

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

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

States a specific verb (Edit) and resource (one asset, with examples: character, product, place, mascot) and enumerates the editable fields. The word 'asset' implicitly separates it from siblings like cinematic_ads_update_clip and cinematic_ads_update_project, though no sibling is named 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?

Usage is implied by the resource scope ('Edit one asset') and by the mode breakdown, which helps an agent pick a path. However, there is no explicit when-to-use vs the clip/project update siblings, nor any stated prerequisites beyond the mode semantics.

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

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

Annotations cover the safety profile (not read-only, idempotent, non-destructive), so the bar is lower, and the description adds genuinely new behavioral facts: the operation is 'Free' (no credit cost) and screen_picks accepts sentinel values (null = none, 'auto' = let the build choose). It stops short of saying what happens to shots not listed in screen_picks.

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

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

One sentence, front-loaded with the action, with parenthetical detail rather than extra sentences. No wasted wording and the sentinel semantics are packed inline where they are needed.

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

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

For a mutation tool with no output schema and a nested object parameter, the description covers both edit modes and their value semantics adequately; no return-value explanation is required since no output schema exists. It omits failure/permission behavior, but that is a minor gap given the annotation coverage.

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 only 33% (only clip_id documented), so the description must compensate, and it does: asset_ids is flagged as ordered, and screen_picks is fully decoded as a shot-id → screen-url map with null and 'auto' semantics that the schema's generic additionalProperties does not convey. Minor gaps remain (interaction between the two params, the 12-item cap lives only in the schema).

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

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

States a specific verb-resource pair ('Change which assets a clip uses' / 'which app screen shows in each shot') and enumerates the two modifiable aspects, which distinguishes it from siblings like cinematic_ads_update_asset and cinematic_ads_update_project.

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

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

The two supported modes (asset_ids vs screen_picks) are implied as the alternatives, but the description never states when to prefer this tool over cinematic_ads_update_asset or when each mode is appropriate. Usage must be inferred.

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 supply destructiveHint, idempotentHint and openWorldHint, so the description only needs to add timing and lifecycle context — and it does: cost ('Free'), refusal during analysis, and the point of no return on the video model. It does not clarify what happens to omitted fields or to already-generated clips, which is the remaining unknown for a destructive update.

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, front-loaded with purpose, then cost, then constraints — a sensible order with no filler. The long parenthetical enumerating brand-kit fields is slightly heavy but each item earns its place by defining the mutation's scope.

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

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

For a destructive, multi-field update tool with no output schema and annotations already carrying safety hints, the description supplies the missing operational context: cost, the analysis lock, and the irreversibility of the video model. An agent has enough to decide when to call it and what to warn the user about.

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

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

Schema description coverage is 63% and the description largely restates the schema's property list, though it does usefully frame the brand-kit fields as a single group (app name, CTA, icon, mascot, end card, frames, screens, brief). Parameters not covered by either source — notably 'pronunciation' and 'dialogue' — get no help here. Adequate but not additive beyond the schema.

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

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

Opens with a specific verb+resource ('Change a Cinematic Ads project's settings') and then enumerates exactly which settings, including the full brand kit. An agent can distinguish this project-level mutation from siblings like cinematic_ads_update_asset or cinematic_ads_update_clip 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 concrete when-not conditions: refused while an analysis runs, and the video model is frozen once part of the video is made, with the explicit alternative 'start a new project for another model'. No routing to the update_asset/update_clip siblings for their respective scopes, which is the only gap.

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

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

The description adds substantial behavior beyond the annotations: it is a credit-spending operation, it is asynchronous ("Returns a job id immediately"), and the job completes even if unobserved. That last point is critical for an agent deciding whether it must poll, and none of it is derivable from readOnlyHint=false / idempotentHint=false.

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

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

Four short sentences, all front-loaded with the most consequential fact (credit spend) second. Nothing is redundant or 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 10-param, nested-object, async mutation tool with no output schema, the description covers the essentials: cost, immediate return value, follow-up tool, and guaranteed completion. It does not state that repeated calls spend credits again, nor where a templateId comes from, but the schema fills most remaining gaps.

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

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

Schema description coverage is 90%, so the schema already carries nearly all parameter meaning (overrides, intent, workspace scoping, user_request verbatim rules). The description contributes nothing parameter-specific, so the baseline 3 applies.

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

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

"Clone a template into a real video generation" states a specific verb (clone) and resource (template → video generation), which separates it from preview/apply-style siblings. It never explicitly names which sibling to use instead (e.g. cinematic_ads_apply_template or preview_render), so it falls just short of full sibling differentiation.

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

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

Usage is implied by "SPENDS CREDITS" and the hand-off instruction "call get_generation to follow it," which tells the agent the correct follow-up tool. However, there is no explicit statement of when to choose this over render_video, cinematic_ads_apply_template, or the preview tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds that the return includes both a status and a result URL, which is useful context, but says nothing about status values, polling cadence, or failure states.

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

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

A single compact sentence, front-loaded with the returned data. It is efficient, though its brevity comes at the cost of the missing parameter and behavioral detail noted elsewhere.

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 return values; it partially does (status + result URL) but omits the set of possible status values and how to poll. For a one-parameter status-check tool this is minimally adequate but leaves gaps.

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

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

Schema description coverage is 0%, so the description carries the full burden for the single jobId parameter, yet it never names or explains it. 'A generation you created' loosely implies jobId identifies the generation, but no format, source, or validation detail is provided.

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

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

The description clearly identifies the resource (a generation you created) and what it returns (status and result URL), letting an agent tell it apart from the render_* creation tools and preview_* tools. It lacks an explicit verb, but the intent — retrieve status/result — 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?

The phrase 'a generation you created' implies the natural workflow (call after a render_* tool), but there is no explicit statement of when to use this versus preview_generation or the render_* siblings, and no mention of prerequisites like polling.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavioral context the annotations cannot convey: the generation prompt is deliberately omitted from the response, which prevents an agent from assuming a missing field is an error.

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. The primary action is front-loaded and the caveat about the missing prompt plus the redirect follow immediately.

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 discloses that the generation prompt is absent from the returned template, which is the key expectation-setting detail. It does not describe what fields are returned or how an unknown id behaves, but for a single-parameter read tool this is close to complete.

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

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

There is one parameter with 0% schema description coverage, so the description carries the burden. 'By id' merely restates the parameter name and adds no format, source, or lookup guidance for templateId. This is the minimum viable level given the coverage gap.

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

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

States a specific verb and resource (get one template by id), which is clear enough to distinguish from list/search siblings. It does not explicitly contrast with search_templates or browse_library, but it does name clone_template as the alternative path.

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

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

Provides an explicit conditional: if you want the generation prompt, send an intent to clone_template instead. That routes the agent away from this tool for the cloning use case. It stops short of stating when-not to fetch a template at all, but the alternative routing is concrete.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds far more: authorization paths and their scope differences, cost ("Free"), a 60-calls-per-minute rate limit per key or person, timezone and 366-day range bounds, cursor paging via meta.next_cursor, and precise semantics for null vs. 0 ("no sample ⇒ avg / p50 / p90 null, never 0"). Member-level row visibility and zero-filled rows for people who did nothing are disclosed up front.

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?

Nearly every clause carries real information, and the purpose is front-loaded in the first sentence. But the body is one enormous run-on paragraph mixing auth, grouping, row schema, metrics, filters, paging, and CSV export, with no headers or line breaks; an agent must parse ~700 dense words to find any single fact.

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 19 parameters and no output schema, the description carries the full burden of describing the return shape, and it does: it enumerates group fields and each metric (attempts, net_credits, reserved_credits, cost_effective_usd, the three latency percentiles with their n and n_approximate semantics) plus the approved_creatives caveat tied to meta.missing_fields. Nothing essential for correct invocation or interpretation appears to be missing.

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

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

Schema coverage is 100%, yet the description still adds meaning the schema cannot: group_by is defined operationally (week starts Monday, month as YYYY-MM, cuts made in Asia/Ho_Chi_Minh, none = a single row), from/to are clarified as first-day-included and day-after-last-excluded with a 30-day default, and compare_previous is explained as producing rows tagged window = "previous". It also explains that filters reduce the runs being summed, not just the returned rows.

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?

"Workspace Analytics & Billing: the RUNS of ONE Enterprise workspace ... added up per group" states a specific verb (aggregate), resource (generation runs), and scope (single workspace), and immediately distinguishes itself from list_generation_events by asserting the rows sum to the same totals. An agent can tell exactly what this tool returns 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?

Explicitly names two alternatives and the conditions that separate them: the same underlying runs as list_generation_events but pre-aggregated, and a different view from list_credit_transactions with the direct instruction "do not mix the two." It also states prerequisites (reporting key or Owner/Admin/Member sign-in) and the Member limitation to own runs.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, and the description goes well beyond them: per-role data visibility differences, auth key requirements, a 60 calls/minute rate limit, 'free' cost, null-never-zero pricing behavior, and Asia/Ho_Chi_Minh time semantics. Even what is not counted as cost (allocate/reclaim) is disclosed.

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

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

The gist is front-loaded in sentence one and every subsequent sentence carries real information, but the middle block is a dense run of field definitions that is hard to scan and would be better served by an output schema. The CSV endpoint note at the end is a useful, compact closer.

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 documenting the response and does so exhaustively: data.granted, sources, pool_available_credits, wallets, held/used credits, price formulas, missing_fields, and timestamp fields. Nothing an agent needs to interpret the result 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% and the workspace_id description already explains the key-vs-membership scoping, so the description adds little new meaning for the single parameter. Its role-based visibility notes are behavioral context rather than parameter semantics, so the baseline 3 applies.

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

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

The first sentence names a specific verb and resource with scope: the budget of ONE Enterprise workspace, read as of now rather than over a date range. The 'read now (not a date range)' clause explicitly separates it from time-series siblings like get_usage_summary or list_credit_transactions without requiring a schema look.

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

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

It states the access conditions clearly: a wdr_report_ key made by the workspace Owner, or sign-in as Owner/Admin (whole workspace) versus Member (only your own numbers). What is missing is an explicit pointer to sibling tools when a date-ranged or multi-workspace view is wanted.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, and the description adds substantial context beyond them: the 60-calls-per-minute rate limit, that the call is free, the 366-day range cap, cursor pagination via meta.next_cursor, and the immutability guarantee that ledger rows never change so updated_since cannot produce duplicates. It also documents that spend_state reflects current state rather than the state at posting, which is a non-obvious behavior an agent would otherwise get wrong.

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 text is dense and front-loaded, with no marketing filler, and the field enumeration earns its place because no output schema exists. The main weakness is structural: it is one large unstructured paragraph with no line breaks or headings, so the paging and sync rules are buried mid-block. Labeled segments ('Range:', 'Paging:', 'Sync:', 'CSV:') help but do not fully offset the wall-of-text effect.

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 six-parameter read tool with no output schema, the description covers everything an agent needs: authentication paths, ordering and timezone, every row field including the refund_of_ref back-reference and held_credits, the cost-accounting formula that reconciles with the Usage page, pagination, incremental sync, and a CSV escape hatch with its header-based cursor. Nothing material about calling it correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaning beyond the schema: it clarifies that `to` is exclusive and pairs with `from` under a shared 366-day cap, that the default window is the last 30 days including today, and that `cursor` must be replayed with the same range. The `updated_since` guidance, storing the last posted_at, is the most valuable addition because it defines a sync pattern rather than restating the field.

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

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

The description opens with a precise verb-plus-resource statement: it returns the credit ledger of one Enterprise workspace, one row per credit movement, ordered oldest-first by posting day. It goes further than the name by defining scope ('ONE Enterprise workspace'), grain ('one row per credit movement'), and sort ('oldest first', Asia/Ho_Chi_Minh), which distinguishes it from summary-level siblings such as get_usage_summary and get_workspace_budget.

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 context is explicit on prerequisites and permissions: a wdr_report_ key or Owner/Admin/Member sign-in, with Members limited to their own wallet. It also explains which rows count as cost ('Net credits used = −Σ credits of spend and refund rows') and notes that allocate/reclaim are never cost, which steers correct interpretation. It never explicitly names an alternative tool or says when not to use it, so it falls short of full 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new operational facts: it is free, consumes no credits, makes no provider call, and the prompt is baked in server-side. That is exactly the kind of cost/side-effect context an agent needs before invoking.

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

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

Three tight sentences, front-loaded with what is returned, then the no-prompt constraint, then cost behavior. Every clause carries information; nothing is filler.

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

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

With no output schema and no parameters, the description must explain return contents, which it does (demo clip, poster image, credit price at two durations), and it covers cost and side effects. 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is required and explains that only a photo and duration matter downstream, adding mild clarifying value.

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

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

States a precise verb+resource (list the 20 one-photo video effects) and enumerates the returned fields (demo clip, poster image, credit price for 5s and 10s). It also distinguishes itself from the sibling render_effect by noting there is no prompt to write, only a photo and a duration.

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

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

"Call this before render_effect" gives explicit sequencing guidance and the 'no prompt to write' note clarifies the intended workflow. It does not, however, address when not to use it or how it relates to the other browse/list siblings (browse_library, list_models, get_template).

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

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

Beyond the readOnly/idempotent annotations, it discloses cost (free), throttling (60 calls/minute per key or person), auth paths and scope limits, null-vs-zero time semantics, that preview_url is publicly readable, that 'there is no cancelled' state, that retries are separate runs, and that meta.missing_fields explains gaps. These are exactly the operational facts an agent needs before calling.

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

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

The purpose and auth are front-loaded, but the 'Each row of data' section is a single enormous run-on enumeration that is hard to scan, and paging/limit rules are restated from the schema. Nearly every detail is substantive, but the lack of structure (no breaks by concern) hurts usability.

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 18 parameters, no output schema, and complex billing semantics, the description carries the full burden of documenting the returned row shape, and it does so field by field, including derived cost figures and time-delta definitions. Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema coverage is 100%, so the schema already carries baseline meaning, but the description adds real value: bucket boundary inclusivity (15 is 0-15, 15.07 is 15-30), day attribution by finish time (submit time for running runs), from inclusive / to exclusive, and that cursor must be sent with the same range and filters. Some schema-level details (limit bounds, cursor definition) are simply repeated rather than extended.

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

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

The opening sentence names a specific verb (list), a specific resource (generation runs of one Enterprise workspace), the grain (one row per run), and the ordering (oldest first). It also crisply defines what a 'run' is, including retries and out-of-job steps, so the agent cannot confuse it with get_usage_summary or list_credit_transactions.

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

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

It states prerequisites precisely (workspace reporting key from an Owner, or Owner/Admin/Member sign-in with Member limited to own runs), the default range, the 366-day cap, paging via meta.next_cursor, incremental sync via updated_since, and rate limits. What it lacks is explicit routing language naming a sibling (e.g. 'use get_usage_summary for totals'), leaving the Usage-page reconciliation only implied.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds useful non-structured context: 'Free', plus the fact that rows carry `prompt` and `requires` flags that must both be checked before rendering. It doesn't discuss pagination or result size, but the call-before-render contract is the behavior that actually matters here.

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

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

Four sentences, densely packed and front-loaded: purpose first, then parameter hint, then the usage imperative, then the row-contract warning. Slightly overstuffed with dashes and parentheticals, but 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?

With no output schema, the description must carry the return shape, and it does name the key row fields (`prompt`, `requires`) and the capability categories. It stops short of describing the full row structure (model names/ids, exact field names), which an agent would still have to discover empirically.

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

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

Schema coverage is 100% and the single `kind` enum is already documented with its default in the schema. 'Pass kind to switch between video, image and audio' restates the enum rather than adding format or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb+resource ('list the models you can generate with') and immediately enumerates what each row contains: reference image/video/audio counts and allowed resolution/duration/aspect values. An agent can distinguish this discovery tool from the render_* siblings 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 an explicit sequencing rule against the alternatives: 'Call this before any render so you pick settings that exist instead of guessing.' It also names the alternative family (render tools) and the condition (before calling a render tool) that selects it.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the rate limit (60 calls per minute per key or person), that the call is free, that output is uniform across readers, that metered AI steps such as Cinematic Ads analysis and export are excluded, and how to derive real per-run cost via meta.cost_basis.effective_cents_per_credit. It also documents the CSV alternate endpoint.

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 sentence front-loads what the tool is and the price-option granularity, and every clause afterwards (auth, rate limit, field meanings, cost math, CSV) carries information. It is dense and delivered as one long block rather than structured sections, which makes the output-field enumeration harder to scan than a list would be.

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

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

With no output schema, the description takes on the burden of documenting the return shape and does so field by field: feature, output_kind, model_id, provider, resolution, with_sound, unit, list_credits_per_unit and list_usd_per_unit, plus the credit-to-dollar conversion. Auth, rate limits and known omissions are all covered, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100% for the single workspace_id parameter, so the baseline is 3. The description adds meaning by tying the id to auth paths ('the workspace the reporting key belongs to, or one you are a member of') and noting that the reporting key must be minted by that workspace's Owner, which clarifies what a valid value looks like.

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 and scope: the workspace's catalogue of sellable services, one row per price option, including feature, model, provider, resolution and unit prices. That distinguishes it from list_models (model catalogue) and get_usage_summary (spend), though it never names those siblings explicitly. An agent can infer the purpose confidently from the field list.

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

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

Prerequisite context is strong: it says a wdr_report_ key or Owner/Admin/Member sign-in is required and that the result is identical for every reader. However it never states when to call this versus list_models, get_usage_summary or get_workspace_budget, and gives no exclusions beyond 'metered AI steps are not listed'. Usage is implied rather than routed.

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

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

The description provides extensive behavioral details beyond the annotations, including the complete return structure (`data` + `meta`), specific meanings for every field (e.g., `status`, `team_history`, `membership_periods`), rate limits (60 calls a minute), and timezone context (Asia/Ho_Chi_Minh).

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 tool description is an extremely dense, multi-paragraph technical specification that is neither concise nor well-structured for an AI agent. It functions more like a reference manual page than a simple tool explanation.

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

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

Given that no output schema is provided, the description is exhaustively complete. It defines every data point returned, including complex nested objects like `membership_periods` and operational constraints like rate limits and time zones.

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

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

Although schema coverage is 100%, the description clarifies the critical context of the `workspace_id`, explaining it must be one tied to the reporting key or one the user specifically owns/is a member of. This context is vital for correct invocation and permission handling.

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

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

The description clearly states the tool's function: listing workspace members. It distinguishes its scope from a standard list by specifying it includes members who have left and those who never ran anything, indicating a deep auditing function.

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

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

While it doesn't name specific alternatives, it defines its use case as a comprehensive, historical report suitable for auditing. This level of scope definition strongly suggests *when* to use it relative to simple member checks.

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

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

Annotations already declare readOnly/idempotent/non-destructive; the description goes further by spelling out the practical consequence — costs nothing, spends no credits, calls no provider — which is the fact that actually determines whether an agent should call it speculatively. It also discloses the return payload keys and a decision rule tied to sufficientCredit, since no output schema exists.

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

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

Four short sentences, front-loaded with the negation of side effects, then ordering guidance, then return values, then the failure branch. Nothing repeats the schema or the annotations.

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

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

For a 9-parameter read-only pricing tool with no output schema, the description covers the no-cost guarantee, the intended call sequence, the returned fields, and the credit-insufficiency action. That is sufficient 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 89%, so the schema already documents avatar, product, overrides, workspace and project in detail. The description adds only the indirect hint that aspect/duration can be previewed, without explaining how overrides affect pricing. 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?

"Price a clone WITHOUT creating it" gives a specific verb (price) and resource (clone) and immediately negates the write behavior, which cleanly separates it from clone_template. The scope is unambiguous to an agent skimming sibling names.

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

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

It names the alternative and the ordering: "Use this before clone_template so the user knows the price and the resulting aspect/duration first." It also states a conditional branch (sufficientCredit false → do not submit, tell the user), which is exactly the when/when-not guidance an agent needs.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantive detail: no credits spent, no provider call, the returned fields (cost, balance, sufficientCredit), and the distinct behavior of transform models that accept no prompt. This is well beyond what the annotations convey.

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

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

Front-loaded with the core price-without-committing statement, then conditional guidance. It is dense with several separate ideas packed in, slightly reducing scannability, but nearly every sentence carries actionable information.

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

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

With no output schema, the description compensates by naming the exact return fields and the decision they drive ('do not submit' when insufficient). It also covers the transform-model edge case that would otherwise cause a wrong 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 100% so the baseline is 3, but the description adds cross-parameter orchestration guidance — read list_models' `prompt` and `requires` fields before choosing which params to pass, and omit `prompt` for prompt:'none' models. It doesn't cover the workspace/run_id scoping nuances, which the schema handles.

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 ('Price a render WITHOUT creating it') and explicitly covers the media scope (video, image, audio). The negative framing immediately distinguishes it from the render_* siblings.

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

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

Explicitly instructs 'Use this before any render_* tool so the user sees the price first' and adds a conditional branch ('if sufficientCredit is false, do not submit, tell the user'). It also names list_models as the prerequisite for transform models, giving a complete call sequence.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and idempotentHint=false. The description still adds real value beyond them: it warns SPENDS CREDITS, that the prompt is sent VERBATIM, that the call returns a job id, and that some models transform rather than generate. This is useful context but the annotation set already carries the mutation/open-world profile, so a 3 is appropriate.

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 it does and the credit warning, then the flow, then the edge case. Every sentence carries actionable information despite the length.

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

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

For a 13-param, costly, open-world generation tool with no output schema, the description covers purpose, cost, prompt fidelity, follow-up step, downstream use, and the transforming-model exception. Nothing critical is missing 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 100%, so the schema documents all 13 params and baseline is 3. The description nevertheless adds selection logic beyond the schema: which models require omitting `prompt`, and that prompt:'none' models need source media instead. It does not explain run_id, project, workspace or user_request semantics, so not a full 5.

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

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

States a specific verb and resource ('Generate audio') and enumerates the concrete subtypes (voice line, sound effect, ambience, music bed), which cleanly separates it from render_image and render_video siblings.

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

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

Explicitly routes the agent: call list_models first and read `prompt`/`requires`, call get_generation to follow the job, pass the resulting URL into render_video. It also carves out the when-not case (prompt:'none' models that transform media and take no prompt).

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

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

Beyond the annotations (which only say non-readonly, non-idempotent), the description discloses the credit cost, that the prompt is fixed server-side, and precisely what preview:true suppresses (no job, no credit spend, no provider call). It also names the three fields returned by the dry run, which is the key behavioral contract for a billing-sensitive 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?

Four sentences, front-loaded with the highest-risk fact (credit spend) in caps, then the fixed-prompt constraint, then the preview escape hatch, then the return contract. Nothing is repeated from the schema verbatim and no sentence is filler.

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

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

With no output schema, it correctly describes the preview return fields — but says nothing about what a paid render returns (job id? how to poll via get_generation/story_get_job?), which is the natural next question after submitting. For an 8-param, credit-spending, open-world tool that is a meaningful remaining gap, though the billing and dry-run guidance is otherwise complete.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real value by scoping the creative inputs to effect/photo/duration and by restating preview's cost semantics in operational terms. It does not clarify run_id, project, workspace, or user_request — those rely entirely on their schema text, and "same rule as render_video" in the schema is a cross-tool dependency the description never resolves.

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?

"Render a one-photo video effect from list_effects — SPENDS CREDITS" gives a specific verb + resource + scope, and immediately distinguishes this from render_video (multi-scene video), render_image (still), and preview_render (generic preview). The source of the `slug` (list_effects) is named in the first sentence.

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

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

It explicitly prescribes the workflow — call with preview:true before any paid render — and gives a hard stop condition: "if `sufficientCredit` is false, do not submit the paid render." It also states what the caller does and does not control ("you only choose the effect, the photo and the duration"), so no when-to-use decision is left to inference.

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

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

Annotations only say it is a non-read-only, open-world, non-idempotent write; the description adds the consequential facts annotations cannot: it SPENDS CREDITS, the prompt is sent VERBATIM with provider flags surviving, and the call is asynchronous (returns a job id, not an image). These are the details most likely to cause a wrong or wasted invocation.

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

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

Front-loads purpose and the credit warning before anything else, then layers the job-id follow-up and model-selection caveat. It is dense and each clause carries information, though the final sentence is long and could be split for faster scanning.

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

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

For a 13-parameter generation tool with no output schema, the description supplies the missing return-value contract (job id → get_generation → finished image shown directly) and the prerequisite discovery step. Nothing an agent needs to avoid a bad call appears 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 cross-tool meaning: `model` must come from list_models and there is no default, and `prompt` must be omitted entirely for prompt:'none' models. The @name-to-@Image1 renumbering and workspace/credit precheck rules live in the schema rather than the description.

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

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

States a specific verb+resource ('Generate an image') with concrete examples of output kinds, and distinguishes itself from siblings render_video, render_audio and get_generation by naming them and their relationship. It also flags that some models transform rather than generate, so an agent understands the full scope of the tool.

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

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

Explicit workflow: call list_models first and read `prompt`/`requires`; for prompt:'none' models omit `prompt` and pass source media instead. It also tells the agent the follow-up path (get_generation) and a downstream use (pass the URL into render_video to build an ad), which is exactly the when-and-with-what guidance an agent needs.

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

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

Goes well beyond the annotations by disclosing that the call SPENDS CREDITS, that it is asynchronous ('Returns a job id immediately; call get_generation to follow it'), and that the prompt is passed VERBATIM with provider flags (--seed, --cf, --wm) surviving. It also warns that some models transform media rather than generate, which changes the call shape materially.

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 cost, then the key verbatim semantic, then the follow-up call, then the routing caveat — a sensible escalation order. Capitalisation is used deliberately for the two facts an agent could get wrong (spending, no-prompt models); no sentence is 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, credit-spending, async tool with no output schema, the description covers the return contract (job id, follow with get_generation), the model-selection prerequisite, and the empty-prompt edge case. 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 schema baseline is already a 3. The description adds real meaning on top: `model` has no default and must come from list_models, and `prompt` must be omitted entirely for 'none' models. It also frames aspect/duration/resolution as list_models-derived rather than free-form, though it does not re-explain the media-reference `name` convention the schema covers.

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

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

Names a specific verb and resource ('render a video') and immediately scopes it as the raw-prompt, verbatim path, explicitly contrasting it with 'a template clone'. That lets an agent separate it from clone_template, render_image, and cinematic_ads_make_video 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 routing: use this when you want exact control rather than a template; call list_models first and read `prompt`/`requires`; call get_generation to follow the job. It also states a when-not case — prompt:'none' models take no prompt and need source media instead.

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

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

Annotations already declare this as a safe, idempotent, closed-world read, so the description need not re-establish that. It adds some value by disclosing partial return content ('aspect and duration'), but with no output schema the description should carry more of the return-shape burden (IDs, titles, pagination, rank/order) than it does.

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

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

Three short sentences, front-loaded with purpose, then usage, then return shape. Each sentence carries distinct information and there is no filler or restatement of the tool name.

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

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

With no output schema, the description must cover return values, and it partially does. However, for a 4-param search tool with no required params and half the schema undescribed, an agent still lacks guidance on query semantics, defaults, and result volume.

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%, and the description says nothing about any of the four parameters. The bare 'limit' and 'industry' params are documented nowhere, and the description does not compensate by explaining search matching, format filtering, or result count behavior.

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

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

States a specific verb and resource ('Search the Wandura ad-template catalog'), and clarifies its role relative to clone_template ('Use this first to find a template to clone'). It does not distinguish itself from other lookup siblings such as browse_library or get_template, so an agent must still infer the boundary.

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

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

Gives a clear ordering cue ('use this first') tied to a downstream action (cloning), which is real when-to-use guidance. It stops short of naming alternatives or exclusions, so it never says when to prefer browse_library or get_template instead.

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

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

Goes well beyond the annotations, which only say non-read-only, idempotent, non-destructive. The description discloses the auth model and refused credential types, the side effect of auto-creating a team when no active team matches, the retroactive-vs-forward-only semantics of first and subsequent team changes, and that every assignment is audit-logged.

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

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

Front-loaded with the action, then prerequisites, then edge-case semantics, then return shape — a sensible order with no filler sentences. It is dense and reads as one long block, which slightly hurts scanability, but every clause carries information an agent needs.

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

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

There is no output schema, and the description compensates by naming the returned fields and explaining changed=false. Combined with the auth requirements, team-creation side effect, report-timing semantics, and audit logging, nothing material is missing for a 3-parameter mutation tool.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: the team is identified by name and a non-matching name creates a new team, and user_id must be obtained via list_workspace_members. It does not restate the length or case-insensitivity rules, which the schema already covers.

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

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

States a specific verb and resource: 'Put a member of an Enterprise workspace in a team', and immediately gives concrete examples of teams (Learn AI, Photo, Fitness) plus the reporting purpose. It is unmistakable against siblings like list_workspace_members, which it names as the id-lookup companion.

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 preconditions (Owner or Admin, own Wandura OAuth sign-in with teams:write) and explicitly rules out API keys and workspace reporting keys, which is effectively a when-not. It also routes the agent to list_workspace_members for user ids. No guidance on what to do when the assignment should be removed or reassigned, so it falls short of a full when/when-not/alternatives treatment.

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

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

Annotations only declare the generic mutation profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true). The description adds the operation is free, that it is asynchronous with an observable 'splitting' → 'ready' state transition taking one to two minutes, and the concrete polling instruction — all behavior an agent cannot get from structured fields.

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

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

Purpose is front-loaded in the first sentence, then the three input modes and the polling loop are delivered compactly. Every clause carries information — the cost note, the state machine, and the scene-granularity warning all earn their 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, and the description compensates by describing the returned `state` field and how to advance past 'splitting'. It omits what `logline` is for and does not state the result of failure or duplicate-title cases, but for an async append tool it is nearly complete.

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

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

With 60% schema coverage, the description carries real weight: it explains what `script` does downstream (saved and split into scenes), what `scenes` means (pre-split, ready immediately), and reinforces mutual exclusivity. It leaves `logline` unexplained (the schema leaves it bare too), which is the only 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+placement: 'Add an episode to the end of a Story mode project.' This cleanly separates it from siblings like story_update_script or story_create_project, and the appended-at-the-end semantics are 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 routing for each input mode — send `script` to have it split in the background, send `scenes` if already split, send neither for an empty episode — and tells the agent to poll with story_get_episode until state is 'ready'. It does not name a sibling alternative for editing existing episodes (e.g. story_update_script), so it falls just short of full when/when-not coverage.

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

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

Goes beyond annotations by disclosing that the action is free and reversible, and that a null job_id clears the selection. Annotations already cover non-destructiveness and idempotency, so this is additive context rather than the full burden, but it still omits what happens to previously selected takes or any permission requirements.

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

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

A single tightly packed sentence plus a short clause; the core action is front-loaded and every phrase (UI equivalence, cost, reversibility, clearing) 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 only two simple parameters, no output schema, and annotations covering the safety profile, the description supplies almost everything an agent needs to invoke it correctly. Minor gap: no mention of what the tool returns or any error/edge conditions around an invalid job_id.

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 explains the null-clearing semantics of job_id, which is genuinely valuable, but says nothing about scene_id beyond its role being inferable from the name, leaving half the parameters underspecified.

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

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

States a precise verb+resource: choosing which finished video take of a scene goes into the episode, and anchors it to the equivalent UI action ('Use in episode' in Wandura). This clearly distinguishes it from sibling tools like story_set_scene_assets or story_refresh_scene, which operate on different aspects of a scene.

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

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

Implies the context of use (selecting the take that goes into the episode) and gives the clearing case explicitly ('pass job_id: null to clear'). It does not name alternative tools or state when-not to use it, so it falls short of the 5 bar.

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

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

Annotations already declare write (readOnlyHint=false), non-idempotent, non-destructive, so the description's job is to add context — and it does: the operation is free, image_url must be a URL from upload_asset, a duplicate name is refused, and an asset without image_url has no picture until priced or set. It stops short of describing what is returned or whether the project must already exist, but this is well above what the annotations carry.

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

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

Front-loaded with the purpose, then cost, then the two image paths, then the error case — a sensible ordering. Fairly dense with clauses, but every sentence carries an operative fact; nothing is padding.

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

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

With no output schema, the description still covers cost, idempotency-adjacent behavior, parameter provenance, and the downstream alternatives for getting an image. The remaining gap is what a successful create yields (e.g. the new asset id) and any project-state prerequisite.

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%, so the description must compensate, and it does for the highest-risk parameter: image_url's provenance (must come from upload_asset) and immediate effect. It also enumerates the three kind values inline. identity and description are left to the schema, and project_id/name receive no elaboration.

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 (Add) and resource (character/background/prop) scoped to Story mode projects, and the clause 'for ones the script breakdown did not find' separates it from story_update_asset and the script-derived asset flow. An agent can pick this out from siblings 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?

Explicit routing: use with image_url for an existing reference picture, without it price the drawing via story_quote, or set an image later with story_set_asset_image. It also names the exclusion — a duplicate name is refused and you should edit that asset instead — which is exactly the when-not guidance an agent needs.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, but the description adds non-obvious behavior: the call is free/no-credits, the breakdown is asynchronous and takes minutes, and downstream paid steps require a human approval gate. It does not say what state the project is left in on partial failure or any rate limit, so it stops 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 core action and cost, then the timing caveat, then the pipeline, then the payment rule. Every sentence carries information, though the pipeline and payment sentences make it slightly long for a creation 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 correctly points to story_get_project for retrieving results and explains the async delay so the agent does not expect an immediate payload. Combined with annotations and a mostly-covered schema, an agent has enough to invoke it correctly; minor gaps remain around failure/partial-state behavior.

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 67%, so the schema already documents script_text, collection_id, output_language, and the episode-targeting options. The description only implicitly maps 'screenplay or story text' to script_text and adds nothing on collection_id, output_language, or the mutual exclusivity of the two target_episode_* parameters. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a Wandura Story mode project from a screenplay or story text') plus the immediate side effect ('start the script breakdown'), and names the concrete artifacts produced (characters, places, props, episodes, scenes). The 'Story mode' qualifier cleanly separates it from cinematic_ads_create_project among the siblings.

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

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

Gives an explicit next step ('The breakdown takes a few minutes; then call story_get_project') and lays out the whole Story-mode pipeline (create → wait → asset pictures → storyboards → scene videos → takes). It also flags the paid path ('story_quote → the person approves in Wandura → story_run'), so an agent knows what to call and in what order after this one.

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

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

Goes well beyond the annotations: discloses cost ('Free'), that execution is asynchronous/background with a concrete polling cadence, the exact failure mode and its payload (missing scenes are returned), and the implicit take-selection side effect. The idempotentHint and destructiveHint=false are consistent with the described behavior of assembling without altering takes.

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

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

Four dense sentences ordered by importance: what it does, cost, prerequisite/failure, then the async follow-up. No filler and nothing repeated from the schema.

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

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

With no output schema, the description still tells the agent where the result appears (poll story_get_export, then share the url) and how failure looks. Minor gap: it does not describe the immediate return payload of this call (e.g. a job/export id to poll with).

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

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

Schema coverage is only 33% — user_request is thoroughly documented in the schema, but project_id and episode_id carry no schema descriptions. The description references 'episode' contextually but adds no format, ownership, or relationship detail for either UUID parameter, so it does not fully compensate for the coverage gap.

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

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

States a specific verb and resource (assemble an episode into one video) plus the exact composition rule: chosen take of every scene, in order, with the episode's music. This is clearly distinguishable from story_get_export (status polling) and from scene-level render tools in the sibling list.

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

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

Gives the precondition explicitly (every scene needs a finished chosen take), tells what happens when it is unmet (refused with the list of missing scenes), names story_get_episode as the way to inspect them, and explains the automatic first-take selection. It also prescribes the follow-up loop: poll story_get_export every 20-30s until state is 'done'.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds genuinely new context: cost ('Free') and a detailed enumeration of the returned structure, including the non-obvious 'storyboard state (and whether it is outdated)' and take-status semantics.

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

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

Two dense sentences with the core read scope front-loaded and the sourcing hint trailing. Every clause adds information; nothing is redundant filler.

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

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

With no output schema, the description must convey the return shape, and it does so concretely (scenes as clips with cast/assets/storyboard/takes/chosen take). Combined with annotations covering safety and the sibling pointer for ids, an agent has what it needs to call it correctly.

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

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

Schema coverage is 0% and neither param is documented in the schema, so the description carries the burden. It explains where episode_id comes from (story_get_project) but says nothing about project_id's origin or the uuid format, leaving half the parameters under-specified.

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

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

States a specific verb (Read) and resource (one episode of a Story mode project) and enumerates the returned contents (scenes, cast, reference assets, storyboard state, video takes, chosen take). This cleanly separates it from story_get_project, story_list_projects, and story_get_script, which target different resources.

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 a prerequisite chain: episode ids must come from story_get_project, and notes the call is free. It gives clear context for when to use it but does not name an exclusion or alternative (e.g., when to prefer story_get_project alone).

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new operational context: the call is free, the download url expires, and re-reading yields a fresh url. That is real behavioral value beyond the structured fields.

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

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

Two tight sentences: the core purpose and state enumeration come first, followed by the cost and url-expiry caveat. No filler or restatement of the tool name.

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

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

For a small polling tool with no output schema, the description covers the return states, the costly/cheap aspect, and the url lifetime. The main omission is that it never links the polling flow to the sibling that starts the export, but nothing needed to invoke the call 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 0% and the description never mentions project_id or episode_id, so it contributes nothing about the two required parameters. The names are largely self-explanatory UUIDs, which keeps this from being a 1, but for a 0%-coverage schema the description should have identified which episode is being polled.

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: retrieve the status of the latest assembled video for an episode, and enumerates every possible state (none, assembling, done with url, error). An agent can distinguish this polling tool from story_export_episode, which presumably triggers the assembly.

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

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

Usage is implied rather than stated: it is a status reader you poll, and 'read again for a fresh one' hints at repeat invocation. There is no explicit statement that it should be called after story_export_episode, nor any when-not guidance against alternatives such as story_get_job.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered; the description adds genuinely new behavior: no cost ('Free'), latency expectation for video jobs, and the polling cadence. It even notes that 'done' carries a url, hinting at the return payload for a tool with no output schema. Exact error payload shape is the only omission.

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

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

Two tight sentences, front-loaded with what the tool returns before the practical polling advice. Every clause carries information (states, cost, latency, cadence) and nothing is repeated from the annotations or schema.

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

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

For a single-parameter read-only status poll with no output schema, the description covers the status vocabulary, the presence of a url on completion, cost, and timing. Only the structure of the 'error' state is unexplained, which is a minor gap in an otherwise sufficient definition.

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

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

Schema description coverage is 0% for the single job_id parameter, but the schema itself supplies the uuid format. The description only implies that the id refers to 'one Story mode job' and adds no syntax, sourcing, or format detail beyond that, so it neither compensates for nor worsens the sparse 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?

Names a specific verb+resource ('Status of one Story mode job'), scopes it to Story mode, and enumerates the possible job kinds (asset picture, storyboard, scene video) and states (queued/running/done/error). An agent can distinguish this from story_run, story_get_export, or story_get_episode 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 concrete operational guidance — it is free, videos take a few minutes, and the agent should poll every 15-30 seconds — which tells it exactly when and how often to call this after kicking off a job. It does not name alternatives 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 already establish readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral value beyond them: the full next_step state machine (wait_for_script_breakdown through done), which tells the agent this tool drives workflow routing, and "Free" which discloses there is no generation cost. It does not describe rate limits or auth, but those are minor here.

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

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

Front-loaded with the entry-point cue, then a dense enumeration of returned fields and an inline next_step enum. No filler sentences; every clause carries information.

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

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

With no output schema, the description compensates well by listing the returned progress signals, the next_step values, and episode ids. It leaves the exact shape of the response loosely defined and says nothing about the project_id format, but for a single-parameter status tool this is close to complete.

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

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

Schema description coverage is 0% for the single project_id parameter, so the description technically carries the burden. However project_id is trivially named and the schema supplies format=uuid and required status; "for an existing project" only loosely implies the id must reference a real project. Marginal value over the schema, so 3.

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

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

States a specific verb and resource ("Returns progress" for an "existing project") and enumerates exactly what comes back: script analysis status, asset/picture gaps, scene storyboard and video state, plus next_step and episode ids. This is far more concrete than a generic getter and distinguishes it from story_get_job and story_get_episode, though it never explicitly names those siblings.

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

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

"Start here for an existing project" is an explicit entry-point instruction that routes the agent to this tool first before the finer-grained story tools. It stops short of naming alternatives or when-not-to-use conditions, so it is clear context rather than full 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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds real value on top: the full status vocabulary (pending, approved, declined, expired, running, done, failed) and the 'Free' cost signal, which the structured fields do not provide.

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

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

Two tight sentences that front-load the core purpose; the status list is compact and the 'Free' fragment is informative despite being terse. No wasted sentences.

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

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

With no output schema, the description usefully enumerates the status values an agent will receive, and annotations cover the safety profile. The only real gap is not explaining where quote_id comes from or its format.

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 technically should compensate, but it says nothing about quote_id. The single parameter is self-evident (a UUID quote identifier), so the gap is minor rather than damaging.

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

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

The description gives a specific verb ('Check') and resource ('a quote'), plus the distinct statuses it reports. It is clearly a read tool, distinguishable by name from story_quote (create) and story_run (execute), though it never explicitly names those siblings.

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

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

Usage is implied rather than stated: 'after a run, which jobs it started' hints that this follows story_run, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative. The context is inferable but not spelled out.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely new context by noting the call is "Free" (no credit cost) and by disclosing the shape of what comes back, including "beats and the original dialogue" for episode mode.

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

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

Two sentences, zero filler. The scope/contents sentence is front-loaded and the parameter behavior follows immediately, with the cost hint appended compactly.

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

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

With no output schema, the description compensates by enumerating returned fields for both modes, and annotations handle the safety profile. An agent has enough to decide whether to call it and what it will get back.

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 documents the only non-obvious parameter well — episode is 1-based and changes the response from an outline to scene-level beats and dialogue. project_id is left to context ("a Story mode project"), which is a minor residual 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?

The description gives a specific verb and resource ("Read the analysed script of a Story mode project") and then enumerates the exact contents returned (title, logline, synopsis, genre/tone, episode outline), which lets an agent separate it from story_get_project, story_get_episode, and story_update_script. The two-mode behavior (full script vs. episode-level scenes) is stated up front.

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

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

It clearly states when to supply the optional parameter: "Pass episode (1-based) to get that episode's scenes with beats and the original dialogue," which tells the agent how to switch modes. It does not name alternative tools for related needs (e.g., story_get_episode) or state exclusions, so it stops short of full routing guidance.

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