VideoGen

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

Annotations already declare non-read-only, non-idempotent, non-destructive. The description adds genuinely valuable behavior beyond that: a hard restriction on built-in entities, file-type limits per entity type, and the recommended call ordering. It stops short of saying what happens on failure or whether existing references are replaced.

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, each carrying a distinct rule (file-type scope, BRAND roles, built-in restriction, recommended ordering), with the core action front-loaded. No filler or 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 5-param mutation tool with full schema coverage, annotations, and an output schema, the description covers everything an agent needs: valid file types, role choices, hard restrictions, and workflow ordering. 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by tying isDefault to the post-create_entity workflow and by explaining role values in the context of what they affect (overlay logo vs. visual generation reference).

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 (attach an uploaded file as a reference on an entity) and immediately scopes it: images for all entity types, PDF/PowerPoint only for slideshow themes. It is clearly distinguished from the sibling remove_entity_reference and from create_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?

Gives explicit when-to-use rules and exclusions: 'Built-in entities cannot have references added,' which role to set for a BRAND, and the ordering instruction to call this right after create_entity with isDefault: true for new PRODUCT/ACTOR entities. Alternatives and constraints are both 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?

Goes beyond the annotations by disclosing that the archive is soft rather than a hard delete, that there is no restore path, and that built-in entities are ineligible. One nuance: annotations claim idempotentHint=true while the description warns retrying can fail, which is a mild tension in framing (a failed retry still leaves state unchanged), but not a true contradiction.

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, no filler, with the core action and its effect front-loaded before the constraints. Every sentence adds a distinct constraint 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?

For a single-parameter mutation with an output schema, an agent has everything: action semantics, effect on listing, irreversibility, eligibility limits, and the failure mode. Return values are covered by the output schema and briefly echoed in the description.

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

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

Only one parameter and schema description coverage is 100%, so the schema already explains entityId and where to obtain it. The description adds no parameter-level detail, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('Soft-archive a team entity') plus the observable effect ('no longer appears in lists or pickers'), which cleanly separates it from create_entity, update_entity, and get_entity. 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?

Gives clear when/when-not conditions: no restore operation exists, retrying an archived entity can fail, and built-in entities cannot be archived. It stops short of naming sibling alternatives (e.g., update_entity for reversible changes), so it is strong context but not full routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds real value beyond them: pending work stops, completed files survive, open reviews are dismissed, and only toolExecutionId is returned. These are exactly the side-effect details an agent needs before invoking a destructive 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?

Four tight sentences, front-loaded with the action, followed by side effects and then the return/routing note. Every sentence 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?

Given an output schema exists, the description needn't explain returns, but it still notes the minimal acknowledgment and where to read results. Combined with the side-effect disclosure, nothing needed 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 100%, so the single parameter is fully documented in the schema (including provenance from a start result or list_tool_executions). The description adds no parameter-specific syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb (cancel) and resource (tool execution), and scopes it to 'API-started media generation or transformation', which separates it from siblings like get_tool_execution and list_tool_executions. 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 makes clear this is for stopping pending work and points to get_tool_execution for reading status afterward. It does not explicitly state when-not to use it (e.g., versus cancel_workflow_run), but the 'API-started' qualifier narrows applicability usefully.

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

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

Goes well beyond the annotations (destructiveHint, idempotentHint) by defining the blast radius: it stops pending work but does not delete the project or undo completed work, and terminal runs are untouched. That is exactly the destructive-scope context an agent needs before invoking.

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

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

Three tight sentences, front-loaded with the action and its scope, then the negative constraints, then the acknowledgment payload. Every sentence earns its place with no repetition of the title.

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

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

Given a single required parameter, an output schema that defines return fields, and annotations covering the safety profile, the description supplies everything missing: scope limits, terminal-run behavior, and the follow-up status tool.

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

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

Schema description coverage is 100% with a single well-documented workflowRunId, so the schema carries the parameter burden. The description only mentions workflowRunId in the return list and adds no format or sourcing detail beyond the schema.

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

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

States a specific verb ('Request cancellation') and a scoped resource ('API-started workflow and its related generation, remix, and export tasks'). The word 'Request' correctly signals asynchronous behavior, distinguishing it from get_workflow_run and list_workflow_runs 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?

Gives clear context: use it to stop pending work, terminal runs are unchanged, and it points to get_workflow_run for status afterward. It does not explicitly contrast with cancel_tool_execution or state prerequisites/permissions, so it stops short of full 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 already cover the safety profile (non-readOnly, non-destructive, non-idempotent, closed-world). The description adds genuine behavioral context beyond them: it returns the new record with entityId/references, brandConfig is BRAND-only, and slideshow themes may attach an image or a PDF/PowerPoint. It does not mention idempotency or duplicate-name behavior, which would complete the picture.

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?

Long but dense; the leading sentence front-loads the entity taxonomy, then downstream usage. Every sentence carries information, though the large type enumeration partly duplicates the enum schema and could be trimmed without losing meaning.

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

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

With a nested-object schema, full parameter coverage, and an output schema present, the description supplies exactly the missing connective tissue: what each type means and where the returned entityId must be reused downstream. Nothing needed to call this correctly is absent.

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

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

Schema description coverage is 100% and the schema already documents entityType enum meanings, brandConfig fields, and description in detail. The description largely mirrors that content (PRODUCT vs PROP, brandConfig for BRAND) rather than adding new syntax or constraints, so the baseline of 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?

Specific verb (Create) plus an exhaustive enumeration of the resource subtypes (ACTOR, PRODUCT, VISUAL_STYLE, SLIDESHOW_THEME, BRAND, LOCATION, PROP), and it disambiguates the trickiest case (PRODUCT vs PROP) explicitly. An agent can distinguish this from create_file_upload or update_entity without opening any schema.

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

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

Gives clear follow-up sequencing (attach references with add_entity_reference and upload the file first) and states exactly which downstream tools consume the returned entityId and under which field name. It stops short of naming siblings like update_entity as the alternative for modifying an existing entity, so it is context-rich but not a full when-to-use/when-not matrix.

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 mutation safety profile, but the description adds critical non-obvious behavior: the return shape { fileId, uploadUrl }, the required PUT mechanics, the explicit warning that NO Authorization header must be sent to the short-lived pre-signed URL, and the post-upload wait step. This is exactly the operational context an agent cannot derive from structured fields.

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

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

Four tight sentences, front-loaded with the trigger condition, then output shape, then required call mechanics, then the alternative. Every sentence carries distinct actionable content 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?

