Fabeo

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

Annotations already declare non-read-only, non-destructive, non-idempotent, so the safety bar is lower. The description adds the non-obvious lifecycle precondition (must precede approve_script), though it doesn't say what happens if that precondition is violated or whether the call is rejected.

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, and the most constraining fact (the pre-approval window) is front-loaded before the parameter note.

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

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

For a 3-parameter mutation tool with full schema coverage and no output schema, the description covers purpose, timing, and the append default. Only the post-call effect (e.g., whether a scene identifier is returned) is unstated, 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 100% and the description's only parameter remark ("position is 1-based; omit to append") restates the schema's own wording. It adds nothing about narration limits or video_id sourcing that the schema doesn't already carry, 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 gives a specific verb and resource ("Add a scene") and scopes it to the script-review phase with its narration. It implies the boundary against edit_scene/regenerate_scene by limiting itself to pre-approval, but never names a sibling tool 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?

It states a concrete usage window — during script review, before approve_script — which is exactly the condition an agent needs to pick this over edit_scene. It stops short of explicit exclusions (e.g., what to use once the script is approved).

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

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

Goes well beyond the annotations: it discloses the 10-15 minute runtime, that credits are spent and capped at the estimate_cost maximum, and the downstream side effect of writing per-clip H3 prompts and rendering them. Those are exactly the cost/irreversibility facts an agent needs before firing a destructive mutation.

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

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

Three short sentences with the destructive action and its time cost front-loaded in capitals, then the mechanics, then the billing bound. Nothing is redundant with the schema or annotations.

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

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

For a paid, destructive, long-running action the description covers trigger, duration, cost ceiling and idempotent retry. With no output schema, it does not say what the call returns (job id or status payload), which is the only notable omission.

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

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

Schema coverage is 100%, and the schema already explains job_id's provenance and the idempotency_key's 24h reuse behavior in detail, so the description adds no parameter-level syntax. It does add the cost context ('up to the maximum estimate_cost returns'), which tells the agent the financial bound of the call.

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 ('Approve the reviewed script') plus the immediate consequence ('START RENDERING'), so the agent knows this is the gate from review to production. It is clearly distinguishable from siblings like estimate_cost, get_job_status and regenerate_video.

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

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

'Approve the reviewed script' implies the precondition that a script has been generated and reviewed, and naming estimate_cost establishes where the spending ceiling comes from. It does not explicitly say when not to call it (e.g. to preview or regenerate instead), which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that the result covers both upload status and recording length, but says nothing about what happens for an unknown or expired audio_upload_id, nor about polling 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?

One compact sentence with no filler; the resource and the two returned facts are front-loaded. Slightly awkward phrasing ('Whether ... yet, and its length') costs it the top mark.

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 is the only source of return information, and it only discloses two facts (uploaded status, length) without saying whether a URL, file metadata, or error state is returned. Adequate for a one-param read but leaves return-shape gaps.

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

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

Schema coverage is 100% and the single parameter is fully described in the schema, including that it comes from get_audio_upload_page. The description only restates that linkage, adding no format or validation detail 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?

The description states a specific check on a specific resource: upload status of a recording plus its length. It is clearly distinct from siblings like upload_audio (a write) and get_audio_upload_page (which mints the link), though the verb 'whether' is phrased as a question rather than an action verb.

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 ties the call to a 'get_audio_upload_page' link, implying the workflow (create link, then poll this), but never states when to call it versus upload_audio or how often to poll. Usage is inferable rather than stated.

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

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

The annotations already declare this is a safe, read-only, bounded operation, so the description does not need to cover those traits. It adds that the result reflects photos uploaded 'so far,' which clarifies the cumulative nature, but it does not mention error behavior, auth needs, or rate limits.

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

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

The description is a single front-loaded sentence with no wasted text. It is a sentence fragment rather than a polished statement, but it communicates the core outcome efficiently.

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

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

For a simple read-only status tool with one parameter and full schema coverage, the description is mostly sufficient: it implies an integer count and identifies the upload context. It stops short of describing error cases or stating the return type explicitly, and no output schema exists to fill that gap.

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

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

Schema description coverage is 100%, and the schema already explains that upload_id comes from get_reference_upload_page. The description reinforces that link context but does not add format, constraints, or error semantics beyond what the schema provides, so 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 states exactly what the tool reports: the number of photos uploaded on a get_reference_upload_page link. It is specific about the resource and scope, though it does not explicitly name a sibling alternative for contrast.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no named alternatives. The phrase 'so far' hints at checking progress after an upload page is issued, but the agent must infer that usage rather than being told directly.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely new behavioral context beyond them: a plan gating rule and a hard quota (up to 10 brands), which determines whether the call will succeed. It omits failure behavior when the quota is hit.

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 core action and its constraint, then the next-step pointer. Nothing is redundant with the title 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 mutation tool with no output schema, the description covers preconditions and workflow but never says what is returned (e.g., the new brand id needed to call create_product) or how limit/plan violations surface. Adequate for invoking, incomplete for using 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 description coverage is 100%, so the schema already explains name, client_id (optional when only one client), description, and brand_colors. The description adds no parameter-level detail such as color format or name uniqueness, 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?

States a specific verb and resource ('Add a brand') and scopes it ('under a client'), which distinguishes it from siblings like create_client and create_product. It stops short of an explicit contrast with those siblings, but the noun/verb pair is unambiguous.

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

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

Gives the eligibility condition (Agency plan, or Enterprise up to 10 brands) and the follow-on action ('Then create_product'), so an agent knows when this call is valid and what to chain next. It does not say what to do when the plan/limit condition fails, so it falls short of explicit alternatives/exclusions.

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

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

