Cinegenta Studio

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

Goes well beyond the annotations: it discloses the spend cap ('the plan's own price as its cap'), the safety stop points ('stops at reviews and before any step that can't be undone'), and the partial nature of rollback ('undo rolls the plan back as far as it can'). It never contradicts destructiveHint=true. It does not state whether credits are charged on a failed or skipped run, which is the one material cost gap for an operation flagged as destructive and credit-spending.

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 precondition and the credit warning, and nearly every clause carries distinct information. The middle sentence chains four action definitions in a single run-on, which is dense but not padded; nothing here is filler.

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

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

Covers the full burden for a destructive, credit-spending mutation with no output schema: precondition, cost cap, stop conditions, per-action recovery paths, and a pointer to get_status for progress. An agent can call it correctly and knows what to do when it halts, which is everything this tool needs.

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

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

Schema coverage is only 40%, so the description must compensate, and it largely does: it explains all five action values, how choices are keyed ('by option id or in the person's own words'), and that alternative takes the id of one of the plan's costed alternatives. project_id and plan_id are left to their names, which are self-evident, so no meaningful ambiguity remains.

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

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

States a specific verb and resource (run/apply a plan produced by direct) and immediately scopes it with a precondition ('only after the person has heard it and said yes'). The title calls out that it SPENDS CREDITS, and the action verbs (start/continue/retry/skip/undo) make it trivially distinguishable from build_plan, get_plan, and get_status.

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 when-to-use gate (after the person has heard the plan and said yes) and routes each action: start to run it, continue from a stop, retry a failed step, skip to end, undo to roll back. It also names get_status(plan_id) as the way to poll progress, so the agent knows the alternative to blind re-invocation.

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 write/non-destructive profile, while the description adds the details an agent actually needs: the operation is free, takes minutes and is asynchronous (poll get_status), can pause at a human review gate with a link, and is resumed by invoking the same tool again. It also discloses the refusal/continue path around keep_length. These are behavioral traits well beyond what annotations convey.

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

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

The core action and its free/no-render nature are front-loaded, and each sentence carries distinct information (duration, polling, pause/resume, cancellation). The final sentence runs long and packs three ideas together, which slightly hurts scanability but not comprehension.

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 asynchronous, multi-stage build tool with no output schema, the description covers cost, duration, polling, review-pause semantics, resumption, and early cancellation — enough to invoke it correctly. It is silent on what a completed plan looks like or what apply_plan does next, which would have closed the lifecycle.

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

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

Schema coverage is 67%, and the schema already documents both decision and keep_length, so the baseline is 3. The description adds context for resuming after a review pause and for continuing past a refusal, but it never mentions the decision enum (keep_cut vs retry) or project_id, so it does not meaningfully extend parameter meaning beyond the schema.

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

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

States a specific verb and resource ('Turn the stored script into the full production plan') and enumerates the artifacts produced (scenes, characters, locations, shots, continuity review). It also pins down scope by saying this is the same run the Script page starts and that no renders are fired. It does not differentiate itself from nearby siblings like apply_plan or regenerate, which is the only reason 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 operational guidance: poll get_status while it runs, call build_plan again after a human approves a review pause, and use run_control(action: "cancel_build") if the script needs changing first. That names a real alternative and its trigger condition. It never states when not to use this tool versus apply_plan or regenerate, so it stops at 4.

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

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

Beyond the annotations it discloses the economics and mutability profile: every field is free and reversible until greenlight, the quote re-prices live, and the default lower-upscale finish incurs a billed pass per clip. That is exactly the cost/permission context an agent needs before mutating a project.

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 first clause front-loads the most decision-relevant fact (everything is optional, free, and reversible), and the delivery caveat follows in priority order. The middle sentence is dense but each clause carries distinct meaning; nothing is filler.

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

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

For a 15-parameter mutation tool with no output schema, key gaps remain: whether omitted fields are preserved or reset, and how the 5 image-model and 15 video-model options differ in cost or quality. The description covers the scoping and delivery model well but leaves an agent guessing on the largest enum sets.

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 53%, and the description does real work on the hardest pair — target_resolution (mastering) versus finish (native vs lower-upscale, with lower-upscale named as the default), which is non-obvious even with the schema text. But roughly half the parameters (image_model, video_model, aspect_ratio, visual_style, dialogue_mode, genre, theme) get no explanation of cost, tradeoffs, or defaults, so the gap is only partly closed.

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

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

The description names a concrete verb (set) and the specific resources it configures (the script and the movie's format), so an agent knows exactly what class of operation this is. It implicitly separates itself from greenlight (changeable until greenlight) but never names or contrasts a sibling tool directly.

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

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

It gives a clear operating window (all optional, all free, all changeable until greenlight) that tells the agent this is the pre-approval tuning step, and explicitly scopes out anything not listed ('configured in the app's Setup page'). It stops short of naming alternatives such as build_plan or quote for the post-configuration steps.

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 this is a non-read-only, non-destructive, closed-world mutation. The description adds information annotations do not carry: the call is 'Free', and no script is needed to succeed, both of which affect an agent's decision to call it early. It stops short of describing the resulting project's state or what identifier comes back.

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

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

Front-loaded with the verb and the cost/sufficiency facts in short sentences; nothing is padded. The trailing fragment 'Then build_plan (free) and quote.' is terse to the point of being slightly clipped, but it still carries workflow value.

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

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

There is no output schema, so the description is the only place to learn what a successful call returns or how to reference the new project in the follow-up build_plan/quote steps. The ordering advice is helpful but the handoff is left implicit, which is a meaningful gap for a create-then-chain tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns one more by clarifying precedence: title alone is sufficient at creation time and script can be supplied later via configure, which is a decision-level insight the schema's required-list does not spell out.

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

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

States a specific verb and resource ('Create a new Cinegenta project') and immediately scopes it: only a title is required. It also implicitly differentiates itself from siblings by noting that script content can be added later 'through configure', so an agent can tell create from update without comparing schemas.

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

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

Gives explicit sequencing: create first with a title, defer script to configure, then build_plan and quote. That is real when-to-use guidance across siblings. It does not state exclusions (e.g., when to use list_projects or get_status 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 only declare the generic safe-mutation profile (readOnlyHint false, destructiveHint false); the description adds the operationally decisive facts: the call is non-mutating until apply_plan, it can incur a small charge from a planning model, and it may take minutes with an async result. Those are exactly the behavioral traits an agent cannot infer from the structured fields.

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

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

Front-loaded with purpose, then return shape, then consent/cost, then latency handling, then exclusions — each sentence carries a distinct decision-relevant fact. No filler or repetition despite covering a lot of ground.

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 spells out the return payload (steps, per-step costs, choices, plan_id) and the not-ready case. Combined with the consent, cost, and latency notes, an agent has everything needed to call this correctly and handle its result.

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

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

Schema coverage is 50% because project_id has no description. The description compensates for the important parameter by defining `request` as the person's own words and enumerating sample change types, which tells the agent what level of natural-language input to pass. project_id is left implicit, keeping this below a 5.

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

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

States a specific verb and resource ("Ask the Co-Director for a change to a built film") and immediately grounds it with concrete examples of what a change is (recast, rewrite a shot, redo a scene's look, trim the cut). It also names the sibling it hands off to (apply_plan), so an agent can place it precisely in the workflow.

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

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

Explicitly says nothing changes until apply_plan, requires getting the go-ahead first because drafting may charge, and gives the fallback path (get_status(plan_id)) when the plan isn't ready. It also lists what this tool cannot do (score, dialogue audio, upscaling, retake cuts), which is real exclusion guidance rather than vague context.

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

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

Annotations only say it is non-read-only and non-destructive; the description adds the operationally critical facts: no credit cost, minutes-long runtime, that progress and the download link come via get_status(wait_sec), and that share creates a PUBLIC page. It also discloses the failure modes (run still producing, shots without clips).

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

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

Front-loads what is produced, then cost, then duration/progress mechanism, then flag-specific caveats, then refusal conditions. Dense but every clause carries information an agent would otherwise have to discover by trial.

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

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

With no output schema, the description still tells the agent how results surface (get_status polling then a download link) and covers cost, latency, safety of the public share, and refusal conditions. Nothing needed 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 67%, with share and allow_missing already documented inline. The description reinforces both with the consequence of each ('PUBLIC to anyone with the link', 'shorter film'), which adds decision-relevant meaning beyond the schema. project_id remains undescribed in either place.

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

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

States a specific verb and resource ('Assemble the finished cut and export the film file') and pins down the scope by defining exactly what the exported cut contains: score, narration, seams, fades and prior human edits. That resolves ambiguity against siblings like apply_plan, build_plan and run_control without needing their schemas.

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

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

Gives explicit conditional guidance for both optional flags ('only when the person asks' for share, 'only when the person accepts a shorter film' for allow_missing) and names the two preconditions under which the call is refused. An agent knows both when to call and when not to.

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

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

Goes well beyond the annotations: it declares the call is free, explains the paging contract ('the result says how to read on'), and warns that plan content is untrusted personal data that must never be acted upon — a security trait no annotation expresses. Annotations already cover read-only/idempotent, and nothing here contradicts them.

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

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

Two dense sentences, front-loaded with the operation and section list, then usage and the trust boundary. Every clause carries information; nothing repeats the schema or annotations verbatim.

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

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

With no output schema, the description does the right work by explaining pagination and section semantics. Minor gap: it does not clarify that the 'scene' parameter is only meaningful with section='scene', nor what happens on an out-of-range page.

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

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

Schema coverage is 75%, so the baseline is 3; the description earns extra by explaining what each section actually returns ('scene' = one scene's shots, 'overview' = settings, cast, scenes), which the bare enum does not. The relationship between the 'scene' number and section='scene' is only implied.

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

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

States a specific verb and resource ('Read the production plan as text') and enumerates the exact sections it can return, so the surface is unambiguous. An agent can tell it apart from apply_plan/build_plan/quote without opening the schema.

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

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

Gives concrete usage contexts: showing the person what they would be paying for, and fetching exact names that upload_reference needs. It does not explicitly say when-not or name apply_plan as the mutating alternative, but read-only framing makes the boundary 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 readOnly, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds important long-poll semantics: wait_sec holds the call up to 45 seconds until something changes, and it previews returned checkpoints and app links. It does not cover auth or error 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 front-loads the status view and stays compact, with every clause describing a returned field or parameter behavior. The list-heavy sentence is dense 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 usefully enumerates what is returned: plan-build progress, run status, department, spend vs cap, checkpoints, next steps, and the finished film link. It also explains long-polling. Minor gaps remain around project_id meaning and error behavior, but it is complete enough for a read-only status tool.

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

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

Schema description coverage is 67%, with project_id undocumented and plan_id only vaguely described as 'A plan from direct'. The description clarifies plan_id as a Co-Director plan and explains wait_sec as a hold-until-change mechanism up to 45 seconds instead of polling, adding meaningful 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?

The description names a specific resource, production status, and enumerates the fields returned, so an agent can tell it retrieves current production state. It distinguishes project-scoped status from plan-scoped status via plan_id, though it does not explicitly contrast with siblings like get_plan or list_projects.

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

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

It gives conditional usage for plan_id (follow a Co-Director plan instead) and wait_sec (long-poll instead of polling), plus notes it is free and read-only. It does not state when not to use it or name alternative sibling tools.

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

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

Annotations only say destructiveHint=true; the description goes much further, disclosing that real credits are spent, that the server enforces the cap before every render, that failures refund themselves, and that stopping preserves completed work. These are the exact risk facts an agent needs before invoking an irreversible spend.

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 credit-spend warning is front-loaded in caps immediately after the opening clause, so the highest-risk fact is seen first. The remaining clauses are dense but each carries a distinct behavioral fact; the run-on punctuation in the rung clause is the only rough edge.

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, 5-parameter, no-output-schema tool, the description covers preconditions, cap enforcement, failure refunds, and interruption semantics. What it omits is what a successful call returns (a run identifier or status) and how to observe progress afterward, which run_control/get_status would handle.

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

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

Schema coverage is 60%, and the description fills the main gap by decoding the rung enum (1 every step · 2 big decisions · 3 autopilot), which the schema provides no descriptions for. It also reinforces cap_credits as human-approved and never invented, and links quote_id to the quote step. project_id remains unexplained in both places.

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?

'Start the produced run' gives a specific verb and resource, and the title plus the credits sentence make clear this is the spend-triggering execution step. It is distinguishable from quote and apply_plan, though the word 'produced' is slightly opaque without familiarity with the pipeline.

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 precondition (cap_credits must be a number the human explicitly approved in chat after seeing the quote) and spells out rung's three modes. It also explains exactly when confirm_length applies (only after a refusal citing that question), which is strong conditional guidance. It never names a sibling tool as the alternative, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description adds 'Free', a cost/credit cue that annotations do not express — genuine value beyond structured fields. 'read-only' is redundant with the annotations, preventing 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?

A single compact sentence front-loads the action and resource, then tacks on return fields and cost. 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?

For a zero-param, no-output-schema list tool, the description covers purpose, returned fields, and cost. 'activity' is left vague and there is no pagination note, but the essentials an agent needs to call it are present.

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

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

Zero parameters, so the baseline is 4. The description instead documents the return shape (id, title, activity), which is useful given there is no output 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 ('List') plus resource ('the user's Cinegenta projects') and even names the returned fields (id, title, activity). The contrast with create_project is implicit but obvious from the verb; it doesn't explicitly route to sibling tools, keeping it just 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?

'Free, read-only' implies this can be called liberally without cost or side effects, which is useful usage context. However, it gives no explicit when-to-use or alternatives among siblings (e.g. vs. get_status or create_project).

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds what they cannot: that the call is free and side-effect-free ("Pure and free"), that it can be invoked repeatedly, and that its suggested cap is advisory rather than an enforced spend limit. That last point is a genuinely important semantic distinction an agent would otherwise get wrong.

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

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

The purpose and returned artifacts are front-loaded, and each following clause carries a distinct decision-relevant fact (freedom to re-call, re-quote trigger, cap authority). 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?

With no output schema, the description does the work of describing the return payload (estimate items, range, suggested cap, balance, quote_id) well. The one remaining gap is sequencing: it never states whether a plan must exist first (build_plan/get_plan before quote), which matters for an agent orchestrating these siblings.

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

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

Schema coverage is 0% for the single project_id parameter, so the description must compensate. It implies project scoping ("remaining work on a project") but never states the identifier format or that project_id comes from list_projects, leaving the agent to infer sourcing.

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 (itemized cost estimate for the remaining work on a project) and enumerates the cost lines it covers (casting, storyboard, shoot, score) plus the returned artifacts (range, suggested cap, balance, quote_id). This is clearly distinguishable from siblings like greenlight and build_plan, which the description also names.

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

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

Explicitly licenses repeated use ("call as often as useful while negotiating scope") and states the re-quote condition ("If the plan or settings change, quote again"). It also routes the spending decision to the sibling tool, clarifying that the cap set at greenlight, not this estimate, is the boundary.

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 (destructiveHint=true, readOnlyHint=false), the description discloses that it bills a render against the project's image or video model, that it sits outside any run's cap, and that a human approval gate applies. It also explains idempotency semantics including the retry-with-same-key rule, which is exactly the behavioral context an agent needs before a costly 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?

The cost warning and core action are front-loaded and nearly every clause carries new information (cost, cap exemption, approval, key provenance, idempotency). The final sentence is long and slightly run-on, costing a point on structure.

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

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

With no output schema and a destructive, credit-spending mutation, the description covers cost, approval gate, cap exemption, retry safety, and input provenance — everything an agent needs to call it without causing double billing or unauthorized spend.

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

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

Schema description coverage is only 20%, so the description must compensate, and it largely does: it explains note as image-only change instructions with an example, gives asset_key provenance, and fully specifies idempotency_key behavior. The kind enum values are only partly reflected in prose (look/storyboard frame/clip vs. six enum values) and project_id is unaddressed, keeping it below 5.

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

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

The first sentence gives a specific verb+resource+scope: redo one asset (look, storyboard frame, clip) rather than a whole plan or run, which implicitly separates it from siblings like apply_plan and run_control. It does not name an alternative tool explicitly, 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?

Explicit when-to-use rules are given per branch: images take a note, a clip re-renders from its current plan, and changing clip content requires editing the plan first. It also states a prerequisite (get the human's go-ahead first) and where asset keys come from (review's structured result), leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description still adds substantial operational detail: sheets are paged, the caption reports what remains, cells are numbered, and the structured result maps numbers to asset keys for regenerate. Pagination and result-shape disclosure are exactly the kind of context annotations cannot carry.

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

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

Front-loads the view options, then the return format, then the paging rule — a sensible order. Slightly padded by the motivational closer ('Approving sight-unseen defeats the checkpoints'), which restates the preceding instruction, but overall dense 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 4-parameter tool with no output schema, the description adequately conveys what comes back (labeled contact sheet, numbered cells, key mapping) and how to traverse it. Minor gaps remain: project_id semantics and behavior when a view has no assets yet.

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

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

With only 50% schema coverage, the description compensates well: it explains what each 'view' enum value produces, clarifies that storyboard/clips are 'by scene,' and explains paging behavior for 'page.' Only 'project_id' is left without any description-level meaning.

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 and resource ('See the film's current work inline') and enumerates the exact view modes (cast, outfits, locations, objects, storyboard, clips) with what each depicts. That specificity separates it cleanly from siblings like regenerate or get_status, and it even names the downstream tool (regenerate) the contact sheet feeds.

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 workflow context: 'look at every page before a checkpoint' and 'Approving sight-unseen defeats the checkpoints,' which tells the agent this is the pre-approval inspection step. It does not name an alternative tool or state when not to use this one, so it stops short of a full 5.

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

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

With destructiveHint=true already declared, the description adds what the annotations cannot: which actions preserve artifacts ('stop — keeps everything made', 'cancel_build — free; what it wrote stays'), that 'continue' clears the current checkpoint, and that three actions re-enable spending and need a spend-scope key. That is concrete consequence and authorization context an agent needs before firing a destructive 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?

Front-loaded with the purpose, then a single dense run of mid-dot-separated action glosses; every clause carries real information and there is no filler. The extreme density makes it harder to scan for a single action than a short bulleted list would, which caps it at 4.

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-parameter, destructive control tool with no output schema, the description covers action semantics, cost, artifact retention and spend authorization. Remaining gaps are minor: project_id scope is never explained and no return/confirmation behavior is hinted at.

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

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

Schema coverage is only 33% (only cap_credits is described), and the description compensates strongly by defining the semantics of all seven action values, including which are irreversible or spend-enabling. project_id is left completely undocumented in both schema and description, which keeps this below a 5.

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

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

States a specific verb+resource ('Operate a live run') and then enumerates all seven actions with a short gloss for each, so an agent knows exactly which operation each enum value performs. It also implicitly routes away from siblings by naming the greenlight question and the review step that gate 'decline' and 'continue'.

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 preconditions for the risky actions ('continue' only after human approval of what review showed; 'raise_cap' only with a human-approved cap; 'decline' dismisses the greenlight question) and states that resume/continue/raise_cap re-enable spending and require a spend-scope key. It stops short of saying when to prefer pause vs stop vs cancel_build beyond their one-word glosses.

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 flag write/open-world/non-destructive; the description adds cost ('Free'), the presigned-URL upload mechanics, and a consent/compliance gate for real people that is invisible in structured fields. The closing caveat that an image carries identity/look but not physical scale is a genuine behavioral limitation an agent could not otherwise 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?

Purpose is front-loaded, then alternatives, then the consent caveat — a sensible order with no filler sentences. It is dense, with a long parenthetical for the curl/PUT flow, so it is efficient but slightly crammed rather than cleanly scan-able.

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

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

No output schema exists, and the description compensates by explaining what the begin call returns (presigned URL, upload_key). For a 10-param write tool with an open-world network hint, the remaining gaps in an agent's decision-making are closed.

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

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

With 80% schema coverage the baseline is 3, but the description goes further by explaining how params interlock: source_url as the server-fetch path versus mode begin/commit with upload_key threaded from the begin call, plus the real_person → consent_confirmed pairing. This adds relational meaning the flat schema cannot express.

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 ('Attach the user's own image as an entity's look') and immediately enumerates the three target kinds (character face/identity, location plate, object reference). An agent can distinguish this from plan-mutating siblings like build_plan/apply_plan without opening the schema.

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

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

Explicitly lays out the two invocation paths — source_url for a public https image, or the begin/commit pair for local files — including what begin returns and what to pass on commit. It also states the prerequisite that names come from get_plan and the consent condition, so the when-and-how is fully covered.

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