Complete for a multi-step upload tool: it covers the pre-signed URL protocol, the follow-up get_file call, and where the returned fileId can be consumed. The presence of an output schema means it needn't explain return values further, and it doesn't over-explain.

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 all three params (type, displayName, isTemporary) are already well documented there. The description adds no parameter-level syntax or defaults beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('start an upload for a large file') and immediately scopes it against the sibling upload_file ('For small files, prefer upload_file'). An agent can distinguish this from upload_file and open_uploader without opening either schema.

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

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

Gives explicit when-to-use conditions ('large file, or when file bytes cannot be inlined'), names the alternative for the opposite case, and lays out the follow-up sequence (PUT to uploadUrl, then get_file with wait:true). Nothing about selection is left to inference.

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

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description adds substantial behavioral context on top: hosted calls return an exportId and are async, local calls block, renders take minutes, and the user must be warned in advance. That is real added value beyond the structured fields.

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

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

Four short sentences, front-loaded with the core action, then output behavior, then the timing warning. Every sentence carries distinct operational information with no repetition.

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

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

An output schema exists, so return-value documentation is not strictly required, yet the description still explains the exportId/polling contract and the sync-vs-async split. Combined with the rich quality enum in the schema, an agent has everything needed.

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% — both projectId provenance and the quality enum tiers are fully documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Render an editable project to MP4'), and the rendering/mutation framing clearly separates it from generation siblings like generate_video_clip or storyboard_to_video. An agent can identify function and counterpart (get_project_export) 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?

Explicitly routes the agent to get_project_export for status/progress and states that local calls differ (they wait for the snapshot). Lacks an explicit when-not-to-use, but the operational context is clear enough to select and drive the tool correctly.

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 generic hints (readOnly=false, idempotent=false), so the description carries the real behavioral load: it discloses that generation is slow ('a few minutes, longer for longer audio'), that it is asynchronous, and that results arrive via get_tool_execution. It doesn't state whether re-invocation is billed/duplicated or how failures surface, 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?

Four short sentences, front-loaded with the core action and required inputs, then latency guidance, then the polling handoff. Every sentence contributes something actionable and nothing is redundant.

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

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

Despite an output schema existing, the description goes further by explaining the async lifecycle and the ID needed for polling, which is the critical missing link. For a long-running, non-idempotent generation tool with an existing output schema, nothing an agent needs to call and follow up correctly is absent.

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

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

Schema description coverage is 100%, so the schema already documents actorEntityId, audioFileId, and the avatarQuality enum. The description references actorEntityId and avatarQuality but adds no new syntax or constraints beyond the schema's own text, making the baseline 3 appropriate.

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

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

States a specific verb and artifact: 'generate a talking-head avatar video from an ACTOR entity and an uploaded audio file.' This clearly differentiates it from siblings like generate_video_clip, voiceover_to_video, and text_to_speech by naming both required input types.

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 prerequisite inputs (audio upload / fileId / text_to_speech result) and the follow-up path via get_tool_execution, plus instructs the agent to warn the user about wait time up front. It doesn't explicitly exclude alternatives such as voiceover_to_video, so it stops short of a 5.

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

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

Annotations already declare non-readOnly, non-destructive, non-idempotent, closed-world. The description adds the latency envelope (15-60 seconds) and an explicit instruction to tell the user about the wait up front — operationally important context the annotations cannot express. It does not say whether the call blocks or returns a task handle, which is the one remaining gap.

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

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

Three tight sentences, front-loaded with the core action, then conditioning modes, then the latency warning. No filler and nothing redundant with the schema.

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

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

An output schema exists, so return values need not be described, and the description covers purpose, conditioning inputs, and the key UX behavior (long-running). It is slightly incomplete in not clarifying sync-vs-async execution or any follow-up polling/status tool, which matters given the sibling cancel_tool_execution/get_tool_execution family.

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 prompt, quality, entityIds, aspectRatio, and imageFileIds are all already documented in the schema, including the entityId/fileId sourcing guidance. The description adds no syntax or constraint detail beyond that, so the baseline of 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 ('Generate') and resource ('an image from a text prompt'), and immediately distinguishes two operating modes (text-to-image vs. image-to-image). This separates it cleanly from generate_avatar, generate_video_clip, and prompt_to_video_clip, which an agent must otherwise disambiguate by name alone.

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 clarifies the two usage contexts (plain prompt, or conditioned on imageFileIds/entityIds for identity consistency), which is real selection guidance. It stops short of naming alternatives or stating when-not to use it (e.g. versus generate_avatar for human characters).

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 write profile (readOnly=false, destructive=false, idempotent=false); the description adds substantial non-obvious context on top: the default transparent WebM vs opaque MP4 output, that VideoGen writes animation code and then renders, the 2–5 minute expected duration, and that a long-running in-progress job is healthy rather than a failure. That latency/expectation guidance is exactly what an agent needs to avoid aborting a valid 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?

Five sentences, front-loaded with purpose then differentiation, then output format, then latency and operational guidance. No filler; even the last sentence about telling the user and polling calmly carries behavioral weight an agent would otherwise get wrong.

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 fills the remaining gaps: differentiation from siblings, default output container, latency expectation, and optional reference media use. Nothing an agent needs to invoke 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 100% and every parameter (prompt, fileIds, entityIds, aspectRatio, subToolModes, durationSeconds, transparentBackground) is documented in the schema. The description only restates the transparentBackground default and mentions optional reference media ids, adding no syntax or constraint detail beyond the schema. Baseline 3 is correct.

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

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

States a specific verb+resource ('Generate an animated motion graphic video from a text prompt') and then carves out a precise niche: 'precise text animations (typing effects, kinetic typography, lower thirds) that stock or generated footage can't express.' That niche statement is what separates it from the many video-generation siblings (generate_video_clip, prompt_to_video_clip, script_to_video).

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

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