Annotations already disclose that this is a non-read-only, non-idempotent, non-destructive mutation. The description adds the agency-plan restriction and follow-up workflow, but it does not explain duplicate-name behavior, permissions beyond plan type, or what happens on failure.

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 two short sentences with no wasted text. The core action and plan restriction are front-loaded before the follow-up workflow hint.

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

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

For a simple three-parameter creation tool with full schema coverage and annotations covering safety traits, the description provides enough context to invoke it correctly. It could be slightly more complete by mentioning return behavior or duplicate handling, but no output schema exists and the core constraints are stated.

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 all three parameters are already documented in the schema. The description does not add any parameter-level detail beyond the schema, which is acceptable given the high coverage.

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

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

The description uses a specific verb and resource: add a client to an Agency account. It also distinguishes the workflow from the sibling create_brand by saying create_brand should be used afterward.

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 clearly states the prerequisite that the account must be on an agency plan and points to create_brand as the next step. It does not explicitly name alternatives or when not to use this tool, but the context is clear.

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 give coarse hints (destructiveHint, non-idempotent); the description adds real context: the copy lands at script review free of charge, scenes can be deleted but not added, reference photos cannot be applied to a copy, and single_scene renders immediately and spends credits. That is exactly the non-obvious behavior an agent needs before calling a mutating tool.

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

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

Front-loaded with the core action, then the post-copy workflow, then the exclusions/expensive mode. Every sentence carries an actionable constraint (free vs credits, delete-not-add, rewrite-before-approve) rather than filler.

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

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

With no output schema, the description still notes that edit_scene 'result lists the scenes', and it covers the full lifecycle of a copy (create, rewrite, approve) plus the alternative path. Nothing an agent needs to invoke it correctly appears 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 baseline is 3; the description nonetheless adds provenance for template_job_id (it comes from list_templates) and reiterates the credit cost of single_scene. product_id semantics are left to the schema, which already documents list_catalog sourcing and defaults.

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

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

