Kuro

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

Annotations only cover the safety profile (non-readonly, non-destructive, non-idempotent). The description adds what annotations cannot: asynchronous behavior (get_generation waits), cost in credits, latency expectation, and the override precedence where `style` beats `preset` whichever is given. That is meaningful behavioral context beyond structured fields.

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

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

Purpose, cost and latency are front-loaded, and later sentences each carry distinct information (defaults, preset list, style override semantics, round-trip). Sentences are long and heavily em-dashed, which slightly hurts scannability, but there is essentially no filler.

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

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

For a mutation tool with a deep nested schema and an existing output schema, the description supplies everything an agent needs: default behavior, cost, timing, override precedence, and the round-trip with get_generation's caption_style. Return-value explanation is not required given the output schema, yet the caption_style handoff is usefully noted.

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

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

Schema description coverage is 0% and the style object is deeply nested, so the description carries the load. It enumerates the `preset` values and singles out `word`, explains that `style` overrides preset and covers type/weight, size, casing, colours, outline-or-plate, position and `grouping`. It leaves margin_h, margin_v, font_id and schema_version unaddressed, so it compensates well but not exhaustively.

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 compound action — transcribe a clip's speech and burn captions in as a new library video. An agent can distinguish it immediately from transcribe_media (transcription only) or get_transcription (retrieval), and the output artifact (new video in the library) is explicit.

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

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

It gives concrete operating context — default look if only `source` is passed, ~5 credits, a few minutes, and that get_generation waits for the result. It also describes the re-run flow ('the same captions on this other clip' via caption_style). It never explicitly says when NOT to use it or names a sibling alternative, so it falls just short of a 5.

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

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

Annotations already declare the safety profile (not readOnly, not destructive, not idempotent), lowering the bar. The description adds one genuinely behavioral constraint — the image is frame zero, so a clip cannot move what the first frame does not show — but says nothing about cost, credit consumption, async/queue behavior, or what a failed animation leaves behind. Useful but thin for a 15-parameter generation tool.

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

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

Front-loaded with the core verb+resource in the first sentence, then the constraint, then the routing. The frame-zero sentence is slightly labored ('at the height and distance the action needs') but every clause adds usable information, and there is no filler.

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

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

For a complex, 15-parameter generation tool with an output schema covering returns, the description supplies purpose, the key input constraint, and an explicit escalation path to recipes and model guides. The main residual gap is model-selection guidance, which it deflects to the guides rather than attempting to cover inline.

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 carries real weight here: it defines `prompt` as the motion description and `image` as frame zero with a composition requirement, which the schema does not. However, of 15 parameters, model, resolution, presets, subjects, duration_seconds, recreate_of, reference_audios, reference_images and the frame params get no semantic treatment in the description, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource — 'Animate an existing image or upload into a clip' — and scopes it to existing images rather than generating new ones, which cleanly separates it from generate_image and generate_clip. It also names generate_with_recipe as the preferred alternative, so the agent can place it without opening any schema.

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

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

Explicit routing: search list_recipes, read with get_recipe, prefer generate_with_recipe when inputs/output fit, otherwise read the model guide and animate here. This is a full when-to-use / when-to-use-something-else instruction set, 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?

Adds substantial behavior beyond annotations: it spends credits, dispatches asynchronously and returns before completion, refuses rather than half-applies on invalid multi-scene morph/model input, and warns that bad stills cost the same as good ones. This is exactly the mutation cost, atomicity, and async semantics an agent needs.

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

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

Front-loads the core action, then layers constraints in dense, non-redundant sentences. It is longer than average, but nearly every clause conveys a distinct operational rule; the morph guidance is verbose but justified by the double-application failure it prevents.

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, async tool with an output schema present (so return values need no explanation), the description covers cost, dispatch/poll lifecycle, readiness prerequisites, and refusal semantics well. It leaves some lower-frequency parameters (idempotency_key, references) undocumented, which is a minor gap.

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

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

Schema description coverage is only 10% across 10 parameters, so the description carries real load: it explains quote, the scenes/all_ready selection mode, morph_into_scene's single-destination rule, and the one-model-per-take constraint. However, storyboard_id, idempotency_key, references, and reference_scenes go unexplained in both description and 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 (animate/film scenes) with precise scope: named scenes, or every ready-still/no-clip scene. An agent can distinguish it from animate_image, generate_clip, and render_storyboard purely from the first sentence.

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

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

Gives explicit when-to-use, prerequisites (generate and inspect stills first), follow-up action (poll get_storyboard), and a non-mutating alternative (pass quote to price without filming). Covers when-not implicitly via the still-readiness gate and the multi-scene refusal 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 destructiveHint=true, readOnlyHint=false and idempotentHint=false, but the description adds non-obvious behavior: created scenes arrive 'unshot,' and the operation is atomic — 'Refused whole, with nothing made, when the template has more scenes than the plan allows.' That refusal/rollback semantics is real disclosure the annotations do not carry. Missing only permission/credit notes.

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 zero filler; the creation scope is front-loaded and the atomic-refusal caveat is placed last as a trailing constraint. Every clause carries information an agent needs.

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

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

An output schema exists, so return values need no explanation, and the description covers creation semantics, resulting state, atomic failure, and the follow-on flow. The only gap is not indicating where a valid template_id comes from.

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

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