Gives a clear selection criterion (use when the content is precise text animation / kinetic typography that footage can't express) plus operational guidance to tell the user about the 2–5 minute wait and to poll calmly. It stops short of naming a sibling tool as the fallback for cases where footage *would* work, so routing is inferable rather than explicit.

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 read-only, not idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavior the annotations cannot express: a 1–5 minute latency expectation and an explicit UX instruction to warn the user up front. It stops short of failure/timeout or cost behavior.

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

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

Three short sentences, front-loaded with the action, then latency, then the actionable UX instruction. No filler and nothing repeated from the schema or annotations.

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

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

An output schema exists, so return values needn't be explained, and annotations cover the safety profile. The description supplies the one thing an agent most needs for this long-running generation call – the wait expectation and how to set user expectations. Missing only edge cases like failure handling.

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 'prompt' parameter is already documented with what it should contain (genre, mood, instrumentation, tempo). The description's 'from a text prompt' adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Generate a music track from a text prompt'), which cleanly separates it from siblings like generate_image, generate_video_clip, and generate_sound_effect. An agent can select this tool from the name and first sentence alone.

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 never states when to use this tool versus alternatives, nor any prerequisites or exclusions. It implies its own usage by describing the output, but gives no routing guidance among the many generate_* 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 only declare the safety profile (not read-only, not idempotent, not destructive, closed-world). The description adds genuinely new behavioral context: this is an async job that returns a toolExecutionId and requires a separate get_tool_execution call to obtain the file and download URL. It does not state expected latency or failure modes, keeping it below 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 filler. The generative purpose is front-loaded and the retrieval instruction follows immediately after; 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?

For a two-parameter async generation tool with an output schema, the description covers purpose and the post-call retrieval flow, which is the critical operational detail. The only gap is disambiguation from sibling generators, which matters given the large family of generate_* 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 description coverage is 100%, so both parameters are already documented in the schema, giving a baseline of 3. The phrase 'desired sound and timing' loosely maps to prompt and durationSeconds but adds no format, unit, or constraint detail beyond what the schema already provides (including the 30-second maximum).

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: 'Synthesize a standalone audio effect from a description of the desired sound and timing.' The word 'standalone' implicitly contrasts with generate_music, but no sibling is named explicitly, so an agent must infer the boundary between this and generate_music or text_to_speech.

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 routes the agent to the follow-up step ('use get_tool_execution to retrieve the generated audio file'), which is useful lifecycle guidance, but it offers no when-to-use vs when-not guidance relative to the many sibling generation tools (generate_music, text_to_speech, generate_avatar). Usage is implied 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 only cover the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds genuinely non-structured context: this is a long-running async operation taking 1–3 minutes (longer for HIGH/MAX) that must be polled, which is exactly the kind of trait an agent needs and annotations do not carry.

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

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

Three sentences, front-loaded with the verb and resource. The latency/polling sentence is actionable and free of filler; slight redundancy in listing every input modality, but overall tight.

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

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

For a 12-parameter async generation tool with an output schema and full schema coverage, the description supplies the missing piece – expected latency and the need to poll – without needing to explain returns. It stops short of naming the actual polling mechanism (e.g. get_tool_execution / get_async_tasks_guidance), which is the one residual gap.

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

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

Schema description coverage is 100%, so all 12 parameters are already documented in the schema. The description names a few modalities that map to parameters (spokenDialogue, source images/videos, reference audio) but adds no syntax, ordering, or dependency detail beyond what the schema provides – baseline 3.

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

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

States a specific verb+resource ('Generate a video clip') and enumerates the input modalities (text prompt, source images, source videos, spokenDialogue, reference audio). It is clearly a generation tool, but it never distinguishes itself from the many video-generation siblings (prompt_to_video_clip, script_to_video, voiceover_to_video), so an agent still has to guess which generator to pick.

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

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

The only guidance is operational ('Tell the user that wait up front and keep polling calmly'), which addresses handling rather than selection. It never says when to use this tool instead of prompt_to_video_clip or the other *_to_video siblings, leaving the choice 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 carry the read-only/idempotent/non-destructive safety profile, so the bar is lower, and the description adds genuine context beyond them: the URL opens a modal or navigates only after sign-in (auth-gated), and the agent should hand the URL to the user rather than surfacing it inline. It stops short of describing expiry or format of the returned URL.

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 purpose and followed by the usage rule. The long parenthetical action list is informative but slightly heavy; otherwise there is no wasted wording.

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 explain the return value, and all 8 parameters are schema-documented. It still supplies the one behavioral fact an agent needs (return the URL for the user to open), so it is complete for 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?

Schema coverage is 100%, so each parameter is already documented (action enum, provider, destination, articleSlug, etc.). The description echoes the action categories but does not add syntax or mapping detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb ('Build a VideoGen app URL') and resource, plus enumerates the concrete destinations (upgrade, credits, top-ups, invite, feedback, integrations, settings, NAVIGATE). It is clearly the only URL-builder among the sibling generation/entity tools, so an agent can distinguish it immediately.

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 prefer it ('when the user needs to complete something in the VideoGen UI that MCP tools cannot do inline — especially credits or plan gates') and gives the operative constraint that selects it. This is a real when-to-use boundary rather than an implied one.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description only needs to add context. It does that by clarifying the tool is equivalent to a resource read and explaining its existence for clients that don't read resources directly, which is useful behavioral context beyond the annotations.

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

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

The description is compact and front-loaded: it states the topic and covered aspects, then gives the call condition, then clarifies its relationship to an MCP resource. Every sentence earns its place with no redundant or filler content.

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 guidance tool with an output schema and full annotation coverage, the description is complete enough. It explains the subject matter, when to invoke it, and its resource equivalence, leaving no obvious gap for correct selection or invocation.

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

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

The tool has zero parameters, so there are no parameter semantics to document. The baseline for a parameterless tool is 4, and the description appropriately omits parameter details.

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

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

The description clearly states the tool's purpose: guidance on handling async workflows, tool executions, and exports, including statuses, wait caps, polling, and webhooks. It is specific about the domain but does not explicitly distinguish itself from sibling guidance tools like get_getting_started_guidance or get_workflows_guidance, 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?

The description gives a clear usage trigger: 'Call before polling or when a start tool returns a still-running snapshot.' It also notes that it's equivalent to reading a specific MCP resource and why it exists as a tool. However, it does not name alternative guidance tools or state when not to use this one.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: the response includes reference images, built-in catalog entities are returned as well, and those carry an isBuiltIn flag. That is real return-content disclosure the annotations do not provide.

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

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

Two short sentences, front-loaded with the core action and immediately followed by the most useful return detail. No filler, no repetition of the title.

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

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

With an output schema, full annotation coverage, and a fully described single parameter, the definition is nearly self-sufficient. The one thing left implicit is the relationship to list_entities/create_entity for obtaining the id, which the schema happens to cover anyway.

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 entityId parameter already documents its own origin (list_entities or create_entity). The description's 'by id' adds no format, type, or sourcing detail beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: fetch one entity by id, and adds the scope qualifier 'one' that distinguishes it from the sibling list_entities. It never explicitly names the sibling tools, but the singular/plural contrast makes the retrieval semantics 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?