States a concrete verb+resource ('Copy a template from list_templates ... into the user's account') and names the sibling that supplies the input. It also differentiates itself from create_video by stating the copy is word-for-word the template's subject.

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: use this tool to copy a template, use create_video when the video must show the user's own person or product photos, and call edit_scene before approve_script. The single_scene=True case is called out with its cost implication, giving clear when/when-not selection 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?

Annotations already declare it is a non-readonly, non-destructive, non-idempotent write. The description adds sequencing dependencies (photos before product creation), a per-brand cap, and the consequential downstream behavior that videos are generated from the description text. It omits cost/rate implications of the follow-on video generation, which is the main residual gap.

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

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

Two compact sentences with the key prerequisite front-loaded and no filler. The nested parenthetical referencing two sibling tools is slightly awkward to parse but still short and purposeful.

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 creation tool in a multi-step chain, the description covers prerequisites and side effects but never indicates what comes back (presumably a product id used by later tools like get_product or create_video), and there is no output schema to fall back on. Adequate, but an agent wiring the chain must infer the return shape.

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

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

Schema description coverage is 100%, so all six parameters are already documented, including the reference_upload_id / reference_image_keys relationship and the 5-image cap. The description only reiterates the photo prerequisite and the description-to-video link, adding little 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?

States a specific verb and resource ('Add a product under a brand') plus its scoping constraint (Agency, Enterprise up to 100 per brand). It clearly differs from create_brand and create_video, though it doesn't itself explain how it relates to get_product or list_catalog beyond the schema hint.

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

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

Gives an explicit precondition: at least one photo must be uploaded first via get_reference_upload_page / upload_reference_image, naming both sibling tools. It stops short of stating when not to use it (e.g., when the brand doesn't exist yet, or when reusing a template via create_from_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 by disclosing the money-relevant behavior: nothing is rendered or billed until approve_script, while single_scene spends credits immediately. That is the crucial hidden trait for a destructiveHint=true, non-idempotent mutation, and it is stated plainly rather than left to the agent to infer.

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 facts (script review vs immediate render, cost) are front-loaded in the first three sentences. It is dense and mostly earns its length, but it restates some schema content verbatim (aspect_ratio formats, video_type listing) which makes it longer than necessary.

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

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

For an 11-parameter, no-output-schema creation tool it covers the workflow, cost model, and every input's provenance. The remaining gap is the return value: with no output schema, the agent is never told whether it receives a video_id, job_id, or script handle to pass to approve_script or get_job_status.

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%, so the baseline is 3; the description earns extra by adding cross-parameter meaning the schema cannot express — the combined 'up to 5 images in total' cap across reference_image_keys and reference_upload_id, and the product_id + catalog_image_keys coupling. It also warns that people described in the topic must match the reference images.

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 ('Start a new video from a topic') and immediately bounds it (10-1500 chars, subject/style/message/CTA). It also distinguishes itself from siblings by naming approve_script as the gate and by contrasting the single_scene path, so an agent can separate it from create_video_from_audio or create_from_template.

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 branches: multi-scene (default) for script-first free review, single_scene=True for an immediate <=11s clip. It names the prerequisite chains for every optional input (product_id from list_catalog, reference_image_keys from upload_reference_image, reference_upload_id from get_reference_upload_page) and points to get_started for video_type.

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 renders immediately, spends credits at roughly one per second of audio, points to estimate_cost for the ceiling, warns that omitting reference photos makes the system invent a person, and explains that reusing idempotency_key within 24h returns the first result instead of charging again. The opt-in idempotency note complements rather than contradicts idempotentHint=false, and the credit-spend warning aligns with destructiveHint=true.

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

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

The core capability and its constraints come first, followed by the key-wiring instructions and then the cost/idempotency caveats. It is dense but every clause carries actionable information, with no restatement of the title or 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?

For a 10-parameter, credit-spending, irreversible render with no output schema, the description covers the audio and image sourcing chain, the cost model, the idempotency escape hatch, and the failure mode of missing references. Nothing an agent needs in order to call this correctly is absent.

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

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

Schema description coverage is 100%, so the baseline is 3; the description goes further by naming where each key comes from (upload_audio, get_audio_upload_page, get_reference_upload_page) and clarifying that topic only controls look/setting while spoken words always come from the recording. It leaves product_id, video_type and aspect_ratio entirely to the schema.

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

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

States a specific verb and resource plus the exact scope: one scene, length matched to the recording (max 60s), lip-synced in the recording's own voice and language. This clearly distinguishes it from the sibling create_video (which writes a script) without the agent needing to open either schema.

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

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

Gives concrete conditions and prerequisites: pass the recording via audio_key (from upload_audio / get_audio_upload_url) or audio_upload_id (from get_audio_upload_page), and photos via reference_image_keys / reference_upload_id, with an explicit 'strongly recommended' caveat. It does not explicitly state when to prefer the sibling create_video instead (i.e. when there is no recording), which is the only missing routing cue.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered; the description still contributes by spelling out 'Irreversible' and the stage gate that blocks use after approve_script. It omits what happens to surviving scenes (index/ordering effects) or the error behavior if called too late.

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, no filler, with the stage constraint and the irreversibility both front-loaded ahead of any detail.

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 destructive tool with full schema coverage and annotations declaring destructiveness, this covers what an agent needs to select and call it. The only gap is downstream effect on remaining scenes, which is minor given the low complexity.

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

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

Both parameters are fully documented in the schema (100% coverage), including where to source video_id and scene_id. The description adds nothing about them, 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?

States a specific verb and resource ('Delete a scene') plus a lifecycle constraint ('during script review (before approve_script)') that implicitly distinguishes it from edit_scene, regenerate_scene and add_scene. It stops short of naming a sibling explicitly, so it lands just under the top mark.

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?

'during script review (before approve_script)' gives a clear window in which the tool applies, which is real usage context. It does not state what to do instead once the script is approved, or point at edit_scene for the modify-don't-delete case.

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

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

Annotations already declare destructiveHint=true, but the description adds genuinely new context: the deletion is permanent and cascades to all scenes and files, and a confirm gate is enforced. It stops short of stating irreversibility consequences on downstream artifacts or failure behavior when confirm is absent.

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

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

Two short sentences, zero waste, with the destructive scope front-loaded ahead of the safety instruction.

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 two-parameter tool with full annotation and schema coverage, this covers permanence, cascade scope, and the confirmation requirement. Only the error path when confirm is missing or false is unaddressed.

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

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

Schema coverage is 100% and both parameters are well documented in the schema itself, including the confirm gate. The description only restates the confirm=true requirement, adding no new semantics beyond the schema.

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

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

States a specific verb and resource ('Permanently delete a video job') plus the cascade scope ('with all its scenes and files'), which distinguishes it from delete_scene without needing to open either schema.

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

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

Gives a usage precondition ('Requires confirm=true; ask the user first') which is actionable, but never says when to choose this over the sibling delete_scene or what state the job must be in. 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 discloses behavior the annotations cannot: edits are staged and applied later, and 'the result's regenerate_mode tells you which regenerate_scene mode applies it (none during script review)'. It also flags rejection conditions ('it is rejected if it doesn't [quote the narration]'), side effects ('a length shorter than the narration needs cuts the voiceover'), cost implications, persistence of hand-written prompts, and the rights-confirmation prerequisite for frame keys — far beyond the destructive/idempotent 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?

The core contract is front-loaded in one sentence and each bullet is scoped to one parameter, so it is easy to scan. It is still long and occasionally verbose (e.g. the multi-clause H3 style paragraph), but almost every clause carries actionable information rather than restating 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?

For a 12-parameter mutation tool with no output schema, the definition covers the full lifecycle: how each field is applied, which regenerate_scene mode consumes it, how to obtain frame keys, how to verify them (get_video / get_scene_prompts), and how to undo. An agent could invoke this correctly without consulting other documentation.

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 already 100%, the description adds substantial meaning the schema cannot: H3 prompt style rules (one continuous take, no on-screen text, the '<Subject 1> is ... in <Picture 1>' opener), the distinction between start/end frame keys and reference images, and the duration/voiceover tradeoff. It effectively teaches correct value construction for the hardest parameters.

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

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

The opening sentence gives a specific verb and resource ('Change one scene; pass only what changes') and immediately distinguishes it from regenerate_scene by stating that nothing re-renders here. The per-field bullets make it unambiguous which aspects of a scene this tool mutates versus which are left to regeneration.

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

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

It routes the agent explicitly to siblings in several concrete situations: 'offer the user to record the line themselves: set_scene_audio', 'get the key first like a reference image (upload_reference_image ...) -- not get_start_frame_upload_url', and 'remove_start_frame / remove_end_frame undo'. The one notable gap is that the sibling edit_scene_narration, which overlaps with the narration parameter, is never mentioned, so the agent gets no guidance on choosing between them.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description usefully discloses the deferred-effect mechanism (prompts are re-written so the clip later speaks the line), but never states what the destructive flag actually destroys here — the existing narration/rendered audio — nor any credit cost implied by the required regenerate step. Adds real context, but leaves the destructive semantics 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?

Two sentences, purpose front-loaded, no filler. The second sentence's punctuation (a colon introducing both a preferred alternative and a separate follow-up workflow) is slightly tangled and costs a re-read, but the content is dense and 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 three-required-param tool with full schema coverage and no output schema, the description supplies the key operational facts: the redirect to edit_scene and the mandatory regenerate_scene step on rendered videos. It stops short of noting cost/credit implications of that regeneration, which an agent would want before acting.

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 all three params are documented in-schema with sourcing hints (scene_id from get_video, video_id from create_video/list_videos/get_video). The description only restates the narration parameter implicitly ('the new spoken line'), adding no syntax or constraint detail beyond the maxLength=800 already in the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Change one scene's spoken line') in one clear sentence, and explicitly positions it against the sibling edit_scene(narration=...) which it says is preferred. An agent can distinguish it from edit_scene and regenerate_scene without opening a schema.

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

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