Schema description coverage is 0% with 2 params. The description resolves a genuine ambiguity for `name` ('is the new film's'), clarifying it is not the template's name, but says nothing about `template_id` beyond what the uuid schema implies. Partial compensation for the coverage gap.

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

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

States a specific verb and resource ('Make a new storyboard from a template') and immediately scopes what gets created: 'every scene and connection, unshot.' It is clearly distinguishable from create_storyboard (blank board) and its sibling save_storyboard_template (the inverse direction).

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

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

It names the downstream workflow tools (generate_scene_images, animate_scenes, render_storyboard), which gives implied context for when to use it, but never states when to choose this over create_storyboard or where template_id is obtained (list_storyboard_templates). No explicit exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=true, so safety is partly covered. The description adds genuinely new context: the operation is reversible and the restore path is archived: false, which contrasts with the sibling delete that is not reversible. That is useful behavioral disclosure beyond the structured fields.

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

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

Two short sentences, zero filler, with the primary action stated first and the sibling contrast immediately after. Every clause carries information the agent needs.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. For a simple two-parameter toggle the description covers the action, the reverse action, and the main alternative; only edge behavior (invalid/already-archived id) is unaddressed, which is minor at this complexity.

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

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

Schema description coverage is 0%, so the description must compensate, and it only partially does: it explains the boolean semantics ('bring it back with archived: false', implying default true archives). prediction_id has no added explanation beyond its uuid format. With two parameters and only one clarified, this is adequate but incomplete.

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 clear action on a specific resource (archiving a virality prediction) using the metaphorical 'put a prediction away', and explicitly distinguishes itself from the irreversible delete_virality_prediction. It is understandable, but the verb is colloquial rather than the literal 'archive', so it lands just short of a maximally crisp verb+resource statement.

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 real routing guidance: use this to hide a prediction reversibly, and use delete_virality_prediction when permanence is intended. It also tells the agent how to reverse the operation (archived: false). It stops short of stating when one would archive (e.g., hiding from listings) or any preconditions on the prediction's state.

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 declare destructiveHint=true and idempotentHint=false, so the safety profile is already covered. The description adds real behavioral value beyond that: it discloses the credit-refund behavior ('credits held for work that had not started are released') and the fact that only not-yet-started work is refunded. It stops short of saying whether cancelled in-flight work can be resumed or retried.

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

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

Two tight sentences with zero filler; the primary behavior is front-loaded and the scoped variant is appended as an alternative. Every clause earns its place.

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

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

An output schema exists, so return values need not be described. For a destructive, non-idempotent operation with two parameters, the description covers scope and credit release adequately; the only gap is whether the cancellation is reversible or how the caller confirms completion.

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

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

Schema description coverage is 0%, so the description must carry the load. It meaningfully explains the optional 'video' parameter by describing the two modes (whole board vs. one named video's render), which is exactly the semantic distinction the bare integer schema lacks. 'storyboard_id' is only implied as the target board and gets no explicit 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?

The description states a specific verb (stop/cancel) and resource (a storyboard's in-flight generations and renders), and it clarifies the two scopes of cancellation. It does not explicitly disambiguate itself from delete_storyboard or undo_storyboard, so an agent must infer that this halts work without removing the board.

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

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

Usage is implied rather than stated: the agent learns it cancels everything on the board by default or a single video's render 'when you name it.' There is no explicit when-to-use/when-not guidance and no mention of the relevant siblings (delete_storyboard, undo_storyboard, cancel_workflow_run) that a caller might confuse this with.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds important behavioral context beyond annotations: 'A video already verified is retained.' This tells the agent that cancellation does not remove a verified video, which is non-obvious and valuable. It does not cover auth requirements or what happens to the import record itself, 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, zero waste. The purpose is front-loaded, followed immediately by the key retention behavior. Every sentence earns its place and there is no redundant or vague 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 simple one-parameter cancel operation with rich annotations and an output schema, the description gives enough to call the tool correctly in most cases: it states the purpose and the key retention rule. The only gap is parameter-level detail, which is not covered in the schema and not compensated here. That keeps it from a 5.

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

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

Schema description coverage is 0% and the description never mentions import_id, its UUID format, or any constraints (e.g., must be an unfinished import's ID). With low coverage, the description is expected to compensate for the schema gap, but it provides no parameter semantics at all. The parameter name is intuitive, but that is not enough to reach a 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 states a specific verb and resource: 'Cancel an unfinished import.' It is clear what the tool does and distinguishes the target as an unfinished import. However, it does not explicitly name sibling alternatives or contrast with tools like retry_video_import or cancel_workflow_run, so it stops 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?

Usage is implied by the phrase 'unfinished import' and the note that a verified video is retained, which gives a condition for when cancellation is appropriate. But there are no explicit when-to-use/when-not-to-use statements or named alternatives (e.g., retry_video_import for failed imports), so guidance is only implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered without the description. The description adds nothing beyond that – it does not say what cancellation destroys (pending steps, outputs), whether it is reversible, or how in-flight work is handled.

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 single sentence is front-loaded and wastes no words, but its brevity reflects under-specification rather than disciplined concision. Nothing is said that the tool name and title do not already say.

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?

An output schema exists, so return values need not be explained. However, for a destructive mutation in a family of workflow-run tools, the description omits all operational context an agent would need to call it correctly.

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

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

There is one required parameter, run_id, with 0% schema description coverage, so the description carries the full burden and supplies nothing. Only the schema's uuid format hints at the expected value, which is why this is not a 1.

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 pairs a specific verb ('Cancel') with a specific resource ('workflow run'), so the agent knows exactly what operation it performs. It does not distinguish this tool from the closely-related siblings resume_workflow_run, retry_workflow_run, rewind_workflow_run, or get_workflow_run, which all operate on the same resource.

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 guidance on when to cancel versus resume, retry, or rewind a run, and no mention of prerequisites such as run state. The agent is left to infer usage entirely from the name.

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 supply negative hints (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the description's disclosure that it consumes an existing account asset, returns a ranked list, spends no credits, and produces no audio is genuinely additive. The word 'Read' sits slightly uncomfortably with readOnlyHint=false, but the description never claims the tool is non-mutating, and its concrete claims (no credits, no audio) are consistent with destructiveHint=false. It does not say whether the ranking is deterministic or recomputed per call, which matters given idempotentHint=false.

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

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

Two short sentences, zero padding, front-loaded with the action and output, with the cost/behavior caveat in second position. Every clause earns its place.

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

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

An output schema exists, so return-shape explanation is not required, and the handoff sentence covers the essential workflow. However, with output schema present the definition still leaves the required 'model' parameter and the upload_id/generation_id choice unexplained, which is a real gap for a 3-parameter tool.

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

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

Schema description coverage is 0% and there are 3 parameters, so the description carries the full burden — and it does not name or explain any of them. 'A portrait already in the account' vaguely gestures at upload_id/generation_id but never distinguishes the two input paths, and the required 'model' enum (six TTS engines) is completely unaddressed, leaving the agent no basis for choosing one.

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

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

Specific verb + resource ('Read a portrait ... return the voices that suit it, best first') with a clear statement of the output ordering and the downstream consumer (generate_voiceover). An agent can tell this apart from generate_voiceover, change_video_voice, and list_models 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?

The description makes the usage context explicit by naming the follow-on tool: the returned ids 'pass to generate_voiceover'. It also sets boundaries in a negative sense ('spends no credits and makes no audio'), which tells the agent this is the cheap selection step rather than the rendering step. It does not state exclusions or prerequisites for the alternative portrait sources (upload_id vs generation_id).

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 declare non-destructive, non-read-only, non-idempotent, closed-world. The description goes further by disclosing that a NEW generation is produced (originals preserved), that account entitlements/credits are consumed, and that the operation is asynchronous with get_generation as the wait mechanism. It omits any statement about failure modes or whether the source clip is consumed.

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

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

Three sentences, each earning its place: what it does, the input constraint, the follow-up. The core action is front-loaded with no filler.

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

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

An output schema exists, so return values needn't be described, and the async polling path is covered via get_generation. Remaining gaps are the meaning of the two source variants and any permission/ownership requirement for the clip, which are minor but real for a mutation tool.

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

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

Schema coverage is only 33%: 'subject' has a description but 'source' and 'voice_id' do not. The description compensates by stating the mutual-exclusivity constraint between voice_id and subject (not encoded in the schema) and defining subject as 'a Subject with an ElevenLabs voice'. It does not explain the two source variants (upload vs generation) that the anyOf offers.

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 the speech voice in an owned clip'), names the voice provider (ElevenLabs), and specifies the output artifact ('saving a new generation'). This is clearly distinguishable from siblings like cast_voice (binds a voice to a Subject) and generate_voiceover (creates speech from scratch).

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 hard selection rule for the two optional inputs ('Pass exactly one of voice_id or subject') and points at get_generation for waiting, but never states when to choose this tool over cast_voice or generate_voiceover, nor any prerequisite about the clip being owned. Usage is implied rather than guided.

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-readOnly, non-destructive, non-idempotent. Beyond that, the description discloses the actual verification behavior (checking declared size, type and checksum) and the post-condition that the upload becomes bindable — real behavioral value. It omits failure handling, i.e. what happens if verification fails, which keeps it out of 5 territory.

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 front-loaded sentence with no filler, leading with the verb. Slightly dense phrasing ('return the upload ready to bind to a generation') 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?

An output schema exists, so return format is covered elsewhere, and annotations cover the safety profile. Still, for a non-idempotent state transition the description says nothing about retry/failure behavior or what the caller should do if verification fails, leaving a meaningful 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 0% across four parameters, and the description compensates poorly: it never mentions upload_id, width, height, or checksum_sha256 by name, and it is unclear why a completion step takes width/height (presumably dimension overrides). The word 'checksum' is the only indirect tie to any parameter.

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 set (verify, return) on a specific resource (an upload), and the finalizing framing ('ready to bind to a generation') distinguishes it from create_upload/get_upload/update_upload. It stops short of naming or contrasting with those siblings explicitly, so it lands at 4 rather than 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?

The phrase 'return the upload ready to bind to a generation' implies this is the terminal step after bytes are sent, which is usable context. However there is no explicit when-to-use/when-not guidance and no reference to create_upload (starting an upload) or get_upload (inspecting one), so usage is only inferred.

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

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

Annotations only declare the generic mutation profile (readOnly=false, idempotent=false, destructive=false). The description adds high-value specifics beyond that: no credit spend, the frame is cut by the renderer (async, hence polling get_storyboard), and the operation is a single undo step — exactly the operational traits an agent needs.

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

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

Four tight sentences, front-loaded with the core action, then prerequisites, cost/async behavior, and undo granularity. Every sentence adds information an agent can act 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?

With an output schema present, return values need no explanation, and the description covers the remaining unknowns: cost, prerequisite state, asynchronous completion, and undo scope. 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 0%, so the description must carry the burden, and it does: it explains that `scene` receives the still and `from_scene` is the source that must already have a clip. `storyboard_id` is left implicit, which is a minor gap but easily inferred.

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 ('give a scene a still that is the LAST frame of another scene's clip') plus the intent (the next shot picks up where the previous ended). This clearly distinguishes it from siblings like extract_video_frame, generate_scene_images, and match_scene_motion.

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 hard prerequisite: `from_scene` must already carry a clip, generated or uploaded, and tells the agent to poll get_storyboard for the still to land. It does not explicitly name competing tools to avoid, so it falls short of a full when/when-not/alternatives statement.

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 context beyond annotations: rendering costs no credits, returns immediately with a generation id, and is asynchronous, which matters given idempotentHint=false and readOnlyHint=false. It also discloses the text-shrink behavior and the 24px floor, i.e. what happens when input exceeds the band, which is genuine behavioral detail.

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

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

Purpose and the page-count constraint are front-loaded, and every clause carries information (limits, credit cost, async flow, shrink guard). It is a single dense block of run-on sentences, though, which slightly hurts scannability.

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 tool with a fully described nested schema and an output schema, the description covers what structured fields cannot: the async render pipeline, the follow-up calls, and the credit cost. Nothing needed to invoke it correctly or to retrieve its output is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot convey: one style applies to the whole set rather than per page, text sits in top/middle/bottom 'reading zones', and an inset is a real screenshot in a phone frame. Minor gap: 'canvas' and 'focus' semantics are left to the schema.

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

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

States a specific verb and resource ('Render 2–20 pictures, in order, into one carousel: an image set in the library, one picture per page'), which distinguishes it from generate_image or edit_image siblings. The output artifact (a library image set with ordered pages) is concrete enough that an agent can tell it apart without reading 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 constrains sources to a ready image generation or an upload, and routes the agent through the follow-up flow (get_generation, then get_download_url). It lacks an explicit 'use X instead when...' exclusion against siblings like generate_scene_images, which keeps it below 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 the write/safe profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description still adds real context beyond them: the row stays private, catalog rows never expose their steps, `model_kind` must agree with the last step's output, and validation errors name the offending field.

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

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

Purpose is front-loaded in the first clause, and the routing guidance comes before the deep detail. It is dense and the embedded run-recipe JSON is bulky, but that example is directly actionable grammar rather than filler, so it earns its place.

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

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

For a 14-parameter, deeply nested tool with an output schema present, the description covers the critical decisions (which action takes which payload, privacy, model_kind validation, a runnable `definition` example) without needing to restate return values. Only the peripheral metadata params are left to the schema.

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

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

Schema description coverage is only 7%, so the description must carry the parameter burden. It does well on the decisive action-gated params (action values and their required companions model_id/config/definition/writer, plus model_kind), but leaves name, tags, highlights, cover_shape, allowed_models, recommended_model and suggested_params unexplained beyond their raw schema types.

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

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

States a specific verb and resource ('Author a private recipe from nothing') and immediately specialises the three modes of the tool via `action`. An agent can distinguish create_recipe from sibling creation tools (save_recipe_from_generation, remix_recipe) 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 names the alternatives and the condition selecting each: save_recipe_from_generation for finished generations, remix_recipe for copying catalog rows, get_recipe to inspect a working arrangement before authoring, publish_recipe/submit_recipe for the downstream lifecycle. This is textbook when/when-not guidance.

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

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

Annotations only say it is destructive, non-idempotent, and open-world; the description goes well beyond by disclosing that the URL is returned exactly once and is unrecoverable, that expiry ranges from one minute to thirty days (absent = no expiry), that indexable defaults to off so links stay unlisted, and that no credits are spent. The one-shot/unrecoverable nature is critical and is not in any structured field.

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

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

The most important constraint (single-use URL, hand it over now) is front-loaded, and the rest is packed into two dense sentences with little waste. It is long but nearly every clause conveys a distinct rule, so only mild trimming is possible.

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?

An output schema exists, so return structure need not be explained, and the description still covers the one-shot return behavior, expiry semantics, most settings, default privacy behavior, and cost. For a 3-param, nested-object, destructive tool this is sufficient to call it correctly.

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

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

Schema description coverage is only 33%, so the description must compensate, and it largely does: it explains expires_in_seconds' bounds and no-expiry default, and maps most settings fields (title, caption, download, made_with as provenance level, theme, indexable) to their meaning. It leaves remix, branding, and view_count unmentioned, so it stops short of fully covering the surface.

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 ('Mint a public permalink') and enumerates exactly what can be shared (a ready generation, a verified upload, or a whole group). That scope, plus the same-turn handoff note, clearly separates it from siblings like get_download_url, list_share_links, and revoke_share_link.

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 operating context — ask before sharing on someone else's behalf, and hand the URL to the user in the same turn — and hints at the revoke alternative ('nothing can recover it later, only revoke it'). It never explicitly names a sibling to prefer for other cases, so 4 rather than 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 give the generic profile (non-read-only, non-destructive, non-idempotent), but the description adds substantive behavior: omitted scene fields fall back to the title and a subtle motion drift, a style name that misses produces nothing, `from_media` fixes the frame from the first file, multi-scene boards are committed in a single write, and no credits are spent at this step.

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 three usage modes, then dense routing and fallback rules with almost no filler; the literary opening phrase is the only mildly rhetorical sentence. Backticked parameter names keep it scannable despite the length.

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

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

With an output schema present, return values need no explanation, and the description covers mode selection, fallbacks, credit behavior, and the downstream render/edit steps. It omits operational bounds (60-scene and 250-item caps) and any permission or prerequisite notes, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is low (17%), so the description must carry the load, and it does for the mode parameters: cast values are subject names, scenes are written in order and chained, settings scope applies only to written scenes and analysis, and from_media semantics are clarified. It does not explain per-scene fields such as hold_motion, duration_seconds bounds, or the item limits, which remain schema-only.

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

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

States a specific verb and resource and enumerates the three distinct creation modes (written scenes, existing media, prior analysis), which an agent can immediately map to the `scenes`, `from_media`, and `from_analysis` parameters. It also contrasts itself with edit_storyboard, generate_scene_images, and apply_storyboard_template, so it is distinguishable from siblings.

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

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

Explicitly routes the agent: use set_scene_clip on edit_storyboard for owned footage, generate_scene_images for new stills, add_sound for voice-over/music before rendering, and list_subjects to resolve cast names. It also states the condition under which settings must be applied later via edit_storyboard for `from_media` boards.

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=false, idempotent=true, destructive=false. The description adds genuinely non-structured context: the consent/rights requirement, the fact that identity images propagate the face into every later tagged generation, and that an image-less subject still travels as name+description. It never contradicts 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?

Front-loads the core purpose, then layers usage, consent, and image behavior with almost no waste. The quoted example ('no mouth, only a stitched black nose') is illustrative rather than padding, though the prose is denser and more stylized than strictly necessary.

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

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

With an output schema present, return values need no explanation, and the description covers the tool's distinctive behaviors (reuse, image propagation, consent). The enum semantics of 'kind' and the distinctions among cover/sheet/avatar are left entirely to the schema, a minor gap for a 10-parameter tool.

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

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

Schema coverage is 70%, so the baseline is 3. The description adds real meaning for the identity images ('the face that travels') and the description field (write what it lacks as well as what it has), but says nothing about name, kind, tags, cover, sheet, avatar, voice, or prompt_fragment, leaving the schema to carry those.

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 ('Name an identity so it can be reused') and clarifies the reusable-identity concept clearly. It does not distinguish itself from siblings like update_subject or list_subjects, leaving the agent to infer the create-vs-modify boundary.

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

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

Gives concrete when-to-use guidance ('Offer one when something the user brought appears in a second generation, never unasked') and a clear constraint ('Only for people the user has the right to depict; a real person needs their consent'). It lacks any explicit routing to update_subject for existing subjects, but the creation context is well covered.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered; the description adds the genuinely non-obvious behavior that quote=true prices the decisions and changes nothing, i.e. a dry-run mode. It also states the cardinality invariant (decisions must cover exactly the open positions, once each), which is behavioral rather than structural. It does not describe what retry/edit triggers downstream in the engine.

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

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

Three sentences, zero filler, purpose and action set front-loaded, then the sourcing precondition, then the quote modifier. Every clause carries distinct 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?

Return values need not be explained because an output schema exists. The description covers the preconditions, the action space, the coverage invariant, and the dry-run flag, which is enough for correct invocation. Minor gap: no statement of which run states are valid targets or what happens to skipped items.

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

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

Schema description coverage is 0%, so the description has to carry the load, and it does: it explains the three action values in prose, defines `position` as the open position from recovery.items (not just an integer index), and defines `quote` as a non-mutating price check. `revision` is sourced to get_workflow_run's recovery payload; only run_id and step_id are left to obvious inference.

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

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

States a precise verb+resource ('Decide workflow items' → answer an engine run paused on `items`) and enumerates the exact choice space: retry, edit prompt and retry, or skip. This clearly separates it from the sibling run-lifecycle tools (retry_workflow_run, resume_workflow_run, cancel_workflow_run) which act on the run as a whole rather than on individual failed items.

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 triggering condition ('an engine run paused on items') and the required prerequisite workflow: read open positions and the current revision from get_workflow_run's `recovery.items`, and cover exactly those positions once each. It also flags the non-mutating preview path via quote=true, but never names a sibling alternative for agents who actually want to retry or resume the whole run.

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 adds value beyond structured data: it discloses that associated media is destroyed alongside the generation and that no credit refund is issued, both of which are behavioral facts the annotations cannot express.

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

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

Two sentences, both earning their place, with the permanence warning front-loaded before the secondary consequence. 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?

An output schema exists so return values need no explanation, and annotations cover the destructive/idempotency profile. The description supplies the key extras (media cascade, no refund); only a note on what happens on repeat or invalid IDs is missing, which is a minor gap.

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

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

One required parameter with 0% schema description coverage, so the description carries the burden and does not address generation_id at all. The parameter is nonetheless self-evident from its name and uuid format, so the gap is minor and a 3 is appropriate.

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

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

States a specific verb ('Permanently remove') and resource ('a generation and its media'), and the scope of collateral removal is explicit. Among siblings like delete_folder, delete_upload, and delete_subject, the resource is unambiguous and no schema opening is needed to tell what is deleted.

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 consequences ('cannot be undone', 'refunds nothing') implicitly steer usage away from mistaken or speculative deletes, but the description never states when to use this versus alternatives (archive, update_generation, or regenerate_generation). Usage is implied by the plain delete semantics 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?

Goes well beyond the destructiveHint=true annotation by disclosing permanence, the exact cascade (cover and public page removed), what survives (generations made with the recipe are kept), and the ownership precondition. These are precisely the facts an agent needs before firing an irreversible 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, front-loaded with the core action, then the cascade, then the exclusions. Every sentence carries distinct information with no repetition of the title 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?

An output schema exists, so return values need no explanation. For a single-parameter destructive tool the description covers action, cascade, preservation, ownership, and the blocked case, leaving nothing an agent needs to call it correctly.

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

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

Schema description coverage is 0%, so the description technically must compensate and does not mention recipe_id at all. Mitigating factor: the single parameter is a self-evident uuid identifier whose name and format fully convey its meaning, so no real 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 (permanently delete) and resource (recipe you own) plus the cascade scope (cover and public page). It also carves out an exception case (curated rows) and clarifies side effects, so an agent can distinguish this from delete_folder, delete_generation, delete_storyboard without opening any schema.

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

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

Provides an implied when-not condition ('A curated row cannot be deleted here'), which is useful routing information. However, it names no alternative tool or path for the curated case, and gives no explicit when-to-use guidance versus update_recipe or archive-style siblings, leaving usage largely inferred.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds real context beyond them: the cascade covers scenes and history, in-flight rendering/filming is halted, and previously exported clips/stills in the Library are explicitly preserved. That survival detail is the kind of thing an agent cannot infer from annotations or schema.

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

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

Two dense sentences, front-loaded with the destructive scope and then the routing advice. 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?

Output schema exists so return values need no explanation, and the description covers the cascade, the interrupted work, the surviving exports, and the safer alternative. For a single-parameter destructive tool, nothing material 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 (storyboard_id, a UUID) and schema description coverage is 0%, so the description contributes nothing about it. The name and uuid format make it largely self-evident, which keeps this at the baseline rather than below it.

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 (delete) and resource (storyboard/film) plus the exact blast radius: the board, its scenes, and its history. It also distinguishes itself from siblings by naming edit_storyboard's archive op and delete_storyboard_template's separate scope.

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

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

Gives an explicit alternative (edit_storyboard's `archive` op) and the precise condition that selects this tool instead: only when the user actually asked for deletion. The reversible-vs-permanent tradeoff is stated outright.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds real value beyond the annotations by scoping the blast radius: existing films made from the template are untouched, which tells the agent exactly what is NOT destroyed — a detail annotations cannot express.

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

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

Two short sentences, action first, scope caveat second — zero wasted words and well front-loaded. It is arguably terse to the point of under-specification, but nothing in the text is redundant.

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

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

An output schema exists so return values need not be described, and annotations cover destructiveness and non-idempotency. Combined with the blast-radius note, the agent has what it needs to call the tool; the only meaningful gap is that nothing states whether deletion is permanent or how to obtain the template id.

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

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

Schema description coverage is 0% for template_id, and the description says nothing about how the template is identified or where the id comes from (e.g., list_storyboard_templates). A single obvious UUID identifier limits the damage, but the description does not compensate for the empty schema documentation.

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 template"), and the follow-up sentence about films started from it clarifies this is the storyboard template specifically, distinguishing it from delete_storyboard. It stops short of naming sibling delete tools (delete_recipe, delete_folder, delete_subject), so an agent must rely on the tool name for the rest of the disambiguation.

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

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

No when-to-use guidance, no prerequisites, and no reference to alternatives such as apply_storyboard_template, list_storyboard_templates, or delete_storyboard. The only implicit signal is that the template itself is removed while derived work is preserved, which is a side effect, not usage direction.

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, but the description adds the details an agent actually needs before firing a destructive call: exactly what is destroyed (strip, description, voice binding), what survives (generations), and that the effect is permanent and irreversible. That is real added value beyond the structured hints.

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

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

Three short sentences, front-loaded with the action, then the preservation rule, then the permanence warning as a one-word closer. Nothing is redundant and nothing buries the destructive nature of the call.

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?

An output schema exists, so return values need not be described. For a single-parameter destructive tool with strong annotation coverage, the description supplies the missing pieces: scope of destruction, what is preserved, and irreversibility. Nothing an agent needs to invoke it safely 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?

There is one required parameter, subject_id, with 0% schema description coverage, so the description carries the burden and does not fully meet it: it never says what identifier to pass or that it comes from list_subjects. It only names the entity being deleted, which is inferable from the tool name. Adequate but with a clear 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 ("Delete a Subject") and immediately scopes it: the named identity goes, the generations it appeared in stay. That scope statement is what separates it from siblings like delete_generation or delete_storyboard, 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?

The blast-radius sentence implicitly tells the agent this is not the tool for removing a generation, and it clarifies what deletion does not affect. But it never names an alternative (delete_generation, update_subject) or states a precondition such as needing the subject to be unused or unshared, so usage is only implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavior beyond that: the deletion is permanent including the underlying bytes, and there is a dependency guard whose refusal message identifies the blocking resource — useful for interpreting failures. No auth or rate-limit context is given.

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 irreversible nature is front-loaded before the refusal condition. Every clause earns its place.

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

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

An output schema exists, so return-value detail is unnecessary, and the description covers the two things an agent most needs for a destructive call: permanence and the dependency guard. Only the absence of any guidance on how to clear the blocking dependency keeps it from a 5.

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

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

Schema description coverage is 0% and the description never mentions upload_id, so it adds no parameter meaning. With only one required parameter whose name is self-explanatory and whose uuid format is declared in the schema, the invocation is still unambiguous, which keeps this at the minimum-viable level rather than a severe 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 ("Permanently delete an upload") and adds scope ("and its bytes"). The resource name cleanly separates it from the many sibling deleters (delete_generation, delete_subject, delete_recipe, delete_storyboard), so an agent can route to it 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 an explicit precondition for failure — it is "refused while something still uses it — a scene, a Subject, a composition" — which tells the agent when this call will not work and what the blocker looks like. It stops short of naming an alternative route (e.g., detach the scene or Subject first), so it is clear context without explicit alternatives.

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 adds genuinely new context by clarifying what is NOT destroyed ('the video it read is untouched'), which resolves a real ambiguity about blast radius for a delete 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?

Two short sentences, front-loaded with the action and immediately followed by the scope clarification. Every clause earns its place; nothing is 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?

An output schema exists, so return values need not be explained, and the annotations cover reversibility and safety. The remaining gap is the missing delete-vs-archive guidance, which matters because a sibling handles the same entity non-destructively.

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

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

Schema description coverage is 0% for the single required prediction_id, so the description carries the burden of explaining it — and it says nothing about the parameter, its format, or where the ID comes from. Only the name and the uuid format in the schema give the agent anything to work with.

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 ('Delete a prediction'), and 'for good' implies permanence. It does not, however, name or distinguish itself from the sibling archive_virality_prediction, which is the nearest alternative for the same entity.

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?

'Delete a prediction for good' hints that this is irreversible, but the description never states when to choose it over archive_virality_prediction or that it is the permanent counterpart to archiving. The agent must infer the routing decision from the tool name alone.

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

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

Annotations cover only safety flags, and the description adds genuinely new behavioral facts: the result is filed as the next version of the original, model/aspect ratio/setting are inherited unless overridden, a source made by a model that cannot read a reference image is silently migrated to one that can, and it costs a normal image generation. These are non-obvious consequences an agent should know before invoking.

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

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

Four sentences, front-loaded with the core meaning before routing and inheritance details. There is mild redundancy — the idea that 'the picture is the input' is stated twice — but each sentence still 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?

An output schema exists, so return values need no explanation. Between the routing rule, the instruction-authoring guidance, the inheritance/defaulting behavior, the model-migration caveat and the cost note, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is only 20%, so the description must carry the load, and it does for `instruction` ('says only what changes', don't restate the prompt) and for the inheritance semantics of `model`, `aspect_ratio` and `setting`. `generation_id` is only implied via 'the picture itself is the input' and 'the source', leaving its role slightly less explicit, but the overall gap is well covered.

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 precise verb and resource ('Change one thing about an image already in the account, keeping everything else') and immediately frames it as the studio's refine step. It distinguishes itself explicitly from the most confusable sibling, generate_image, 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?

The description states when to use it and names the anti-pattern directly: 'Use this — never a second generate_image with a reworded prompt — whenever someone asks for the same picture with something different about it.' It also explains why the alternative fails (different composition/lighting), which is a concrete selection criterion rather than vague guidance.

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

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

Adds substantial behavior beyond the annotations: sequential op resolution against the evolving board, shared undo-step grouping for consecutive writes, origin-guarded undo, fail-fast semantics where prior ops stand and the receipt names the failing op, and the soft/reversible delete guarantee. It also clarifies that a failed batch may write nothing and therefore leaves nothing to undo.

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 ordered-list and numbering semantics, then behavior, then edge cases, which is the right order for this tool. It is dense and some sentences are run-on, but given 25 ops and 0% schema description coverage the length is largely earned.

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?

An output schema exists so return values need not be explained, and the description still usefully describes the failure 'receipt'. For a high-complexity mutation tool it covers ordering, undo, error, credits, and delete-join semantics, though the op catalogue itself is left entirely to the schema.

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

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

Schema description coverage is 0% and the schema defines ~25 op variants, so the description cannot document the fields. It does add the single most important semantic — scenes are addressed by 1-based number and each op resolves numbers against the board as it stands after the previous one — which the schema does not convey. The per-op fields and reference types remain undocumented outside the schema, so this is baseline-plus rather than 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?

States a specific verb and resource — 'Apply an ordered list of edits to a film and get the board back' — and the scope is unambiguous. It implicitly separates this tool from read/render siblings by describing the mutation semantics and by naming undo_storyboard as the reversal path.

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

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

Gives clear context: nothing spends credits, ops like set_scene_clip and add_sound are for attaching existing media 'before rendering', and undo_storyboard takes back the latest step. It stops short of explicit when-not conditions or naming a sibling (e.g. render_storyboard) as the alternative, so it is strong but not fully routing.

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 asserts 'Exporting the same video twice returns the same clip rather than a second one, and costs nothing', which is a direct claim of idempotent, side-effect-free repeated invocation, while the annotations declare idempotentHint=false. That conflict would mislead an agent deciding whether a retry is safe, and the rule for contradicting annotations applies even though the rest of the description (reference identity with list_media, no cost) is genuinely informative.

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

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

Three short sentences, front-loaded with the action and its result, then the interoperability point, then idempotency/cost folded efficiently into one clause. The 'bridge off the board' flourish is minor flavor rather than 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?

An output schema exists, so return values need not be spelled out, yet the description still explains the returned reference's identity and where it can be reused. The remaining gap — that a completed/current cut must exist before exporting (only hinted at by the render_id schema note) — is covered implicitly by 'a finished film'.

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

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

Schema description coverage is only 33% (render_id alone is documented) and the description contributes nothing about storyboard_id, video, or the render_id/current-cut distinction. With low coverage the description is expected to compensate for the undocumented parameters, and it does not.

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 concrete verb and resource — copying a finished film into the library as an ordinary clip and returning its link — and positions it against the rendering layer ('the bridge off the board'), so an agent can separate it from render_storyboard and list_media 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?

Usage is implied rather than stated: 'a finished film' and 'the bridge off the board' signal this runs after a render completes, but there is no explicit prerequisite, no when-not-to-use, and no alternative named (e.g., get_download_url vs. export). The downstream consumers (join_clips, create_subject) are mentioned, which is helpful but is about what happens after, not when to pick this 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 indicate this is a non-read-only, non-destructive, non-idempotent operation. The description adds important behavioral context: it costs no credits, uses account storage, produces a new image generation, and explains the face-drift limitation for talking-head workflows.

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 output, then adds cost, async behavior, chaining guidance, and the speech exclusion. Every sentence contributes useful information 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 annotations, an output schema, and two parameters, the description covers the action, output, cost, storage use, async retrieval, chaining workflow, and key exclusion. It gives an agent enough context to select and invoke the tool 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?

With 0% schema description coverage, the description must compensate. It clarifies that the source is an owned video and that position is first or last, but it does not explain the source object's upload_id versus generation_id structure or the default position behavior.

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

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

The description states a specific verb and resource: save the first or last decoded frame of an owned video as a new image generation. It clearly distinguishes the output as an image generation and scopes the input to owned videos, making the tool identifiable among siblings.

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

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

It explains when to use the extracted frame: carry the last frame into generate_clip for longer sequences, then join_clips. It also gives an explicit exclusion ('Not for speech') and notes that get_generation waits for the result.

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 context the annotations don't carry: the call spends credits, returns immediately (so results must be fetched later), and eleven-music silently ignores sample_rate, bitrate, and lyrics rather than erroring. Annotations already cover mutation/safety, so this is a solid supplement, though permissions and any credit amount/limit are not stated.

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 purpose, the credit cost, and the async behavior in two short sentences before a compact model table. The only minor waste is repeating the model display names after the IDs, which is harmless.

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?

The presence of an output schema means return values need no explanation, and the cost/async facts are covered. But for a nine-parameter generation tool, the description omits how lyrics_optimizer and is_instrumental behave and how the prompt is interpreted, leaving meaningful ambiguity.

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 11%, so the description must compensate, and it does so for the model-specific parameter interactions (lyrics, lyrics_optimizer, sample_rate, bitrate). However, lyrics_optimizer, is_instrumental, audio_format, and the meaning of the prompt are left unexplained, so several of the nine parameters remain opaque.

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 — start a music generation from a creative brief — which is unambiguous against siblings like generate_image, generate_voiceover, and generate_clip. The model list further narrows what the tool produces and under which engine.

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

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

Gives selection guidance at the model level: eleven-music is instrumental only, takes no lyrics or lyrics_optimizer, and always emits MP3, which effectively tells the agent when to pick each model. It never names an alternative tool or a when-not-to-use condition, so it stops short of full routing guidance.

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

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

Annotations declare only destructive=true, non-idempotent, non-read-only. The description adds material behavior the annotations cannot: it spends credits, is asynchronous and returns on dispatch rather than completion, enforces a dependency ordering around anchored recurring faces, and caps output per call with the overflow returned as remaining scenes. This is exactly the extra context the annotations leave out.

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

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

Front-loaded with purpose, then cost/dispatch behavior, then the ordering rule. Mostly dense and useful, though the middle sequence ('Ask for the open wave, look at it, create_subject from the anchor, then the next') is compressed to the point of being cryptic.

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 high-complexity, credit-spending, async tool with an output schema present, the description covers the operational model an agent needs: cost, dispatch semantics, polling target, and ordering. The remaining gap is the undocumented reference/idempotency parameters rather than return values.

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

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

Schema description coverage is 0% across 6 parameters, so the description must carry the burden. It explains quote (price the batch against balance without generating) and implies scenes, but references, reference_scenes (max 4), storyboard_id, and idempotency_key get no explanation at all — the agent is left guessing at the reference-object shape and the retry 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 concrete verb+resource ('Make the still pictures of the scenes you name') and pins it to a specific artifact type (scene stills) distinct from generate_image and animate_scenes. An agent can route to it 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 routes the workflow: dispatch then poll get_storyboard, use create_subject from the anchor still before the next wave, and use quote to price without producing. It also states the ordering gate (a scene is refused until its turn) and the concurrency cap, which tells the agent exactly when this call will and won't succeed.

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 behavior the annotations do not carry: that the call spends credits, that it returns immediately rather than blocking, per-model cost and character ceilings, and the stitching (continues_from) semantics for keeping a voice continuous across separately generated lines. The idempotency_key note (reuse to retry without spending twice, different args refused) clarifies spend behavior, which is the material risk here; annotations only say destructiveHint=false and idempotentHint=false, which is consistent with a non-destructive but credit-consuming 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-loads the action, its cost, and its non-blocking nature in the first sentence, then routing rules, then the script-consistency caveat, then the model roster. The roster is dense but every line carries decision-relevant data (cost, ceiling, default voice, supported controls) rather than filler.

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

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

For a 10-parameter generative tool with an output schema, the description covers cost, latency, voice selection strategy, script continuity, and model trade-offs — enough to call it correctly without reading other tools. It omits error/retry behavior beyond the idempotency hint and any note on retrieving the resulting generation, which the output schema and get_generation presumably cover.

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 40%, so the description must compensate, and it largely does: the per-model roster documents default voices, character limits, and which controls (language, speed, emotion, style prompt, custom voice ids) each model supports. It does not explain the speed range (0.1-5) or emotion enum values, and leaves language_code format unspecified, but the enums in the schema cover the discrete choices.

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 and resource ("Start a voice-over generation from text") and immediately scopes it as an async, credit-spending operation. It is clearly distinguishable from siblings such as change_video_voice or cast_voice, which operate on existing media rather than producing a new generation.

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

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

Gives explicit routing rules for the core parameter choice: pass `subject` to inherit a bound voice (with the caveat that model/voice/style/language may then not be passed), or pick `model`/`voice` yourself, or omit both for the default. It also gives a strong consistency rule for multi-line scripts (generate once and cut, or keep model/voice/delivery fixed). It does not name sibling tools or state when-not to use this tool, so it stops short of a 5.

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

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

Annotations only declare this is a non-readOnly, non-idempotent, non-destructive write. The description goes well beyond them by disclosing concrete runtime behavior: RECIPE_MODEL_UNFIT with a reason, automatic snapping of pinned settings (ratio/resolution/length/format) to the nearest supported value, and clip-shape coercion. It omits cost/credit implications, which would be valuable for a generation tool.

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

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

Purpose is front-loaded, but the remaining text is a dense run-on of em-dash and parenthetical clauses that is heavy to parse. Most clauses carry real information (subject preference, model fitness rules), yet the packaging could be split into cleaner sentences or bullets.

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

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

For a 5-parameter tool with nested objects and an output schema (so return values need not be described), the description covers the essential behavior: recipe inputs, subject binding, model override rules, and failure semantics. It is nearly complete, missing only practical notes like cost or the required recipe_id acquisition path.

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

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

Schema description coverage is 0%, so the description carries the full burden and largely succeeds: it explains creative_prompt (a brief on reprompt recipes), choices (one value per get_recipe choice), model_id (default vs. tested models and fitness failure), and the nested inputs shape including media binding and the subject contract. It does not surface schema constraints like maxItems/minItems, but meaning is well conveyed.

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 states a specific verb, resource, and scope: create ONE image or clip using a guided recipe (arm or reprompt). This cleanly distinguishes it from siblings like generate_image, generate_clip, and start_recipe_run without the agent needing to open any schema.

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

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

It clearly establishes the workflow prerequisite — supply creative_prompt and one value per choice that get_recipe declares — and explains the model-selection path (use allowed_models vs. another model of the same medium). However, it never explicitly states when NOT to use this tool (e.g., vs. plain generate_image), leaving that routing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: the interim default (an image takes the best tier), the null selected_tier for clips awaiting a decision, and the fallback when a tier is unaffordable. It does not cover latency or whether benchmark data is cached, so it stops just short of full transparency.

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?

Every clause carries decision-relevant information — pricing, defaults, the ask-once protocol, the affordability fallback, and the recipe preference — and the core purpose is front-loaded. The cost is that it arrives as one dense run-on paragraph, which makes the decision rules harder to scan than they need to be.

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

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

An output schema exists, yet the description still names the key fields an agent must branch on (affordable, free_now, selected_tier, image_priority/clip_priority), and it covers the full decision workflow including the ask-user-once policy and recipe handoff. Nothing an agent needs to call this 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 0%, so the description must carry the load: it fully explains `task` ('also get the catalog recipes made for that job', with the recipe follow-up path) and ties `kind` to priorities and selected_tier. It only illustrates kind with image and clip, leaving video/tts/music behavior to inference from the enum.

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 with full scope: 'Which model to use for a job, in three tiers (best, middle, cheapest), priced for this account', and enumerates the returned signals (credits per reference request, affordable, free_now, priorities, selected_tier). It is clearly distinguishable from siblings like list_models or quote_generation because it is account-priced and returns a selected tier per task.

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

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

Explicitly instructs 'Call it before choosing a model and take the selected tier', defines what to do when no priority is saved (ask once at first request of that kind, then persist via set_preferences, never ask again), what to do when a tier is unaffordable (take the best affordable and say so), and what to do with recipe results (prefer generate_with_recipe / start_recipe_run). Both alternatives and conditions 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 establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description still adds meaningful non-obvious context: AI requests share one rate limit across the app and agents, a covered generation consumes no credits, an included line reads `included`, and RATE_LIMITED should be retried after retry_after_seconds. It stops short of describing pagination or response shape, but the failure-mode and quota semantics are genuinely useful.

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?

It opens with a policy instruction rather than the tool's purpose, so the most decision-relevant content (what it reads) arrives second. Sentences are packed with multiple ideas and one clause ('A press the allowance covers costs no credits') is garbled enough to slow parsing. Nothing is strictly wasted, but the front-loading is suboptimal.

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?

An output schema exists, so return values need no explanation here. Combined with the annotations and the description's coverage of quota semantics and rate-limit handling, an agent has what it needs to call this correctly. The missing piece is only cross-tool routing against get_usage/get_account_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?

The tool takes zero parameters, which sets the baseline at 4 per the rubric. Schema description coverage is 100% and there are no enums to disambiguate, so nothing further is needed from the description.

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

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

The description names specific resources it reads: available credits, current plan, account-wide AI requests per minute, and this month's free allowance coverage. That is a clear verb+resource statement beyond the title. It does not differentiate itself from near siblings such as get_usage or get_account_context, 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?

It gives a real usage constraint ('use only the account's existing entitlements... do not offer purchases, upgrades, subscriptions or checkout links') and tells the agent what to do on RATE_LIMITED (wait retry_after_seconds). However it never states when to call get_credits versus get_usage or get_account_context, so the routing guidance is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the URL is short-lived, it is 'minted at the press' (ephemeral, re-mint rather than cache), and set references collapse into a single ordered ZIP. This meaningfully tells the agent how the result behaves over time.

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

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

Three sentences, each carrying distinct information (what it returns, the set/ZIP rule, the caching directive) with the core resource front-loaded. Dense and front-loaded, though 'Minted at the press' is slightly colorful relative to the otherwise plain register.

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?

An output schema exists, so return-shape detail is not owed by the description, and annotations cover the safety profile. The description supplies the operative gaps: prerequisite states, aggregate-set behavior, and ephemerality. The only omission is the optional filename parameter's effect, which keeps it from a 5.

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

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

Schema description coverage is 0%, so the schema documents structure but not meaning. The description partially compensates by mapping the two accepted reference kinds ('a ready generation or verified upload') onto the reference union, but it never explains the optional 'filename' parameter or what controls the ZIP ordering/naming. Baseline-adjacent, with a partial fill of the coverage gap.

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

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

It names the resource (a short-lived attachment URL) and the only two inputs it accepts in domain terms (a ready generation or verified upload), and it explains the aggregate case (a set returns one ordered ZIP). No sibling tool in the list mints download URLs, so differentiation is implicitly clear. It loses a point only because it is phrased as a noun description rather than a direct verb+resource statement.

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 encodes the precondition for use (the generation must be 'ready,' the upload 'verified') and a usage directive ('ask again rather than caching it'), which is genuinely actionable. However, it never names an alternative tool or states when-not-to-use it (e.g., vs get_generation or list_generations for metadata). Usage is implied rather than scoped against siblings.

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, and non-destructive, so the safety profile is covered. The description adds genuinely useful content-level transparency — that it returns the full 'whole' record across three row shapes plus submission/curator/public-page state — which goes beyond what the annotations convey. It stops short of 5 as the row/doctrine vocabulary is undefined.

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, but the body is a dense, jargon-laden run-on ('arm row', 'reprompt row', 'doctrine', 'run row') that taxes parsing, and the closing note about Kuro Desktop workflow files is niche. Several clauses don't clearly earn their place.

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

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

With an output schema present, the description needn't detail return values, yet it helpfully frames the record's composition and states the precondition relationship to update_recipe. It is largely complete for a single-parameter read, with the recipe_id source being the main 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 description coverage is 0% for the single recipe_id parameter, so the description carries the burden of explaining it — but it says nothing about the id's format or where to obtain it (e.g., from list_own_recipes). It only hints at recipe kinds via 'the recipe you own', leaving the required parameter effectively undocumented.

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

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

States a specific verb (Read) and resource (one recipe you own), and the scope qualifier 'you own' implicitly separates it from the catalog-oriented get_recipe sibling. It never names get_recipe, list_own_recipes, or update_recipe's read complement directly, so differentiation is inferred rather than explicit, and the 'arm row/reprompt row/run row' jargon obscures the plain purpose.

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 gives a use condition with rationale: 'Use this before update_recipe — a patch replaces config, writer or definition whole.' That is a concrete when-to-use directed at a named sibling. It falls short of 5 because it offers no when-not guidance and doesn't distinguish itself from get_recipe or list_own_recipes.

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 as a safe, read-only, idempotent operation. The description adds useful semantic context about what 'full' means by naming the reader-facing description and provider prompt fragment, but it does not add behavioral details such as error handling, permissions, 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?

It is a single front-loaded sentence with no wasted words. The core operation and the returned fields 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 low-complexity read-only tool with rich annotations and an output schema, the description is largely complete. The main remaining gap is that it does not explain how to source the preset_id or explicitly route agents from list_presets to this 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?

There is one parameter, `preset_id`, with 0% schema description coverage. The description does not identify the parameter, explain that it is a UUID, or say where to obtain it, so it does not compensate for the schema's lack of 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?

The description uses a specific verb and resource: 'Read one style in full.' The word 'one' distinguishes it from the sibling list_presets, and it names the concrete fields returned (`description` and `prompt_fragment`), so an agent can identify the operation 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?

The description implies usage by stating it reads one style in full, which suggests fetching a known preset by ID rather than listing presets. However, it does not explicitly state when to use this versus list_presets, nor does it mention prerequisites or error conditions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: which fields stay private (provider prompt template, reprompt rules) and that a run recipe returns run_inputs and step_count but never its steps. That is meaningful disclosure 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?

Front-loaded with the verb and resource, then layered with the variant-specific caveats. The reprompt sentence is dense but each clause carries information; there is very little filler.

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