Usage is implied rather than stated: an agent infers it should call this when it has a single entityId and wants that record. There is no explicit when-to-use vs list_entities or when-not guidance, and no statement that the id can be sourced from list_entities or create_entity (that lives only in the schema).

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 safety is covered. The description adds real behavioral context beyond them: URLs are hydrated/non-expired, and wait:true switches the tool into a polling mode until processing finishes — a state-dependent behavior 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, front-loaded with the core fetch behavior and followed by the conditional polling instruction. No filler, no 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 payload details need not be spelled out, and it still names the rendition types an agent will receive. With 100% schema coverage and full annotation coverage, nothing needed to invoke 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 100%, so the baseline is 3 and the schema already documents fileId, wait, timeoutMs, and pollIntervalMs. The description still earns credit by tying wait:true to a concrete workflow moment rather than restating the boolean's definition.

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 (fetch) plus resource (file by id) and further specifies what comes back: freshly hydrated, non-expired signed URLs for thumbnail, preview, and download renditions. That return-oriented detail separates it cleanly from siblings like list_files, upload_file, and create_file_upload.

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 workflow trigger: set wait: true and call this right after PUTting bytes to a create_file_upload URL, naming the sibling it follows. It does not state when NOT to reach for this tool (e.g., versus list_files for discovery), so it stops just short of full routing guidance.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds real context beyond that: it is the tool equivalent of the `guidance://getting-started` resource and exists for clients that cannot read resources directly, plus an overview of what content is returned.

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 that are front-loaded with the content scope, then the invocation triggers and the resource-equivalence note. Dense but each clause carries information; no filler.

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

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

For a zero-parameter, read-only guidance tool with annotations and an output schema, this is complete: it says what the guidance covers, when to fetch it, and why it exists in tool form. 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?

The tool takes zero parameters, so there is no parameter surface to explain; the baseline for 0 params is 4. The description correctly implies a no-argument call.

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

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

The description names a specific resource (getting-started guidance) and enumerates its content: authentication, verifying with get_me, VideoGen intro, workflows-vs-media-tools selection, and ID conventions. It is clearly not a data-mutation or generation tool. However, it does not distinguish itself from the sibling guidance tools (get_workflows_guidance, get_tools_vs_workflows_guidance, get_async_tasks_guidance), whose scopes it partly overlaps.

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 call triggers: connecting, onboarding, user asking what VideoGen can do, or setting up the API/MCP. This is clear contextual guidance. It stops short of naming alternatives or when-not conditions (e.g., 'use get_workflows_guidance instead when you only need workflow details').

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's marginal additions are the connection-test hint and the field list, but the field list largely duplicates the existing output schema, and it says nothing about auth failures or error behavior when the key is invalid.

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

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

Two tight sentences, front-loaded with the core action and payload, followed immediately by the practical usage note. No filler and nothing buried.

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?

A zero-parameter read tool with full annotation coverage and an output schema needs only a statement of what it returns and why to call it; the description supplies both. An agent has everything required to invoke it correctly.

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

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

The tool takes no parameters, so there is nothing for the schema to document and no semantic gap for the description to fill. Baseline 4 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 ('Fetch') and resource ('the account and team behind the API key'), and enumerates the identifying fields returned. It is clearly distinguishable from siblings like get_entity or get_project, which target different resources.

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

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

Explicitly names a use case — 'Use it as a connection test' — which tells the agent when this zero-argument tool is appropriate. It stops short of naming alternatives or exclusions, but the context is clear enough to act on.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the detail that some fields are returned 'when available,' which is minor contextual value. It does not discuss permissions, rate limits, or pagination.

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

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

The description is two sentences: one front-loaded return-value summary and one usage instruction. There is no redundant or filler content.

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 and rich annotations covering safety, the description only needs to state purpose and relevant usage. It does so completely, including the key downstream call guidance for the projectId.

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

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