Gives an explicit preferred alternative ('Same as edit_scene(narration=...), which is preferred') and a conditional follow-up rule ('on a rendered video, apply it with regenerate_scene(mode='narration')'). Both when-to-use and what-else-to-use are named, not 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety needs no restating. The description nonetheless adds real behavioral context: the upper-bound nature of the figure ('maximum', 'the most the render can cost'), the billing granularity (clip generation only), and the refund policy for failed renders.

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

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

Three short sentences with the core meaning front-loaded; the pricing ratio and refund caveat are parenthetically packed rather than sprawling. Minor redundancy between 'maximum credits' and the closing 'Returns the most the render can cost.'

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

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

With no output schema, the description needs to say what comes back, and it does identify the return as the maximum possible cost. It is slightly thin on whether a breakdown or plain number is returned, but an agent has enough to call and interpret 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% and all three parameters carry their own descriptions, so the schema already does the heavy lifting. The description only reinforces duration_seconds for the regenerate_scene case, adding no detail about scene_count or single_scene beyond what the schema states — the expected baseline of 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?

The description names a specific verb and resource — estimating the maximum credits a render will cost — and immediately qualifies the unit ('~1 credit per rendered second'). It is clearly distinguishable from the sibling mutation tools (create_video, regenerate_scene), though it never explicitly names what it is not.

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

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

It gives a concrete routing rule: 'For regenerate_scene pass the chosen scenes' total duration,' which tells the agent exactly which value to supply in that workflow. There is no explicit statement of when not to call it or of alternative tools, keeping it 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 non-read-only, idempotent, non-destructive, closed-world behavior. The description adds the important side effect that the video is moved off its current product and explains the resulting visibility grouping, though it does not discuss error conditions or response 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 a single front-loaded sentence with no wasted text. The key operation and side effect are stated 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?

For a simple two-parameter mutation with complete schema descriptions and rich annotations, the description supplies the essential behavioral context: existing video reassignment and visibility inheritance. It is nearly complete, though it does not describe the tool's result or failure modes.

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 parameters are documented directly in the schema with source hints (create_video/list_videos/get_video and list_catalog). The description does not add parameter meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: put an existing video under a product. It also clarifies the key scope, that this moves the video off its current product rather than creating or adding a new video, which distinguishes it from siblings like create_video or add_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?

Usage is clear from 'put an existing video under a product' and 'moving it off its current one,' which tells an agent this is for reassignment of existing videos. It does not explicitly name exclusions or alternatives such as create_video, but the context is strong enough.

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

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

Annotations already establish that this is a safe, closed-world read, so the description's job is to add meaning — and it does, by clarifying that the connection's spend limit is a distinct concept from account credits and that billing/plan links are surfaced. It omits any mention of freshness or caching of credit figures, which is the only notable gap for a balance-style read.

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, front-loaded with the payload contents, with the operational advice ('check it before a render') placed last where it belongs. No filler or restatement of the title.

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

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

There is no output schema, so the description carries the burden of describing return values — and it enumerates them (plan, credits, spend limit, billing links). Combined with the read-only annotations, an agent has everything needed to decide to call it and 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?

The tool takes zero parameters, which is the baseline-4 case: there is nothing for the description to disambiguate, and the schema is trivially complete.

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 ('Show') and enumerates exactly what the account resource returns: subscription plan, remaining credits, the connection's spend safety limit, and billing links. That content profile clearly separates it from siblings like estimate_cost or get_product without needing to name them.

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 an explicit trigger for use: 'Check it before a render if credits may be short.' That is clear contextual guidance, but no when-not conditions and no named alternative (e.g. estimate_cost for a cost preview) are offered.

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

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

Beyond the annotations (readOnlyHint false, non-idempotent), the description discloses the one-hour URL lifetime, the 'give them the URL' human handoff, the single-file/format/size/duration limits, and the rights confirmation the user makes on the page. It stops short of saying whether calling again issues a fresh page or invalidates a prior URL — relevant given idempotentHint=false — and says nothing about rate limits.

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, front-loaded with the action and the returned artifact, then the constraints, then the follow-up chain. Every clause (formats, 60s, 4 MB, rights confirmation, chat-app restriction) carries an operational decision the agent would otherwise have to discover by failure.

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 parameters, no output schema and only coarse annotations, the description carries the full burden and does so: it explains what is returned, how long it lives, what the user must comply with, and which tools to call afterward. An agent has everything needed to invoke it and handle the response.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description instead spends its words on the returned URL contract, which is the only input-like decision an agent faces here.

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

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

The description names a specific verb and resource (returns an upload_page_url so the user can upload their own voice recording) and immediately scopes it with constraints: one file, MP3/WAV/M4A/OGG, 60s, 4 MB. The clause 'Use in chat apps, which can't upload files' implicitly separates it from the direct-upload sibling upload_audio, and the follow-up tools are 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?

It states exactly when to use this tool (chat apps that cannot upload files, user supplying their own recording) and gives the full follow-up sequence: check_audio_upload when the user says they're done, then create_video_from_audio or set_scene_audio with the audio_upload_id. This is an explicit when-and-what-next routing, not an implied 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?

Annotations only declare the non-read-only, non-destructive, non-idempotent profile; the description adds genuine behavioral context: one-hour expiry, 60-second length cap, accepted formats, and the exact multipart POST mechanics (upload.fields entries as form fields, file as 'file'). It also discloses the refusal behavior when rights_confirmed is false, which the annotations cannot convey.

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

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

