Retiplex

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

Annotations only cover safety (not read-only, not destructive, closed-world); the description adds crucial domain behavior: an uploaded video only surfaces via a `custom-footage` moment and 'uploading it alone does nothing', plus that footage plays muted. It doesn't discuss reversibility or auth beyond what annotations imply, but the non-obvious side effects are disclosed.

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

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

Front-loads the key caveat ('Optional — except for uploaded videos') and packs type definitions and examples efficiently. It is dense but nearly every clause carries needed information; only the type enumeration could be tightened.

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

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

For a six-parameter tool with a nested object and an enum, and no output schema, the description covers when to use, all type semantics, the footage constraint, tagging, and script-length ordering. An agent has everything needed to call it correctly.

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

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

Schema coverage is high (83%), so the baseline is 3, but the description earns more by explaining what each type means (product-shot vs faceless, b-roll, product-action, talking-person), the `footage` requirement and muted playback, and the @[Name] tagging syntax with a concrete example.

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

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

States a specific verb and resource ('Adds a required moment: a scene the ad must contain') and immediately explains the mechanism (script written around it, storyboard places it). It is clearly distinguishable from sibling add_subject and remove_moment.

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 frames it as 'Optional — except for uploaded videos', states the null case ('without moments the script and storyboard decide everything, which is fine'), and gives ordering ('Add moments before generate_script; the total must fit the script's length'). 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description carries real behavioral burden – and it delivers cost ('a few credits'), latency ('ready in about a minute'), input constraints (≥480 px, upload_id origin), and a hard ordering dependency. What it omits is failure behavior (name collisions, generate-quota exhaustion), which keeps it short of a 5.

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

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

Front-loaded with 'Optional.' and the purpose, then the skip condition, then image sourcing, then ordering – a sensible priority order with no filler sentences. It is, however, one dense paragraph with heavy parenthetical nesting, which slightly impedes scanning.

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

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

For an 8-parameter mutation with a nested archetype object, no output schema, and 4 required fields, the description covers creation mode selection, prerequisites, cost, ordering, and kind semantics. It stops short of describing what is returned (e.g. the new subject's identifier used by later tagging) or error conditions.

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

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

With only 50% schema description coverage, the description compensates almost fully: it explains the two mutually exclusive image routes (image_url vs upload_id), the generate flag's side effects and cost, and the critical conditional that archetype applies only to generate+person while description drives pets/objects. That conditional is not derivable from the schema alone.

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

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

States a specific verb+resource ('Adds someone or something to the cast') and immediately bounds the scope relative to siblings: beyond the narrator and the product, i.e. not set_actor or set_product. It enumerates the three kinds (person/pet/object) and the mechanism (@[Name] tagging in moments), so the agent can distinguish it from add_moment without opening a schema.

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

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

Gives an explicit when-not ('Skip it unless the ad needs them'), names the prerequisite tool for the upload path (create_media_upload), specifies the generated path (generate: true), and states ordering constraints against add_moment and generate_script. Alternative routes for supplying the image are laid out as a decision, not left to inference.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds substantial context beyond that: the URL is one-time, the upload requires the correct Content-Type header, per-file and per-call limits (8 files, 15 MB photos, 50 MB videos), dimension/duration constraints, and that the tool is a no-op for videos unless a custom-footage moment exists. This is rich behavioral 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?

The core workflow is front-loaded in the first sentence, and the remaining constraints are organized as a scannable bulleted list with no filler. It is dense and fairly long, but every clause (formats, sizes, tagging, descriptions, file cap) carries operational weight.

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

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

There is no output schema, so the description correctly explains the return value (upload_url plus a ready-made curl command) and the required next step. For a 2-parameter upload-initiation tool, nothing an agent needs in order to invoke it correctly appears to be missing.

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

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

Schema coverage is 50%: project_id is documented, content_type carries only an enum. The description enumerates the accepted formats (JPEG/PNG/WebP, MP4/MOV), which effectively explains the content_type enum values, but it never clarifies the meaning or scope of project_id or how content_type relates to the uploaded file. Baseline 3 is appropriate since the schema plus enum carries most of the load.

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 ('create media upload' returning a one-time upload_url for a photo or video file on the user's machine) and names the follow-up sibling (finalize_media_upload) and the moment-based sibling (add_moment). An agent can distinguish it from finalize_media_upload and update_product_media 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?

It states the precondition (a local photo/video file plus an agent that can run curl or make HTTP requests), the exact sequence (PUT bytes with Content-Type, then call finalize_media_upload), and the failure mode for videos uploaded alone ('does nothing' without a custom-footage moment). Explicit when-to-use and what-comes-next guidance is present.

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 and destructiveHint=false, so the mutation profile is known; the description only adds that it returns the project and the next step. It omits richer context the tool clearly has (the 5-credit product_url import, downstream dependency on set_creative_brief/script), leaving behavioral disclosure thin beyond 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?

Three tight sentences, front-loaded with the core action, then the input choice, then media and returns. Every clause earns its place 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?

For a 9-param creation tool with no output schema, the description covers the workflow (import or describe product, attach media, get project + next step) adequately, and the heavy detail lives in schema param descriptions. It stops short of noting prerequisites like ordering language/video_quality before the brief, so it is complete but not exhaustive.

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 high (78%), but the description adds real value by explaining the alternative input path — import via product_url versus supplying product_name and product_description — a relationship the schema does not state. It likewise clarifies that media accepts URL-based assets. This is meaningful semantics beyond the schema.

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

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

States a specific verb+resource outcome ('Starts a new video ad for a product') that cleanly separates it from sibling readers/mutators like get_project, list_projects and set_product. An agent understands it creates and returns a new project object without needing 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?

Clearly gives the two input pathways (product_url to import, or product_name + product_description) and tells the agent to attach media by URL, with create_media_upload named in the schema for local files. It lacks explicit when-not guidance or a 'call this first' ordering versus other setup tools, 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 say destructiveHint=true; the description goes further and specifies exactly what is destroyed (the uploaded file is deleted from Retiplex storage on inspection/classification/save failure), that the error is returned, and that recovery requires a fresh upload. That is precisely the destructive-consequence and recovery detail 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?

Three short sentences, front-loaded with what the tool does, then failure behavior, then the recovery constraint. No filler or restatement of the title.

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

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

With no output schema, the description covers the failure path and its side effects well and implies success means the file is added to project media. It stops short of describing the successful return payload or validation rules applied during the check, a minor gap for a finalize/validate tool.

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

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

Schema description coverage is 100%, including the enum meanings for angle and the required-for conditions on description, so the schema carries the parameter semantics. The description adds no parameter-level detail beyond what is already documented, so the baseline 3 applies.

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

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

'Checks a file PUT to an upload_url against the requirements and adds it to the project's media' names a specific verb and resource and makes the two-phase upload flow evident. It does not explicitly name create_media_upload as the required predecessor, so sibling differentiation is implied rather than stated.

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 precondition is stated concretely ('a file PUT to an upload_url'), which tells the agent this is the second step of an upload flow rather than the step that creates the upload. No alternative tool is named and no when-not-to-use condition is given, but the operating context is clear.

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

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

With destructiveHint=true, the description usefully discloses that re-invocation produces a different variation (implying the prior script is replaced) and that save-mode is free, plus the downstream storyboard-invalidation consequence. It does not explicitly confirm overwrite/reversibility of the existing script, so it stops short of full behavioral coverage.

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 dense sentences, front-loaded with the core action and mode-switching behavior, followed by the length parameter and the workflow constraint. No filler; every clause carries actionable information.

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

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

For a 3-param generation tool with no output schema, the description covers generation vs save semantics, length limits, cost, and the storyboard dependency. It omits what the call returns (the generated script text or a confirmation), which an agent handling the result would benefit from knowing.

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

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

Schema coverage is 67%: `script` and `project_id` are documented in the schema, but `target_seconds` is not. The description compensates by explaining that target_seconds sets length within 10–120s and that trial accounts are more restricted — meaning beyond the schema's bare min/max bounds.

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

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

The description states a specific verb+resource ('writes the voiceover script from the brief') and covers both operating modes: generative (no script passed) and save-mode (script passed). It is easy to tell apart from sibling generate_storyboard, which it explicitly references via the storyboard dependency.

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: each repeated call yields a different variation, passing `script` switches to save-mode, and changing a script after a storyboard forces a storyboard regeneration. It stops short of naming an explicit alternative tool to use instead, so it lacks the when-not/alternative routing that would merit 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?

Goes well beyond annotations: discloses the 1–3 minute background execution, the polling-based completion check, the paid-plan requirement, and that regenerating replaces existing scenes (consistent with destructiveHint=true). It also quantifies cost (~28 credits/sec) and the English-only limitation of premium.

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

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

Dense but every sentence earns its place, and it is front-loaded with the core action before the operational details. 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?

With no output schema, the description still explains how to detect completion and what the result contains (storyboard.scenes), plus the prerequisite and destructive behavior. An agent has everything needed to invoke and follow up correctly.

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

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

Schema coverage is only 50%, but the description fully compensates: project_id is implicit in 'the script, actor and product photos', and video_quality is explained in depth (standard vs premium, the models behind each, cost, and premium's English-only restriction) — meaningful semantics the bare enum does not convey.

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 ('Plans the scenes from the script, actor and product photos') and clearly distinguishes itself from siblings like generate_script and start_video_generation. An agent knows exactly what artifact this produces.

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 states when to call it, the prerequisite (paid plan), the follow-up workflow (poll get_project until storyboard.scenes > 0, then review with the user), and the instruction to ask the user about video_quality before the first storyboard. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by stating that it returns capability and plan information for the signed-in user and should be called before spending credits, though it does not discuss authentication requirements or response format beyond the listed 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 tightly written sentences with zero waste. The resource and returned fields are front-loaded, followed immediately by the key usage instruction.

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

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

For a parameterless read-only account lookup, the description is complete: it states what is returned, who it applies to, and when to call it. An agent has enough information to invoke it correctly without needing an output 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?

The tool has zero parameters, so there are no parameter semantics to explain. The description instead lists the account fields returned, which adds meaning about the output even though no output schema exists.

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

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

The description clearly identifies the resource as the signed-in user's Retiplex account and enumerates the key fields returned: credit balance, plan, video-generation capability, and maximum script length. This is specific enough to distinguish it from all sibling tools, which focus on projects, media, and video generation rather than account state.

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 explicit usage guidance: 'Call this first, and before anything that spends credits.' This tells the agent exactly when to use the tool and why, with a clear prerequisite relationship to credit-spending operations.

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 establish the safe read-only profile, but with no output schema the description carries the return-value burden and does well, enumerating the fields returned and surfacing `nextTool` and the polling pattern. It adds real behavioral context (what comes back, how to proceed) rather than restating the safety hint, though it omits any latency or rate-limit expectations.

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 return description, then terse usage ('Poll this ...') and alternative ('call view_images'). The opening sentence is a dense field list but each item earns its place by describing the return shape; no filler sentences.

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

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

With no output schema and a rich, composite return, the description compensates by enumerating the returned components and pointing to `nextTool` and the polling behavior. It's largely complete for correct invocation, though some fields (e.g., 'current step', 'needs') are named without detail.

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

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

Schema coverage is 100% and the single project_id is fully described in the schema. The description adds no semantics about the parameter beyond what the schema provides, so the baseline 3 is warranted for a tool with schema-documented input.

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

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

The description clearly states a specific verb and resource: it returns a project's state and enumerates the returned components (product, media, cast, moments, brief, actor, script, storyboard, current step, nextTool). It distinguishes itself from view_images by routing there for photos/portrait, but it does not differentiate from close siblings like project_card, show_project, or list_projects.

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

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

Gives explicit usage context: 'Poll this while a storyboard or a subject image generates,' which tells the agent when to call it. It also names view_images as the alternative for accessing actual images. It stops short of stating when not to use it versus other project-reading siblings, so it's clear context without full exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds behavior the annotations cannot convey: the polling cadence and the fact that the response content changes from progress to a final URL as rendering completes. It does not state error/edge behavior when no render exists, keeping it short of a 5.

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

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

Two short sentences, front-loaded with what the tool returns and followed by the polling constraint. Every clause carries information; nothing is padded or 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?

There is no output schema, so the description correctly carries the return-value burden by naming progress and the final URL, plus the polling cadence. It is adequate for a single-parameter read tool, though it omits what 'progress' actually looks like or what happens before generation begins.

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

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

Schema description coverage is 100% and there is only one parameter, whose uuid format and pattern are fully specified in the schema. The description adds no semantics beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific resource (a project's video generation) and precisely what is returned: progress and the finished video's URL. It implicitly distinguishes itself from start_video_generation and resume_video_generation, though it never names those siblings explicitly.

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

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

It gives an explicit invocation pattern ('poll every couple of minutes, not faster'), which is genuinely actionable guidance. However, it never says when to call this versus alternatives like get_project or project_card, nor what to do if the project has no generation in flight.

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

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

Annotations already declare this as a read-only, non-destructive, closed-world operation, so the safety profile is covered. The description adds meaningful behavioral context by explaining that `custom` has no fixed structure and should be treated as an idea rather than a template.

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

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

Two short sentences, front-loaded with the core purpose and followed by the most important exception. Every sentence adds value without repetition.

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

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

For a zero-parameter, read-only listing tool with no output schema, the description gives enough context to invoke it correctly and interpret the main special case. Nothing essential is missing.

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

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

The tool has zero parameters, so there are no parameter semantics to disambiguate. Per the baseline for parameterless tools, a 4 is appropriate.

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

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

The description clearly identifies the resource as ad formats (narrative templates) and ties it to set_creative_brief, distinguishing it from unrelated siblings. It does not start with an explicit verb like 'Lists', but the name and title make the operation unambiguous.

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

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

The phrase 'for set_creative_brief' gives clear context for when to use this tool: to discover formats before or while setting a creative brief. It also gives a specific usage note for `custom`, though it does not state exclusions or alternatives in detail.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description usefully adds the implicit hard limit of 20 and a recency ordering, but says nothing about pagination, whether older projects are reachable, or result shape — with annotations present, that lands at a 3.

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 nine-word sentence that front-loads the resource. Every word carries information and nothing is repeated from the title or schema.

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

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

For a zero-parameter, non-destructive read with no output schema, the key contract (what is returned and how many) is stated, and annotations carry the safety profile. The one gap is that the 20-item cap is presented as an absolute with no hint about reachability beyond it.

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

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

The tool takes zero parameters, so the schema has nothing to document and the baseline of 4 applies. The description correctly implies no filtering or paging knobs are available.

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

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

The description names a specific resource and a precise scope ('the user's 20 most recent video projects'), so an agent knows exactly what set is returned. It stops short of an explicit verb and never distinguishes itself from nearby siblings such as get_project, show_project, or project_card, which also surface project data.

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 statement of when to prefer this over get_project/show_project/project_card, nor any note about what to do when a user has more than 20 projects. The cap implies a default browsing use case but the agent must infer it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the cryptic phrase 'read by the card itself' but does not clarify permissions, return contents, or typical call context.

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 one sentence is short but under-specified rather than concise. The phrase 'read by the card itself' is confusing and does not front-load useful information.

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

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

For a single-parameter read tool with no output schema, the description should explain what 'project card data' includes or how it relates to sibling read tools such as get_project and show_project. It leaves that essential context entirely absent.

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

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

Schema description coverage is 100%, and the single project_id parameter is already documented as 'The project's id.' The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

The description restates the title ('project card') and says it returns 'the project card's data,' but it does not specify a clear verb or explain what a project card is versus a full project. It remains unclear how this differs from siblings like get_project or show_project.

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

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

There is no guidance on when to use this tool, when not to use it, or which sibling tool is the alternative. An agent cannot infer from the description whether this is for UI card rendering, project summary retrieval, or something else.

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 adds the target ('from the ad') and the provenance of the moment, but says nothing about reversibility, required permissions, or what state the ad is left in.

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; the action and target are stated first. The phrasing 'a required moment' is slightly ambiguous (whether the moment or its presence is required), costing a point.

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

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

For a two-parameter destructive tool with full schema coverage and annotations covering the destructive profile, the description is minimally adequate. It could do more to explain the consequence of removal from the ad, 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 100%, so both parameters are already documented. The description's parenthetical merely restates the schema's own 'From get_project's `moments`' note, adding no new semantic detail.

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

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

States a specific verb ('Removes') and resource ('moment') scoped to the ad, and the inverse of the sibling add_moment is obvious. It does not explicitly name a sibling, but the remove/add pairing makes the distinction clear enough.

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 explicit when-to-use or when-not-to-use guidance, and no alternatives are named. The only hint is the parenthetical about where moment_id comes from, which is provenance rather than usage guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the entity must be untagged by any moment, and that pending/failed subject images are also in scope, which affects whether a call will succeed.

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 sentence with no filler; the resource and its precondition are front-loaded in one clause. Nothing could be removed without losing meaning.

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

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

For a two-parameter destructive tool with annotations covering safety, the definition covers the entity, the removable variants, and the tagging precondition. It stops short of saying what happens on a blocked removal (error vs no-op), a minor gap given no output schema exists.

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

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

Schema description coverage is 100%, so both parameters are documented in the schema, including that subject_id comes from get_project's 'cast' or 'pendingSubjects'. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

States a specific verb ('Removes') and resource ('a subject'), and clarifies the scope by naming the removable variants ('pending/failed subject image'). An agent can distinguish it from add_subject and remove_moment without opening a schema, though no sibling is named explicitly.

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

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

The clause 'that no moment tags' implies a precondition for use, but the description never states when to choose this over remove_moment or what to do when the precondition fails. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the write/safety profile is covered. The description adds genuine context by stating the operation resumes from the point of failure rather than restarting, but says nothing about permissions, rate limits, or what a resume attempt does if the job is unrecoverable.

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

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

One sentence, zero filler, with the core action front-loaded and the trigger condition attached as a subordinate clause. Nothing needs trimming.

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

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

For a one-parameter, no-output-schema tool, the description supplies the essential action, scope, and trigger condition. It leaves unstated what the tool returns or how the agent should proceed if the retry also fails, which is a minor gap given the tool's simplicity.

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

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

There is a single parameter with 100% schema description coverage, so the schema already documents project_id fully. The description adds no format, constraint, or selection guidance beyond that, which is the expected baseline when structured fields carry the load.

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 (retries/resumes) with a specific resource (video generation) and clarifies the scope with 'from where it stopped.' That scope clause separates it from the sibling start_video_generation without the agent needing to open either schema.

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

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

It gives an explicit trigger condition tied to another tool: use it 'when get_video_status suggests it.' It does not spell out the exact status values that qualify, nor explicitly warn against using it for a fresh generation (start_video_generation), so the routing is clear but not complete.

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

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

Beyond the annotations (which only say destructiveHint=true, non-read-only), the description discloses the cost per call (1 credit), that every call renders a new portrait, the merge semantics of partial updates, and the side effect that changing language clears language_accent. It also gives an operational constraint (show the returned previewUrl, never substitute your own image). Nothing here 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-loaded with purpose and tightly packed, but the single dense paragraph stacks several nested conditionals (auto-cast vs partial vs first actor vs voice-only) plus the previewUrl instruction, making it heavier to parse than the ideal. Every sentence does carry information, so no real 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?

There is no output schema, and the description compensates by naming the return artifact (previewUrl) and how to use it. With 1 required parameter, a nested object, enum constraints, and a credit-consuming render, all the information an agent needs to call this correctly is present.

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

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

Schema coverage is 75% and the description adds semantics the schema cannot express: omitting archetype triggers auto-casting, archetype behaves as a merge patch on an existing actor, and a first actor requires all fields except facialFeatures. It also scopes language/language_accent to voice changes rather than recasting, which is not derivable from the enum alone.

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

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

Opens with a specific verb+resource: 'Casts the on-camera narrator and renders their portrait', and immediately names the sibling it differs from (set_narrator_voice) and the field that selects between them. An agent can distinguish it from add_subject, set_product, and set_narrator_voice 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 conditional routing: omit archetype for an audience-fitted auto-cast, pass it to design someone, and use set_narrator_voice instead when only language/accent should change 'which doesn't recast'. It also states the create-vs-update rule (first actor needs every field except facialFeatures) and that partial fields merge, so the agent knows exactly when and how to invoke it.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered, but the description adds non-obvious behavior the annotations cannot convey: omitted facts are inferred from the product and this costs credits, and the custom format triggers a written brief from the idea. It stops short of saying what an existing brief is replaced by.

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

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

Three tight sentences with the primary purpose front-loaded and the cost/deduction caveat placed before the custom-format branch. No filler, though the parenthetical fact list slightly lengthens the opening sentence.

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

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

For a 7-parameter destructive mutation with no output schema, the description covers cost and the custom flow but omits what is overwritten by a re-set brief and says nothing about funnel_stage. It is workable but leaves a meaningful gap for a tool flagged destructive.

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 57%, and the description compensates by mapping the plain-language "who it's for, the benefit to sell, the action to drive" onto target_audience, benefit_to_highlight and primary_ad_goal, plus explaining idea's role. funnel_stage remains undefined in both places.

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

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

States a specific verb and resource ("Sets the ad's format and campaign facts") and immediately enumerates the facts in parentheses, so the agent knows exactly what the call accomplishes. It does not name an alternative sibling to disambiguate against, though it does point to list_formats as the source of format values.

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 conditional guidance for one path ("For the `custom` format pass `idea`") and notes format is required the first time, which implies repeated invocations. However there is no explicit when-to-use/when-not relative to siblings like create_project or generate_script, so the routing is mostly 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?

With destructiveHint=true declared, the description goes further and names exactly what is invalidated: the script must be regenerated, and an existing storyboard 'goes stale'. It also enumerates what follows the setting (script, talking scenes, voice, captions) and notes it is free, none of which the annotations convey.

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

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

Four tight sentences, front-loaded with the core action and followed by consequences and remediation. Every sentence carries information, though the dependency chain (regenerate vs pass as `script` vs scriptWarning) is dense enough to require a second read.

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

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

For a destructive, no-output-schema mutation tool, the description covers cost, scope, dependent artifacts, and the recovery path, which is what an agent needs to act safely. A closing note on the returned/observable result (e.g., how the agent confirms success or reads the warning) would make it fully complete.

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

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

Schema coverage is 100%, so language, project_id, and language_accent are already well documented (including the enum and the accent-clearing behavior), which sets the baseline at 3. The description adds little parameter-level detail and even references a `script` argument that is not in this tool's schema, which could momentarily mislead.

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 (sets the narrator's spoken language and accent) and immediately scopes it against the sibling by saying it operates 'without touching the actor', which separates it from set_actor. The parenthetical showing the in-app name ('Narrator's voice') anchors the term the user sees.

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

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

Explains the downstream workflow clearly: a script in the old language must be regenerated via generate_script or rewritten and passed as `script`, and points to get_project's scriptWarning as the signal. It also flags cost ('Free.'). It stops short of an explicit 'use this when...' rule for choosing this tool over set_actor, but the context is unambiguous.

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

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

Annotations already declare this is a destructive, open-world mutation, but the description does not explain what existing product/media is replaced, whether changes are reversible, or any credit/auth implications. 'Changes' and 'adds' only restate the mutation at a high level.

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 definition is very short and front-loads the main actions. The second sentence is concise but of limited value because it relies on knowledge of another tool.

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

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

For a six-parameter destructive mutation with no output schema and only partial schema coverage, the description is too sparse. It omits usage conditions, destructive effects, and meaningful parameter explanation, leaving the agent dependent on the schema and sibling tools.

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

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

Schema coverage is 67%, but the description adds no parameter meaning beyond the schema. 'Same inputs as create_project' is a vague cross-reference and does not compensate for undescribed fields such as product_name and product_type.

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 specific actions: changing a project's product and adding photos/videos. It is understandable apart from vague product terminology and does not clearly distinguish itself from sibling update_product_media.

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 no guidance on when to use this tool versus create_project or update_product_media. 'Same inputs as create_project' describes input shape, not usage conditions or exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context beyond them: the card is live and self-updating while a storyboard or video generates, and rendering depends on client capability with a URL-sharing fallback. No auth, rate-limit, or payload details, but the UI-lifecycle behavior is disclosed well.

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

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

Two sentences, front-loaded with the verb and resource, then the contents, then routing guidance. The middle enumeration is long but each item is informative. No wasted preamble or restated title.

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

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

There is no output schema, but the description compensates by describing what the card displays, including the rendered video, so an agent knows what comes back. Combined with one simple required param and full read-only annotations, an agent has enough to call it correctly. The only unresolved ambiguity is how it relates to the sibling project_card.

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 parameter with 100% schema description coverage, so the schema already documents project_id. The description adds nothing about the id's format or source. Baseline 3 applies when the schema carries the parameter semantics.

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

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

States a specific verb and resource ('Shows the user a live card of the project') and itemizes what the card contains: progress, portrait, photos, storyboard scenes, and the rendered video. It also draws a line against get_project. It stops short of differentiating from the sibling project_card, which sounds like it may do something very similar.

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

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

Explicitly says when to use it ('whenever the user wants to see the project or the result') and names both the fallback tool and the condition that triggers it ('in clients that can't display it, share the URLs from get_project instead'). That is a complete when/when-not/alternative routing 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?

Annotations only declare non-read-only, non-destructive, closed-world. The description adds real behavioral context beyond them: a 10–30 minute runtime, that it consumes credits, and that it is asynchronous and must be polled via get_video_status. The cost-refusal behavior is partly covered by the schema's max_credits description.

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 what is produced and immediately followed by the time/cost constraint and the required follow-up call. 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?

No output schema exists, and the description supplies what an agent needs to invoke it correctly: duration, credit spend, the max_credits sourcing rule, and the polling loop. It is slightly thin on failure behavior and on what to do if the run is interrupted, which matters given resume_video_generation exists as a sibling.

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 operational meaning the schema lacks: max_credits should be the estimatedVideoCredits value from get_project and should be confirmed with the user first. It does not explain the consequence of setting it too low beyond the schema's 'refuses above 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 and resource ('Generates the video from the storyboard') and enumerates the pipeline stages (hook, voice, scenes, final render), which separates it from generate_storyboard and generate_script without opening a schema.

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

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

Gives concrete workflow guidance: read the estimate from get_project, confirm with the user, pass it as max_credits, then poll get_video_status. It stops short of naming resume_video_generation as the alternative path for an interrupted run, which is the one sibling most likely to be confused with this one.

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

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

With destructiveHint=true already declared, the description adds substantial non-obvious behavior: the removal path, per-batch limit, the muted-playback/video-only-through-custom-footage rule, and required-description conditions. This is well beyond what annotations convey.

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

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

Purpose is front-loaded, but the bulk is a media-specification block (JPEG/PNG/480×480/15 MB/video durations) that reads like it was copied from an upload tool and is only partially relevant to classification. The 'at most 8 files per call' note also sits oddly against a schema that takes a single required media_id.

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

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

For a mutation tool with no output schema and no annotation detail beyond hints, the description is nearly complete — it covers removal, required descriptions, and tagging rules. It omits any permission/auth requirement, but otherwise an agent has enough to call it correctly.

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

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

Schema coverage is already 80%, so the baseline is 3; the description adds real meaning by specifying which photos need `angle` tagging, when `description` is mandatory, and the ≤240-character limit. It mostly reinforces rather than extends the schema's own angle enum descriptions.

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: 'Classifies a product photo or video (its view `angle`, its `description`) or removes it.' It clearly distinguishes itself from sibling tools by positioning classification/tagging rather than uploading (create_media_upload / finalize_media_upload) or viewing (view_images).

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 concrete workflow: look at each photo get_project lists with `needs`, view it via view_images, then tag with what you see. It also routes videos to add_moment (type custom-footage). However, it never explicitly contrasts with the upload tools that create the media this tool then tags, so the 'when-not' boundary is left implicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds materially: the default inclusion logic (portrait + unclassified photos, all photos once none do), the captioning behavior (each image labelled with its media_id), and a firm directive to surface Retiplex URLs rather than fabricate images.

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 compact sentences, front-loaded with what is returned before the workflow hint. Dense but each sentence carries a distinct payload (scope, sequencing, output/directive); minor overlap between the default-scoping clause and the actor parameter's own default description.

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

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

With no output schema, the description takes on the burden of describing the return: images captioned with their media_id, which is exactly what the agent needs to chain into update_product_media. Nothing necessary 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 coverage is 100%, so the baseline would be 3, but the description adds the interaction between parameters that the schema states only per-field: the actor portrait is included by default and media_ids overrides the unclassified-photo default. That clarifies the real selection semantics beyond the field-level docs.

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 ('Shows you the project's images') and immediately disambiguates scope: the actor's portrait plus every product photo still needing classifying, falling back to all photos. It is clearly distinguishable from siblings like get_project or update_product_media.

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

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

Explicitly prescribes placement in a workflow: 'Use it before update_product_media to see which view each photo shows.' It also states the default selection rule, so the agent knows when the bare call is sufficient versus when to pass media_ids.

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