Schema description coverage is 100%, so the schema already documents the projectId parameter and its origin. The description adds meaning beyond the schema by noting that the projectId is reusable for 'subsequent remix and export calls,' clarifying its downstream utility.

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 plus resource ('Return a project's ...') and enumerates the exact fields returned, so the agent can immediately distinguish this from list_projects or export_project. It clearly states this is a single-project inspection tool.

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

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

It gives clear downstream guidance: 'Use the projectId for subsequent remix and export calls.' This tells the agent what to do with the result. It does not explicitly state when not to use it or name list_projects as an alternative, but the context is sufficient.

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 safety is covered; the description adds the genuinely useful behavioral fact that status is asynchronous and progresses to one of three terminal states. It does not say whether a ready downloadUrl expires or how errors are surfaced across polls.

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

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

Two sentences, zero filler, and the payload contents are front-loaded before the polling instruction. 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?

With an output schema present and annotations covering safety, the description only needs the async/polling contract — which it supplies, including terminal states. Minor gaps (poll interval guidance, downloadUrl lifetime) keep it from being 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 description coverage is 100% and both parameters are documented there (exportId format vg_expo_..., projectId provenance), so the schema carries the load. The description adds no parameter-level meaning beyond naming return fields, which is the baseline 3 case.

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 ('Return an export snapshot') and enumerates what comes back (status, progress, errors, downloadUrl, exportFileId, thumbnailUrl, file metadata), so an agent knows this is the retrieval half of the export flow. It does not name the sibling export_project as the initiator that produces the exportId, leaving that differentiation to the schema.

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

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

'Poll until status is succeeded, failed, or cancelled' gives an explicit usage pattern plus the exact terminal conditions that justify repeated calls. It stops short of stating polling cadence, timeout behavior, or what to do after a terminal failure 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 already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that this is a polling operation and that thumbnailUrl is present only "when available", which is real value, but it says nothing about polling cadence, terminal statuses, or how error details/attemptIndex behave across retries.

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 return payload and then the usage condition. No filler, no repetition of the tool name or 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 annotations covering the safety profile and an output schema present, the description does not need to enumerate return values, yet it briefly does anyway. The remaining gap is operational: no guidance on how often to poll or what status values indicate 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 100% and the single parameter already explains where to source toolExecutionId (start result or list_tool_executions). The description adds no parameter-level detail, so the baseline of 3 for fully documented schemas 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 (Return) and resource (tool execution snapshot) plus the fields it carries (status, progress, attemptIndex, error details, results), so the agent knows exactly what it gets. It does not name list_tool_executions or cancel_tool_execution, the nearest siblings, so differentiation is implied rather than 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?

"Use this to poll a started generation without creating another asset" gives a clear when-to-use condition and implicitly steers away from re-invoking a generation tool. It stops short of naming the alternatives (list_tool_executions, cancel_tool_execution) or stating exclusions, so it is context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: it is equivalent to the `guidance://tools-vs-workflows` resource and exists for clients that don't read resources directly, explaining why a read-only tool of this kind exists.

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

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

Three sentences, front-loaded with the purpose, then the invocation condition, then the resource-equivalence rationale. No sentence is redundant and each adds a distinct fact.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. Nothing required to call a zero-parameter guidance tool correctly is missing.

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

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

Zero parameters, so the baseline is 4. There is no parameter syntax to document, and the description correctly does not invent any.

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

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

States a specific resource (guidance on tools vs workflows) and the comparison it resolves. Among the several guidance siblings (get_workflows_guidance, get_getting_started_guidance, get_async_tasks_guidance), the topic is scoped clearly enough that an agent can pick the right one 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?

Explicitly names the trigger condition — 'Call when choosing between generate_* tools and workflow tools' — and identifies the alternatives at the decision point. The remaining behavior, actually invoking it, follows directly from that condition with nothing 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description earns credit beyond that by disclosing a conditional behavior: downloadUrl is only populated once auto-export has finished, which tells the agent how to interpret a missing field. It stops short of describing behavior for unknown or failed run IDs.

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, zero filler. The return payload is front-loaded and the usage constraint follows, so the agent gets the essential facts first.

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 read tool with full annotation coverage and an output schema that carries the return structure, nothing critical is missing. The description correctly focuses on scope and the one conditional output nuance rather than re-documenting 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 100% and the single parameter already documents the workflowRunId source ('from a workflow start result or list_workflow_runs'). The description adds no additional syntax, format, or lookup guidance for the parameter, so the baseline 3 is appropriate.

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

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

The description gives a specific verb and resource ('Return a workflow run') and enumerates the payload fields (status, progress, error details, projectId, projectUrl, downloadUrl), which is far more than a restatement of the name. It implicitly separates itself from list_workflow_runs and from project-starting tools, but never names an actual sibling, so differentiation is inferred rather than 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?

'Use this to poll an existing run without starting another project' states a clear usage context and an implicit exclusion (don't use it to create runs). It does not, however, contrast against nearby siblings such as list_workflow_runs (plural listing) or get_project_export, which an agent may confuse with 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 establish readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: it is a static guidance payload equivalent to the guidance://workflows MCP resource, and it exists specifically for clients that don't read resources — which tells the agent this call has no side effects and no input-dependent output variation.

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 tightly packed sentences, front-loaded with the primary purpose, then routing rules, then the trigger condition. Every sentence carries distinct information with no repetition of the name 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-value explanation is not required, and the description covers purpose, trigger timing, and the resource equivalence. For a no-input, read-only guidance tool this is fully 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?

The tool takes zero parameters, so there are no parameter semantics to document; the baseline for a 0-param tool is 4. Nothing in the description is needed here and nothing is misleading.

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 deliverable: the canonical run → remix → export flow plus when to use each workflow tool. This clearly distinguishes it from action siblings like script_to_video or remix_project. It does not explicitly differentiate itself from other guidance siblings (e.g., get_tools_vs_workflows_guidance, get_getting_started_guidance), which keeps it short of a 5.

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

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

Gives direct when-to-use instruction ('Call before starting a full video project') and even routes between alternatives ('Prefer script_to_video for longer narrated / informational videos; keep storyboard_to_video to ≤3 scenes unless the user asks for more'). That is explicit selection guidance an agent can act on without 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=false, idempotentHint=false and destructiveHint=false, and the description's 'producing a video' is consistent with that mutation profile. However, for a media-generation tool in a suite that exposes get_async_tasks_guidance and get_tool_execution, it says nothing about whether the call blocks or runs asynchronously, or about cost/latency.

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

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

One sentence, front-loaded with the action and ending with the output artifact. No filler or redundancy.

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 the parameter is fully documented in the schema. The remaining gap is operational: no hint that this is a likely long-running generation whose result may need polling via the async task tools present in the sibling set.

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 and schema description coverage is 100%: the schema itself explains that imageFileId comes from upload_file, list_files, or a succeeded image generation. The description adds nothing beyond that, so the baseline 3 applies.

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

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

States a specific transformation ('add 3D parallax motion to a still image') plus the output form ('producing a video'), which is enough for an agent to distinguish it from image-only siblings like upscale_image or vectorize_image. It stops short of naming any sibling alternative, so it doesn't reach the explicit differentiation 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?

The description contains no when-to-use or when-not-to-use guidance and names no alternatives, even though siblings such as generate_video_clip and script_to_video also produce video output. The agent must infer the selection context from the 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 already declare readOnly/idempotent/non-destructive, but the description adds real value beyond them by disclosing that built-in rows carry isBuiltIn=true and cannot be updated or archived. That immutability caveat is behavioral context the agent cannot get from the structured fields.

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

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

Three tight sentences, front-loaded with the resource enumeration, then immutability, then filtering. Little waste, though the listing could be slightly tighter.

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 entity kinds, immutability, and filtering. It leaves only the when-to-use-vs-get_entity routing implicit, which keeps it short of 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 description coverage is 100%, so the schema already documents limit, cursor, and entityType. The description only reinforces the entityType filter behavior, adding no syntax or format detail beyond the schema; baseline 3 is appropriate.

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

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

Specific verb ('List') plus resource ('entities'), with an explicit enumeration of what kinds are returned: built-in actors, products, visual styles, slideshow themes, plus team entities like brands, locations, props. This clearly distinguishes it from sibling list tools such as list_files and list_projects.

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

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

It offers one usage hint ('Filter with entityType when you only need one kind'), which is a genuine when-to-use condition. However, it never routes the agent toward get_entity for single-entity retrieval or names any alternative/exclusion, so guidance is implied rather than explicit.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds the key-scoping constraint, which is useful context beyond annotations, but says nothing about pagination behavior or return shape.

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 tight sentence with the scope constraint front-loaded and no filler. 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for a list tool in a large sibling set, the absence of pagination guidance and sibling differentiation leaves clear gaps.

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

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

Schema coverage is 100%, so limit and cursor are fully documented in the schema. The description adds no parameter-level detail; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (files) with a scoping qualifier ('visible to the current API key'). This distinguishes it from get_file and create_file_upload, but does not explicitly differentiate from sibling list_* tools.

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

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

No statement of when to use this tool versus alternatives like get_file for a single file. The scope qualifier implies a per-key listing but no exclusions or routing guidance are provided.

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, non-destructive and closed-world, so the safety profile is fully covered. The description adds only the returned field pair (languageCode + English name), which is largely duplicated by the output 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 tight sentences: the return content first, then the intended use. Nothing is redundant and the purpose is front-loaded.

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 rich annotations, a full output schema, and a single fully-documented optional parameter, the definition supplies everything needed to call it correctly. Only marginal detail, such as which language set is covered, 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 optional 'query' parameter with 100% schema description coverage, so the schema fully documents the substring-filter behavior. The description adds no syntax or filtering detail beyond that, which is the correct baseline when the schema does the work.

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

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

Specific verb and resource ('Return supported narration and caption languages') plus the shape of each entry (languageCode and English name pairs). An agent can distinguish this lookup tool from list_tts_voices and other list_* siblings from the description alone.

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 the downstream use: 'Use these codes when selecting workflow output languages,' which tells the agent when to reach for this tool. It stops short of naming alternatives or stating when not to use 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, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds value beyond that by disclosing the polling workflow and that pagination metadata is included. It does not mention rate limits or how large a result set can be, which matters for a polled list endpoint.

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

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

Two sentences with zero filler: the first covers the return payload, the second the usage trigger. Front-loaded and 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 needn't be spelled out, and the annotations carry the safety profile; the description still covers purpose and the polling use case. The one unaddressed point is that pagination metadata is returned with no corresponding input parameter, leaving the agent unsure whether it must page or always receives the full set.

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

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

Only one parameter and schema description coverage is 100%; the schema itself explains projectId and where to obtain it (workflow result or list_projects). The description adds no syntax, format, or filtering semantics beyond that, so the baseline 3 for schema-covered parameters applies.

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

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

States a specific verb and resource (return remix actions for a project) and enumerates what each action record contains (ids, types, status, progress, attempts, errors), so the agent knows exactly what it gets. However, it never differentiates itself from the other readiness-oriented sibling get_project_export, which an agent could plausibly confuse for the 'edits ready for export' check.

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?

Second sentence is a genuine routing cue: poll after remix_project to learn when edits are ready for export. That answers 'when do I call this' clearly. It stops short of stating when NOT to use it (e.g., use get_project_export for export status, or list_tool_executions for other async work).

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 bar is low. The description nonetheless adds real behavioral context: results are scoped to the authenticated team, ordered most-recently-updated first, and paginated via a cursor.

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

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

Two tight sentences, front-loaded with scope and ordering before the return/pagination note. No filler; every clause carries information.

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

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

With an output schema present, the return-value enumeration is mildly redundant but harmless. Scope, ordering, and pagination are covered; only the selfOnly team-vs-owner distinction 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 100%, so the three parameters are fully documented in the schema and the baseline is 3. The description adds no parameter-level detail (selfOnly, limit, cursor are untouched), so it neither helps nor hurts.

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

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

The description gives a specific verb (browse/list) and resource (projects), scoped to the authenticated team and including dashboard-created ones. It distinguishes scope well, though it never names the single-item sibling (get_project) the way a 5 would.

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 only implied: 'browse' and the mention of a pagination cursor suggest a discovery/listing use case, but there is no explicit when-to-use vs get_project or when-not guidance. Adequate but leaves selection 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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description's contribution is the result ordering ('most recent first'); it says nothing about default page size, total counts, or whether results are team-scoped, though selfOnly and cursor in the schema hint at these.

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 short sentence with the ordering guarantee front-loaded alongside the purpose. There is no filler and nothing to trim.

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 explanation is unnecessary, and the annotations cover the safety profile. The only real gap is the absence of any routing hint toward get_tool_execution versus this list tool, which for a 48-sibling suite would be valuable.

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%, with all three optional parameters (limit, cursor, selfOnly) documented inline including the limit maximum and the cursor's origin. The description adds no parameter-level detail beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb and resource ('List past tool executions') plus an ordering guarantee ('most recent first'), which the schema does not convey. It implicitly contrasts with the singular sibling get_tool_execution, but never names it, so the list-vs-get distinction is left for the agent to infer.

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 only implied: 'past tool executions' hints at a history/audit use case, but there is no explicit when-to-use guidance and no mention of when to prefer get_tool_execution for a single record. With 48 siblings including near-duplicates, that omission matters.

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, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral value beyond that: pagination via nextCursor and the supportsDirectToolExecution gating rule that determines whether a returned voice is usable by text_to_speech.

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 with zero filler, front-loaded with the returned resource and fields before the usage instruction. 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 enumerating return fields is partly redundant, but the mention of supportsDirectToolExecution supplies the one cross-tool decision rule the schema cannot. Pagination and filtering are fully covered, leaving no functional gap for a four-parameter, zero-required list 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%, so the schema already documents limit, query, cursor and includeDeprecatedVoices. The description only echoes cursor (as nextCursor) and deprecation status without adding syntax, defaults, or filter semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb ('Return a page of') and resource ('narration voices'), then enumerates the returned fields. No sibling tool lists voices, so the resource name alone distinguishes it from list_languages, list_files, and the other list_* tools.

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

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

Explicitly routes the agent: 'Use a voice with supportsDirectToolExecution true for text_to_speech' names the downstream tool and the selection condition, and 'nextCursor fetches more voices' explains how to continue paging. It stops short of saying when to call this versus e.g. hardcoding a voiceId, so it is strong but not exhaustive.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the bar is low. The description still adds real context beyond them: results are ordered most-recent-first, paginated via nextCursor, and can omit export URLs when unavailable, which flags potentially missing 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?

A single front-loaded sentence that leads with the action and resource before enumerating fields. It is slightly dense with an inline field list, but every clause carries 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?

An output schema exists, so return values need not be re-explained, and annotations carry the safety profile. The description still supplies ordering and pagination behavior, leaving only the list-vs-single vs cancel routing to inference, 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 100% and all three parameters (limit, cursor, selfOnly) are documented there. The description only echoes the pagination cursor concept via nextCursor, adding little syntax or format detail beyond the schema, so baseline 3 applies.

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

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

Clear verb ('Return a page of') plus specific resource ('workflow runs'), with useful scope detail like ordering ('most recent first') and returned fields. It does not explicitly distinguish itself from the sibling get_workflow_run, so an agent must infer the singular/plural split.

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 guidance on when to reach for this versus get_workflow_run (single run) or cancel_workflow_run. The list semantics are implied by the name, but there are no stated conditions, exclusions, or named 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavior: the two-phase async nature (launch status returned now, file id only after the user finishes), client gating, and the consumer tools. Not a 5 only because it doesn't mention auth or failure/timeout behavior when the user never completes the upload.

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 purpose, then downstream use, then preference, then fallbacks and return behavior. No filler and each sentence carries distinct information.

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

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

With an output schema present, annotations covering safety, and zero parameters, the description supplies everything else an agent needs: platform constraint, fallback routing, the id format, the consumer tools, and the asynchronous return timing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond noting that the file id arrives asynchronously rather than as an argument.

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 ('Open an in-chat file uploader') plus the platform gate (ChatGPT only) and the payload produced (vg_file_... id for downstream video tools). An agent can distinguish it from upload_file/create_file_upload immediately.

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 fallbacks (upload_file for small files, create_file_upload for large files) and the condition selecting them (clients without in-chat UI), and states a preference rule ('Prefer this over asking the user to paste a link'). This is exactly the when/when-not/alternative guidance wanted.

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

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

Annotations declare a non-read-only, non-destructive, non-idempotent, closed-world mutation, and the description adds meaningful behavior on top: it creates a new editable project and is asynchronous, requiring polling of get_workflow_run, with auto-export producing an MP4. That async lifecycle and the project side effect are not derivable from the annotations alone.

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

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

Two dense sentences with zero waste; the core action is front-loaded and the async follow-up is second. Every clause (new editable project, returned IDs, polling target, auto-export) 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 6-parameter creation tool with an output schema present, the description covers the async return lifecycle and the auto-export path without needing to restate return values. The remaining gap is sibling selection (generate_video_clip vs. this tool), which is left unresolved.

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

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

Schema description coverage is 100%, so the schema already documents prompt, quality, autoExport, aspectRatio, imageFileIds, and durationSeconds in detail, including the autoExport/remix_project interaction. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a concrete verb and resource: 'Generate one short AI video clip from a prompt inside a new editable project,' which is specific about scope (single clip, new project). However, it never distinguishes itself from the sibling generate_video_clip, whose name implies a near-identical job, so an agent cannot tell the two apart from the text alone.

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 second sentence gives a clear follow-up pattern ('poll get_workflow_run for status and downloadUrl after auto-export'), which is useful operational guidance. But there is no when-to-use vs. when-not guidance relative to generate_video_clip, script_to_video, storyboard_to_video, or the other video-producing siblings, so selection 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?

With destructiveHint=true and readOnlyHint=false already declared, the description still adds real context: the original project is edited in place unless saveAsNewProject is true, the expensive operation is called out by cost, and the async nature is disclosed via the polling instruction. This is exactly the additional context annotations cannot carry.

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

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

Four short sentences, zero filler, front-loaded with the core action and the mutation semantics before cost and polling details. Every sentence carries actionable information.

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

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

An output schema exists so return values need not be described, and the description covers the remaining essentials: mutation semantics, cost tradeoff between edits, and the follow-up polling tool for async status. Nothing needed to invoke it safely is missing.

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

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

Schema description coverage is 100%, and the schema already documents saveAsNewProject, projectId sourcing, and each edit enum value in detail. The description's parameter-related content (saveAsNewProject behavior, ZOOM vs CONVERT) largely repeats the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Apply curated edits to an existing project') and immediately disambiguates scope from generic generation siblings by framing it as editing an existing project. The in-place-vs-copy behavior further pins down what kind of operation this is.

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

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

Gives explicit selection guidance between edit modes: CONVERT_IMAGES_TO_VIDEOS is expensive, ZOOM is the cheap Ken Burns option, and it names list_project_remix_actions as the polling tool. It does not, however, say when to prefer remix_project over sibling generators like slideshow_to_video or generate_video_clip.

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

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

The description adds substantial texture beyond the annotations: it discloses the operation is a soft-archive (not a hard delete), that a default reference promotes a replacement, that the response is the entity with its remaining references, and that built-in entities are ineligible. The 'retrying can fail because it is no longer active' note sits in mild tension with idempotentHint=true, though soft-archiving is still idempotent in effect, so this is a nuance rather than a contradiction.

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 compact sentences, each front-loading the most important fact (soft-archive, no source deletion) with no filler. Slightly dense and the return-value sentence is partly redundant given an output schema exists, but nothing is wasted.

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

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

Given an output schema already exists, the description need not explain the return payload, yet it usefully confirms what comes back. Combined with the soft-archive semantics, default-promotion behavior, retry caveat, and built-in restriction, it is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description adds no syntax, format, or constraint detail about entityId/fileId beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Soft-archive a reference attachment on a team entity.' The scope (reference attachment vs. source file) and the contrast with sibling tools add_entity_reference and archive_entity are unambiguous, so an agent can select 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?

Provides a clear exclusion ('Built-in entities cannot have references removed') and a safety precondition ('without deleting the source file'), giving the agent solid context for when the call is valid. It stops short of explicitly naming an alternative tool or the when-to-use-vs-sibling routing, which keeps it below 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?

Adds real behavior beyond the annotations: the source file is left unchanged (clarifying that the mutating, non-destructive, non-idempotent operation does not overwrite the original) and that execution is asynchronous and must be polled via get_tool_execution. It stops short of describing failure modes or processing 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 short sentences with zero filler: purpose first, then the safety-relevant guarantee, then the async retrieval path. Every sentence earns its place and the most important facts are front-loaded.

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 explanation is not required, yet the description usefully points to get_tool_execution for status and results. Coverage of the input contract and the async lifecycle is adequate, with only the lack of any error/timeout context keeping 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?

Only one parameter and schema description coverage is 100%, so the schema already defines imageFileId and its acceptable sources. The description references the 'source file' only implicitly and adds no format or constraint detail beyond the schema, which is the expected baseline.

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

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

States a specific verb and resource ('Create a new image with the background removed'), which cleanly distinguishes it from the sibling remove_video_background and from vectorize_image/upscale_image. An agent can select 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?

The description implies the async workflow by stating it returns a toolExecutionId and that get_tool_execution provides status and results, which is genuine usage guidance. However, it never states when to choose this over siblings like remove_video_background or what input images qualify beyond the schema's own note.

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 non-read-only, non-destructive, non-idempotent profile. The description adds genuinely useful behavior beyond that: the source file is left unchanged, the call is asynchronous, and the output arrives via get_tool_execution rather than in the response.

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, each carrying distinct information: the action, the non-destructive guarantee, and the async result path. Front-loaded with the effect and 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 one-parameter async tool that has an output schema, the description covers everything an agent needs: what is produced, that the input is preserved, and how to retrieve the result. Nothing material is left implicit.

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

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

There is a single parameter with 100% schema description coverage, and the schema already explains where to source the videoFileId. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a concrete verb and resource ('Create a new video with the background removed') plus the key scope fact that the source is untouched. An agent can distinguish it from remove_image_background purely from the 'video' resource in the first sentence.

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

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

The description explains the async handoff ('get_tool_execution provides status and results'), which tells the agent how to complete the operation, but it never states when to choose this tool over siblings like remove_image_background or the various generate_* tools. Usage is implied rather than directed.

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 a non-destructive, non-idempotent, closed-world write, so the safety profile is covered. The description adds useful behavioral context beyond that: the run yields an editable video (implying a remix path) and narration can be actor-driven via actorEntityId with an avatar quality tier. It stops short of stating run duration or export/async behavior (which the schema's autoExport note carries), so it is a solid 4 rather than 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?

Three sentences, each load-bearing: preference/scope first, core transformation second, sibling routing third, avatar note last. The most decision-relevant information is front-loaded with zero 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-parameter write tool with full schema coverage, nested objects, annotations, and an output schema, the description covers routing, scope, and the avatar mode adequately. Return-value and export mechanics are correctly left to the output schema and the autoExport description, so only minor gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning by tying actorEntityId and avatarQuality together into a coherent avatar-narration mode. This goes beyond the per-field schema text by explaining how the parameters combine.

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

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

States a specific verb and resource ('Turn a verbatim narration script into an editable video') plus the concrete output attributes (AI-generated visuals and captions). It also explicitly distinguishes itself from the sibling alternative storyboard_to_video, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use ('narrated / informational / explainer videos... ~1 minute or longer'), names the alternative ('Prefer this over storyboard_to_video'), and states the exclusion ('unless the user wants a short shot-directed storyboard'), plus the avatar-narration condition. 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 the safety profile (not read-only, not idempotent, not destructive), and the description adds meaningful async context: it returns workflowRunId/projectId/projectUrl and that progress and downloadUrl come via get_workflow_run after auto-export. This tells the agent the call is a long-running job requiring polling, which annotations alone would not convey.

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

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

Four tight sentences, front-loaded with purpose, then prerequisite, then the avatar parameter path, then returns and the next step. Every sentence carries actionable content 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 complex 9-parameter async creation tool with nested objects, the description covers the source prerequisite, the optional avatar branch, and the polling follow-up, and an output schema exists so return values need not be enumerated. It is close to complete, though the theme/autoExport decision points 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 coverage is 100%, so the schema already documents all nine parameters, including the upload relationship for fileId and the avatar conditions. The description reinforces the fileId prerequisite and avatar path but adds little beyond what the schema descriptions already state, so baseline 3 applies.

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

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

States a specific verb and resource ('Build an editable narrated video') and scopes the input source ('from an uploaded PDF or slideshow file'), which distinguishes it from sibling video tools that take scripts, storyboards, or voiceovers. It stops short of naming those siblings explicitly, so 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?

Gives a concrete prerequisite chain ('Upload the file first with upload_file, then pass its fileId') and conditional guidance for the avatar path ('For avatar narration, pass actorEntityId and optionally set avatarQuality'). It does not say when to prefer this over voiceover_to_video or script_to_video, so no explicit alternatives 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 only declare the mutation profile (non-readonly, non-idempotent, non-destructive) and the description goes well beyond that: it discloses the credit-cost characteristic ("Much more credit-heavy than script_to_video"), the entity-attachment mechanic ("A prompt alone does not attach those images"), and a prerequisite workflow. It does not mention auth/permissions or rate limits, so not a perfect 5, but it is rich behavioral 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?

Front-loaded with the core action, then the entity mechanics, then cost/routing constraints — every sentence carries distinct, load-bearing information with no repetition of the schema.

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

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

For a 7-parameter nested-object tool with an output schema, the description covers the decision, the cost tradeoff, the entity prerequisite workflow, and the alternative tool. Return values are handled by the output schema, so nothing an agent needs before calling 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. The description nevertheless adds meaning beyond the schema by linking the entity parameters to required setup calls ("create_entity and add_entity_reference first") and clarifying the per-scene vs project-level duplication of productEntityIds/actorEntityIds. That cross-parameter guidance is genuine added value.

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

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

States a specific verb+resource ("Build an editable video from an ordered storyboard (frame-by-frame shot list)") and explicitly distinguishes itself from the sibling script_to_video. An agent can tell this apart from script_to_video, slideshow_to_video, and prompt_to_video_clip without opening any schema.

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

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

Gives concrete when-to-use rules (at most 3 scenes unless the user asks for more), a named alternative with its selection condition ("Prefer script_to_video for ~1 minute+ narrated / informational videos"), and a gating instruction to ask the user before calling when no workflow is named. This is exemplary 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 only cover the safety profile (not read-only, non-destructive, non-idempotent); the description adds genuinely new behavior: async execution returning toolExecutionId, the need to poll, and the synchronous short-circuit for local calls. It also introduces the 'supportsDirectToolExecution' voice constraint, which is meaningful context. Missing error/timeout behavior keeps 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?

Three compact sentences, front-loaded with what the tool produces, followed by the async contract. Minor redundancy in restating return fields covered by the output schema, but 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 listing fileId/downloadUrl/file metadata is somewhat redundant, but the description correctly covers the async polling lifecycle and the local synchronous path. No required parameter is left unexplained.

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

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

Schema description coverage is 100%, so the schema already documents text, speed, voiceId, and language with format and bounds. The description only adds a quality constraint on voiceId (must support DirectToolExecution). Baseline 3 is appropriate since the schema does the heavy lifting.

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 (synthesize) and resource (spoken audio from text) and ties it to a catalog voice, which cleanly separates it from generate_music and generate_sound_effect siblings. It does not explicitly address the closest alternate, voiceover_to_video, so it falls just short of full sibling differentiation.

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

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

The description gives a real usage instruction – poll get_tool_execution for status/results on hosted clients – and names list_tts_voices as the source of voiceId. However, it never states when to prefer this over the adjacent audio-generation siblings, so usage is implied rather than fully guided.

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