Very information-dense with almost no wasted wording: capability and client constraint first, then upload mechanics, then downstream use, then the consent gate. It is a single packed block rather than clearly separated steps, so the rights-confirmation requirement is somewhat buried mid-paragraph.

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 URL-issuing tool with no output schema, the description covers everything an agent needs: expiry, size/format limits, the exact upload protocol, the returned audio_key and where to pass it, and the consent gate. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description supplies the actual rights notice text the caller must present and the consequence of skipping it, which is the substantive semantics behind rights_confirmed. It also enumerates the accepted formats matching the file_type enum, though it does not clarify the default (mp3) or optionality.

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 — a one-hour presigned upload URL for exactly one voice recording — and immediately scopes it to clients that can make HTTP requests. It explicitly names the siblings it is not (get_audio_upload_page, upload_audio) and the downstream tools that consume its output (create_video_from_audio, set_scene_audio), so an agent can route without opening a schema.

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

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

Gives a clear selection rule: use this only for clients that can make HTTP requests, otherwise use get_audio_upload_page or upload_audio for chat apps. It also states the required precondition (rights_confirmed=true only after notifying the user and receiving their OK) and the follow-on step (pass audio_key to create_video_from_audio or set_scene_audio).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description then adds genuinely non-obvious behavior: status stays COMPLETED while regenerate_scene runs and video_url is stale, plus that failures return a reason and a credits entry with charged/refunded amounts. These are exactly the behavioral gotchas an agent could not infer from structure.

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 return contents before the pipeline, the next_action warning, and the failure case, in descending order of importance. Dense but every clause carries information; the parenthetical example embedding a sample stage string is slightly heavy but illustrative rather than filler.

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

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

No output schema exists, so the description must carry the return contract — and it does, describing the key fields, the stage sequence, the next_action priority, and the failure payload. Nothing an agent needs to poll and interpret 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?

Only one parameter and schema description coverage is 100% — the schema already explains job_id and where to obtain it (create_video, create_from_template, list_videos). The description adds nothing about the parameter, which is appropriate here, 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 ('check a job's progress') and immediately enumerates what comes back (stage, progress_percent, per-stage statuses, next_action). The pipeline enumeration (SCRIPT -> AUDIO -> KEY_FRAMES -> CLIP_GENERATION -> VIDEO_STITCH) makes the scope unmistakable and clearly separates it from sibling actions like regenerate_video or retry_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?

Gives clear operational guidance: 'share it with the user while they wait' establishes the polling context, and 'Follow next_action rather than status alone' is an explicit usage rule with a stated failure mode. It stops short of naming sibling alternatives (e.g. get_video vs. this tool, or when to use retry_step after a failure), so it is not 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 already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered and the description's job is to add context. It does so by spelling out the full return payload, including photos of the product, brand and client. It does not say what happens when a product_id is invalid or missing (the schema covers the default case).

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?

Everything is packed into one front-loaded sentence that leads with the resource and the payload. The phrase 'brand and client' is repeated in the photo clause, which is slightly redundant but not 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?

With no output schema, the description carries the burden of describing returns and does so field by field, down to the three photo keys. Only the nesting/shape of the returned object is left unstated, which is a minor gap for a single-record read.

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

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

Schema description coverage is 100% and the single product_id parameter is fully documented there, including its 'default' fallback and where to obtain it. The description adds no extra meaning about the parameter, 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 and then enumerates exactly what comes back: title, description, extra context, brand, client, and photos with image_key/url/source. That level of detail separates it cleanly from list_catalog, which is only implied as the source of product_id.

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 downstream workflow: show images to the user and pass the chosen image_keys into create_video's catalog_image_keys, which names the sibling and the handoff field. It stops short of saying when to call this versus listing the whole catalog, but the intended use is unambiguous.

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

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

Beyond the annotations, the description discloses important behavior: it returns a one-hour upload_page_url, the page accepts up to 5 PNG/JPEG photos, and the user must confirm rights to the photos. It also explains the intended chat-app context and the required follow-up sequence.

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 return value, then adds limits and next steps without unnecessary repetition. Every sentence contributes useful operational context.

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

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

Given the tool has no input parameters and no output schema, the description provides enough detail: what the tool returns, how long the URL lasts, what the user does on the page, and which tools to call afterward. Nothing essential for correct invocation 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?

The tool takes zero parameters, so there are no parameter semantics to explain. The description appropriately avoids inventing input details, consistent with the baseline for parameterless tools.

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 specific action: generating an upload page URL that lets a user upload reference photos from their own device. It distinguishes the chat-app use case from direct upload paths, but it does not explicitly differentiate itself from nearby siblings such as get_reference_upload_url or upload_reference_image.

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 this in chat apps like Claude or ChatGPT that cannot upload files themselves, and it names the follow-up flow of check_reference_upload then create_video(reference_upload_id=...). It does not explicitly state when to prefer the sibling tool get_reference_upload_url 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 only declare the safety profile (non-readonly, non-destructive, non-idempotent, closed-world). The description adds real behavioral context the annotations cannot convey: the URL expires in one hour, each call yields exactly one image and up to 5 are allowed, an HTTP multipart POST is required with every upload.fields entry as a form field plus the file in 'file', and the call is refused without rights confirmation.

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 audience constraint and the core action, and every sentence carries operational information. The multipart-POST sentence is long and parenthetical, which slightly hurts scanability but not correctness.

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, yet the description explains the return value (reference_image_key) and exactly where to pass it (create_video's reference_image_keys), plus the expiry window and per-image call limit. An agent has everything needed to chain this into a working upload flow.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by spelling out the user-facing protocol behind rights_confirmed (tell the user about ownership/infringement liability, get their OK) and by tying file_type to png/jpg uploads, though it does not discuss the jpeg enum alias.

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

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

States a concrete verb+resource (a one-hour presigned upload URL for one reference image, png/jpg) and immediately scopes it to clients that can make HTTP requests. Sibling tools in the same family (get_reference_upload_page, upload_reference_image) are named as the non-HTTP alternatives, so the agent can tell them apart without opening any schema.

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

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

Explicit routing: use this tool when the client can make HTTP requests; 'Chat apps: use get_reference_upload_page or upload_reference_image.' It also gives the exact call pattern (one call per image, up to 5) and the mandatory precondition (rights_confirmed must be true after informing the user).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds real semantic context with the prompts_stale meaning and how it is resolved. It stops short of describing response structure beyond the field list, but the behavioral disclosure is well beyond the annotation baseline.

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 read purpose before the stale-prompt caveat and the edit_scene recommendation. Density is high and mostly earns its place, though the MiniMax H3 naming adds minor detail an agent may not need.

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

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

For a two-parameter read tool with no output schema, the description sketches the return payload well enough to act on, including the per-clip positive_prompt and start-frame indicator. Only edge behavior (missing scene, error modes) is unaddressed.

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

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

Schema description coverage is 100% and both parameters are documented there, including provenance (video_id from create_video/list_videos/get_video, scene_id from get_video). The description adds no additional parameter-level 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?

Uses a specific verb (read) and scope (one scene as the renderer sees it) and enumerates the returned components: narration, visual description, reference images, per-clip MiniMax H3 positive_prompt, and the start-frame flag. An agent can distinguish this from get_video and edit_scene without consulting schemas.

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

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

Explicitly prescribes the ordering: 'Read this before writing a positive_prompt with edit_scene,' and routes the stale case to regenerate_scene mode='narration'. Both when-to-use and the corrective alternative are named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is carried by structured data, not prose. What the description adds beyond that is a preview of the returned content (capabilities, limits, costs, plan, credits), which matters because there is no output schema. It does not mention response size or whether the payload is static vs. account-personalized, so it stops at 4.

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

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

One sentence, front-loaded with the invocation trigger ('Start here with a new user, or when unsure what to make') followed by the enumeration of what it returns. The parenthetical list of start modes is dense but earns its place by telling the agent exactly what coverage to expect. Minor cost: the comma-list runs long enough that it reads as a run-on.

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

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

For a zero-parameter read-only orientation tool with no output schema, the description supplies the one thing structured fields cannot: an inventory of what the response will cover, so the agent knows this single call replaces several discovery calls. Complete enough to call correctly; only missing is a note on whether the content is personalized to the current account.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description correctly does not waste words on parameter semantics and instead spends its space describing the returned content.

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

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

The description names a specific purpose: an onboarding/orientation tool that returns what Fabeo makes, the ways to start, the seven video styles, limits, costs, template categories, and the account's plan and credits. That is far more specific than a tautology like 'get started', and it clearly is not a creation or listing tool. It stops short of a 5 because it does not explicitly distinguish itself from overlapping siblings such as get_account (plan and credits) or list_templates (template categories).

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 with a new user, or when unsure what to make' gives a clear trigger condition for invocation. It lacks an explicit 'do not use this for X, use sibling Y instead' clause, which keeps it out of 5 territory given the many overlapping read 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?

The description adds substantial behavioral context beyond the annotations: the URL expires in one hour, the upload must be a multipart POST using the returned fields and then the file as 'file', and the next calls to edit_scene and regenerate_scene are specified. It does not explain what happens on repeated calls 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?

The description is compact and front-loaded: the first sentence states the purpose and expiry, the second gives the upload protocol, and the third gives the follow-up workflow. Every sentence adds necessary information with no waste.

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

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

Given the tool's simplicity, the presence of annotations, and the fully described input schema, the description is complete. It covers the purpose, expiry, upload mechanics, and the full downstream workflow, so an agent can invoke it correctly without additional context.

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 input schema already documents all three parameters thoroughly. The description does not add any new semantic details about video_id, scene_id, or clip_index beyond what the schema provides.

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

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

The description states a specific verb and resource: get a one-hour upload URL for the user's own start frame (PNG) for one clip of a rendered scene. This clearly distinguishes it from sibling tools like get_reference_upload_url or get_audio_upload_url.

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

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

The description gives clear context for when to use this tool: when the user wants to provide their own start frame for a clip. It also outlines the subsequent steps (upload, edit_scene, regenerate_scene), but it does not explicitly name alternative tools or state when not to use 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the video_url is only playable once rendered, and scenes come back in order with a defined field set. It doesn't cover error behavior for an invalid or in-progress id, keeping it from a 5.

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

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

Two sentences, front-loaded with the core action and followed by the sibling redirect. The parenthetical field list is dense but useful for anticipating the response. Slight verbosity in the enumeration, but nothing wasted.

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

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

With no output schema, the description carries the burden of explaining returns, and it does so by naming status, video_url, and the ordered scene fields. An agent knows what it will get and how to get related clip prompts via a sibling, leaving only minor gaps around error/in-progress states.

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

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

Schema description coverage is 100% and the single video_id parameter is already documented in the schema (including its provenance from create_video/list_videos). The description adds no format or constraint detail 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?

The description states a specific verb ('Get one video') and enumerates the returned resource: status, playable video_url once rendered, and ordered scenes with their sub-fields. It also differentiates from the sibling get_scene_prompts by scoping that tool to a rendered scene's clip prompts.

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

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

It explicitly routes the agent to get_scene_prompts for clip prompts, which is real alternative-selection guidance, and 'playable video_url once rendered' signals a prerequisite state. It doesn't spell out when not to use this tool (e.g., vs list_videos for discovery), but the context is clear.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds return-shape detail (tree of clients → brands → products with id, title, short description, photo count) and the notable extra that it also reports what the plan may create — useful behavioral context beyond the annotations.

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

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

Two compact clauses: what the tool returns (front-loaded, with the tree structure made explicit) followed by the use case. No filler, no repetition of the title.

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

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

With no output schema, the description must carry the return shape, and it does list the key fields and the plan-permission aspect. It stops short of explaining how the 'what this plan may create' portion is structured or how large catalogs are handled, but nothing essential for calling a zero-argument read 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It does not need to compensate for any schema gap.

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

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

States a specific verb and resource ('the account's catalog as a tree -- clients, their brands, and each brand's products') and enumerates the returned fields plus plan entitlements. It is clearly distinguishable from siblings like get_product, list_templates and list_videos, which cover single products, templates and videos respectively.

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

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

'Use it to find the product_id of the product the user wants a video for' gives an explicit triggering condition. There is no explicit when-not or named alternative (e.g. get_product for a known id), but the context is clear enough to select the tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral context about what is returned in each mode—categories with counts, or per-template ideas and preview_urls—and instructs the agent to show preview links and let the user choose. It does not mention rate limits or auth needs, but those are less critical for a read-only listing operation.

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

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

The description is front-loaded with purpose and next action, then cleanly separates the two conditional modes. It is well-structured and mostly efficient, though the phrase 'a quick way to a good video' is slightly promotional and could be trimmed without losing meaning.

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

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

For a simple read-only listing tool with no output schema, the description covers the essential return shapes for both modes, the optional aspect_ratio filter, and the recommended next step. Annotations cover safety, and the parameter semantics are sufficiently clear from the schema and description combined.

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, setting a baseline of 3. The description adds meaning beyond the schema by giving concrete example video_type categories, stating that the category result is authoritative, and clarifying that aspect_ratio optionally filters templates to '9:16' or '16:9'. This extra semantic context justifies a 4.

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 (browse/list) and resource (Fabeo's template videos), and explicitly distinguishes two modes: without video_type returns categories and counts, with video_type returns template ideas and preview_urls. It also names the sibling create_from_template as the follow-up action, making it easy to tell apart from other listing tools.

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

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

It clearly explains when to use this tool: as a quick route to a good video by finding a template to copy via create_from_template. It also defines usage patterns for both parameter configurations. However, it does not explicitly state when not to use it or contrast it with other listing siblings like list_videos, leaving a minor 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that with result ordering, the cursor round-trip contract, and the mutual-exclusivity constraint on filters — behavior an agent could not infer from the structured fields alone.

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

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

Three short sentences, zero redundancy, with the core action and ordering front-loaded before pagination and filter constraints. Every clause carries a constraint the agent needs to call the tool correctly.

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

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

For a six-parameter read tool with no output schema, the description covers ordering, pagination and filter exclusivity — the main behavioral risks. It stops short of sketching what a listed video contains or noting that the response carries the next_page_token, which would have closed the loop for an agent planning a follow-up call.

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

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

Schema description coverage is 100%, so the baseline is 3. The description earns a point above baseline by stating the cross-parameter constraint that no filter field's own description mentions: at most one of client_id, brand_id or product_id may be set.

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

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

States a specific verb and resource ('List videos in the account') plus a meaningful scope qualifier ('newest first'), which lets an agent distinguish it from the singular get_video sibling without opening either schema. It does not explicitly name the sibling it is not, so it falls short of 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?

Gives concrete procedural guidance for pagination ('Pass next_page_token from a previous response to fetch the next page') and a hard selection rule ('At most one of client_id, brand_id, product_id may be set'). What it lacks is an explicit statement of when to prefer this over get_video or how filtering combines with mine_only.

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 destructiveHint=true annotation by quantifying cost (~1 credit per rendered second), listing what is free (key frames, voice, stitching), and promising a full refund on failure. It also discloses preconditions that cause refusal, which annotations alone cannot convey.

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

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

The action/cost guarantee is front-loaded and the bulleted mode list is easy to scan without waste. It runs long and the closing voice-recording parenthetical is a slight detour, but every section still 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 destructive, credit-spending mutation with no output schema, the description covers cost, refund behavior, preconditions, mode semantics and fallbacks. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is already 100%, yet the description is the only place that explains what each enum value of mode actually does downstream (rewrite prompts vs. new key frames vs. re-roll clips) and what prior edit each requires. That is genuine meaning beyond the enum literals.

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 the exact verb and resource (re-render scenes, then re-stitch) and constrains scope to a FINISHED video, which implicitly separates it from regenerate_video and edit_scene. An agent knows immediately what state the video must be in.

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 an explicit selection rule per mode ('narration' after narration/visual edits or set_scene_audio, 'images' after keyframe='variant', 'clips' after prompt/keyframe/duration edits), states the refusal condition for unapplied edits, and names a concrete alternative path (get_audio_upload_page then set_scene_audio) instead of further re-rolls.

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 destructive/not-idempotent annotations: it discloses that credits are spent per clip second, that a previously failed clip render was refunded so the user is not double-charged, that edited scenes are re-written into prompts first, and that the retry is refused without the content_edited flag. That is exactly the cost-and-side-effect context an agent needs before a destructive, billable call.

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

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

The core action and the alternative are front-loaded, and each following sentence carries non-redundant cost or side-effect information. Slightly dense with the refund aside, but nothing 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?

Complete on cost, side effects and failure routing for a billable mutation tool, and annotations carry the safety profile. The one gap is that it never says what comes back (job id / async job) or that the caller should poll get_job_status, and there is no output schema to fill that in.

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 job_id, content_edited and idempotency_key are already fully documented in the schema. The description adds context about when the content-policy retry applies but no new syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Re-render every clip of a finished video') plus the recovery case (retry a render that failed at clip/stitch). It explicitly contrasts with retry_step and implicitly with regenerate_scene, so an agent can route without opening either schema.

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

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

Gives both when-to-use (failure at clip/stitch step, e.g. ran out of credits) and when-not ('For failures at other steps use retry_step'), naming the alternative. It also states the precondition for the content-policy retry path.

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 annotations: which failures are free to retry, which spend credits, how estimate_cost relates to the maximum charge, and the content-policy prerequisite. These are meaningful side-effect and cost disclosures for a destructive, credit-spending operation.

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

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

Front-loads the core action, then concisely covers failure-mode branches, cost implications, and exclusions. Every sentence adds operational value without repetition.

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 a 3-parameter mutation tool with no output schema, the description is complete enough: it explains eligibility, cost behavior, content-policy handling, and the key exclusion case.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces content_edited usage after content-policy failures, but it does not add much semantics beyond what the schema already documents for job_id, content_edited, and idempotency_key.

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

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

States a specific action (resume a FAILED video) and resource/job scope, and explicitly clarifies the preserved script/edits. It distinguishes the tool from related recovery or regeneration actions by focusing on same-job resume.

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 eligibility (FAILED jobs), points the agent to get_job_status's next_action, covers the content-policy path with edit_scene and content_edited=true, and explicitly excludes running or stuck jobs.

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, idempotentHint=true and readOnlyHint=false, yet the description still adds real value: the revert path via remove=true, the 60s cap, the lip-sync/length consequence, and the fact that the change isn't rendered and that regenerating spends credits. The only gap is it doesn't say what happens to a previously uploaded recording beyond remove=true.

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

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

Front-loaded with the purpose and effect before the parameter mechanics and the re-render caveat, which is the right order. It is dense – the opening sentence carries several clauses – but every sentence conveys a distinct, actionable fact with no repetition.

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

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

For a 6-parameter mutating tool with no output schema, the description covers trigger, side effects, revert, prerequisites, credit cost and the required follow-up call on rendered videos. Nothing an agent needs in order 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 baseline is 3; the description still adds meaning the schema lacks – that audio_key and audio_upload_id are alternatives sourced from upload_audio/get_audio_upload_page, that narration is the transcript used to align text and visuals, and the 60s duration constraint. It stops short of stating which of the two audio parameters wins if both are supplied.

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 ('Replace one scene's AI voice with the user's own recording') plus the resulting state (scene shows the person speaking, lip-synced, length = recording up to 60s). It is clearly separable from edit_scene_narration and regenerate_scene, which are the sibling tools an agent might otherwise 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?

Gives explicit trigger conditions (AI voice mispronounces words, handles a regional language/accent badly, adds gibberish or stray sounds, and editing narration didn't fix it) and states the exclusion: nothing is re-rendered here, so on a rendered video use regenerate_scene(mode='narration'). It also names the prerequisite tools (get_audio_upload_page / upload_audio).

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false). The description adds genuinely new behavioral context: the call is refused unless rights_confirmed is true, and the exact legal notice must be shown first. It does not, however, disclose what happens on repeat uploads of the same URL (non-idempotency), whether uploads are retained/deletable, or anything about failures — gaps an agent would care about for a write operation.

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

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

Front-loaded with the verb, formats, and size cap, and the alternative is placed last where it belongs. The embedded rights notice is long but is required content, not filler; the only blemish is the awkward splice "first tell the user By uploading... and get their OK," which slightly muddies sentence boundaries.

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 write tool with no output schema, the description covers the input source, the format/size constraints, the returned key, the downstream consumers, the consent gate, and the alternative path for local files. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3. The description goes beyond it by supplying the verbatim rights notice the agent must display before setting rights_confirmed=true, which is semantic instruction the schema only references. audio_url semantics largely restate the schema field description.

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

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

States a specific verb and resource ("Store the user's voice recording"), constrains the input form (public https link to MP3/WAV/M4A/OGG, up to 60s, 25 MB), and names the output artifact (audio_key) plus the two sibling tools that consume it. An agent can distinguish it from get_audio_upload_page and upload_reference_image 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 routes the alternative case: "For a file on the user's device use get_audio_upload_page instead." It also names downstream tools (create_video_from_audio, set_scene_audio), so the agent knows both the entry condition and where the result goes.

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 openWorldHint=true, not idempotent, not read-only and not destructive; the description adds the size/format ceiling, the downstream key consumed by create_video, and the hard rights gate that blocks the call. That gating consequence and the mandatory user-consent step are real context beyond the annotations, though it doesn't discuss failure modes, duplicate uploads, or what happens to a stored image later.

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 the alternative tool are front-loaded in the first clause, which is good, but the sentence then runs on through a verbatim legal notice before closing with 'and get their OK.' The notice must be reproduced for the user, so it earns its place, yet the single run-on construction makes the actionable instruction ('get their OK') easy to lose.

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 parameters and no output schema, the description covers the essentials: input constraints, the consent procedure, the returned reference_image_key, and the sibling alternative. Missing only minor operational detail such as whether re-uploading the same URL yields the same key (relevant given idempotentHint=false).

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

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

Schema coverage is 100%, so both parameters are already documented in structured form. The description does add meaning for rights_confirmed (it holds the exact notice text the agent must present), but image_url is largely a restatement ('public https link straight to a PNG or JPEG') of the schema's own wording.

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

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

States a specific verb and resource ('Store a reference image') with the accepted source (public https link), accepted formats (PNG/JPEG, max 10 MB), and what it produces (a reference_image_key for create_video). It also distinguishes itself from the sibling get_reference_upload_page by naming the case that tool covers (photos on the user's device).

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: use this tool for a public link, use get_reference_upload_page for files on the device. It also states the precondition sequence — show the user the rights notice, get their OK, then set rights_confirmed — so there is no ambiguity about when the call is legitimate.

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