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

Annotations only declare the generic mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds real behavioral context beyond that: entity-type restrictions, accepted file formats, and the ordering dependency on create_entity. It stops short of disclosing idempotency, overwrite behavior, or failure modes, so it is strong but not complete.

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

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

Four tight sentences, front-loaded with the core action before constraints and the workflow tip. No filler, and the most important scoping rule (built-in entities excluded) is stated plainly.

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. For a non-destructive mutation tool with full schema coverage and annotations, the description covers constraints, file-type rules, and call ordering, which is 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?

Schema coverage is 100%, so the baseline is 3. The description goes further by tying isDefault to a concrete workflow step (setting the usable thumbnail/generation reference right after entity creation), which adds selection meaning beyond the schema's plain 'primary reference (thumbnail)' phrasing.

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 (attach) and resource (uploaded file as a reference on an entity), with the file id prefix (vg_file_...) making the input type unambiguous. It is clearly separable from siblings like remove_entity_reference, upload_file, and 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: images work for all entity types, PDF/PowerPoint only for slideshow themes, built-in entities cannot take references, and new PRODUCT/ACTOR entities should call this immediately after create_entity with isDefault: true. This is exactly the routing and prerequisite guidance an agent needs.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: archived entities disappear from lists and pickers, and built-in entities cannot be archived. It could disclose more about reversibility or permission requirements, but it meaningfully exceeds the structured hints.

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

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

Two short sentences, front-loaded with the primary action and immediately followed by the most important constraint. Every sentence earns its place 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?

For a one-parameter, destructive mutation tool with full schema coverage, annotations, and an output schema, the description covers the key behavior and a critical caveat. It is nearly complete, though it leaves some operational details unstated, such as whether archiving is reversible or what permissions are required.

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

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

Schema coverage is 100% and the single required parameter entityId is fully documented in the schema as an entity ID with a vg_enti_ prefix example. The description does not add syntax, format, or meaning beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description gives a specific verb and resource, 'Archive an entity,' and states the observable effect: it no longer appears in lists or pickers. It also distinguishes archive behavior from sibling retrieval and listing tools by focusing on removal from visibility, making the intent clear without opening schemas.

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

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

The description implies usage by stating the effect and a key exclusion: built-in entities cannot be archived. However, it does not explicitly say when to choose archive_entity over update_entity, remove_entity_reference, or other mutation tools, so the 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 destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds a modest but real nuance by saying 'Request' cancellation, implying best-effort/asynchronous behavior rather than guaranteed termination, and 'in-progress' bounds which executions are eligible — but it never states what happens to partial output or whether cancellation is final.

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

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

A single front-loaded sentence with no filler, which is efficient. It is borderline under-specified rather than over-concise — the brevity costs it the usage and behavioral detail it could have carried.

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 destructive profile. Still, for a mutation/cleanup tool the description lacks timing semantics (immediate vs deferred cancellation), idempotency, and any note on required permissions, leaving an agent with the minimum needed to invoke it.

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

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

There is one parameter and schema description coverage is 100% (the schema documents the vg_tool_... id format), so the description's single sentence adds no parameter 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?

Specific verb (cancel) plus specific resource (tool execution), and it scopes the target to an in-progress execution, which distinguishes it from get_tool_execution/list_tool_executions. It does not, however, mention the near-identical sibling cancel_workflow_run, so an agent must infer the boundary from the 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?

No when-to-use or when-not-to-use guidance is given. With cancel_workflow_run sitting in the same toolset, the description offers nothing to route between cancelling a tool execution versus a workflow run, and no prerequisites (e.g. needing a live execution id) are stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this mutates state. The description adds one genuinely useful nuance beyond that: 'Request' implies the cancellation is asynchronous and may not take effect immediately. It still omits idempotency, whether in-flight work is discarded, and permission requirements for 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?

A single front-loaded sentence with zero waste; the destructive/async action leads. It is arguably under-specified rather than over-long, but as structure goes it is efficient and well-ordered.

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 destructive tool with an output schema and explicit destructive annotations, the description covers the essentials but leaves meaningful gaps: no outcome/return behavior, no note on whether a cancelled run can be resumed, and no routing to sibling cancel/get tools. Adequate, not 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% — the single workflowRunId parameter is documented with its 'vg_work_...' prefix format. The description adds no syntax or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (cancel) and resource (workflow run) plus a scope qualifier ('in-progress'), which clearly distinguishes it from list/get workflow-run tools. It does not, however, differentiate itself from the nearby cancel_tool_execution sibling, which an agent could plausibly confuse for the same intent.

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

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

There is no guidance on when to use this versus get_workflow_run, list_workflow_runs, or cancel_tool_execution, and no prerequisites or exclusions (e.g., only pending/running runs can be cancelled). The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the mutation/safety profile is covered structurally. The description adds genuinely useful behavior: creation alone is insufficient (a reference must follow), and the type-to-downstream mapping. It stops short of stating idempotency or failure/limit behavior, so not 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, zero filler, front-loaded with the create action followed by the required follow-up step and the downstream consumption. Every clause carries distinct operational information.

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

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

With an output schema present, return values need not be explained, and the description covers the remaining unknowns: valid types, the mandatory reference attachment, file upload ordering, and where entityId is reused. Nothing an agent needs to call and chain this tool is missing.

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

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

Schema coverage is 100%, so entityType, name, and description are already documented with rich enum comments. The description still adds value by linking each entity type to the downstream parameter it feeds (actorEntityId, product/style reference, slideshowThemeEntityId), which the schema does not say. Slightly above the baseline for that extra mapping.

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?

Starts with a specific verb+resource ('Create an ACTOR... PRODUCT... VISUAL_STYLE... SLIDESHOW_THEME entity') and enumerates exactly what can be created, distinguishing it from sibling mutation tools like update_entity or archive_entity. An agent immediately knows this is the entity-creation entry point.

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 post-create requirement ('attach at least one reference with add_entity_reference (upload the file first)'), names the prerequisite tool and ordering, and spells out where the returned entityId is consumed (generate_avatar, script_to_video, storyboard scenes, slideshow_to_video). This is a full workflow route, not just a hint.

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 establish that this is a non-destructive, non-open-world write. The description adds critical operational behavior the annotations cannot: the return shape { fileId, uploadUrl }, the requirement to PUT raw bytes with NO Authorization header to a short-lived pre-signed URL, and the follow-up get_file call to await processing. That is exactly the extra context that makes invocation succeed.

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

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

Four dense sentences, front-loaded with the triggering condition and return contract, then the transport instruction and the follow-up call. Every sentence carries unique operational value; 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?

Despite having an output schema, the description fully covers the end-to-end flow (create → PUT bytes → get_file wait → consume fileId), which is what an agent needs to chain this multi-step upload correctly. 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 all three parameters (type, displayName, isTemporary) are already documented including enum values and defaults. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Start an upload for a large file, or when file bytes cannot be inlined') and explicitly distinguishes itself from the sibling upload_file ('For small files, prefer upload_file'). An agent can route correctly 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 bytes cannot be inlined), an explicit alternative for the opposite case (small files → upload_file), and the required follow-up sequence (PUT bytes, then get_file with wait:true). 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 only give the generic safe-mutation profile (not read-only, not destructive, not open-world). The description adds genuinely new behavioral context: the operation is asynchronous, latency is minutes-scale, and the response may be a status rather than a finished file. It does not mention whether the export can be cancelled or re-run, so it falls short of a 5.

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

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

Two short sentences, front-loaded with the core action, and every clause carries information (return shape, latency, user-facing messaging). The trailing 'Tell the user that wait up front' is slightly awkwardly phrased but earns its place as an instruction.

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

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

An output schema exists, so return-value explanation is correctly omitted, and the annotations cover the safety profile. The async/latency disclosure plus the return-shape hint make this sufficient for correct invocation, though a note about follow-up polling via get_project_export or task listing would have closed the loop.

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 only two parameters (projectId and an enum quality with its own 'Omit for the default' note), so the schema already carries the semantics. The description adds nothing about parameter meaning; 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 ('Export a project to an MP4') plus the return shape ('status or download URL'), which is far more than the bare title. It implicitly distinguishes itself from the sibling get_project_export (which retrieves an existing export) but never names that sibling explicitly.

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

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

The timing note ('Renders often take a few minutes. Tell the user that wait up front') gives real operational context for a long-running job. However, it offers no guidance on when to choose this tool over get_project_export or the async-task/guidance siblings, so usage selection is only implied.

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

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

Annotations only declare the safety profile (readOnly=false, destructive=false, openWorld=false). The description adds genuinely new behavioral context: generation takes 'a few minutes (longer for longer audio)' and the agent should tell the user about the wait up front. That latency/UX disclosure is exactly what annotations do not cover.

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 core action, then optional parameter, then the latency caveat and user-facing instruction. Nothing is wasted, though the final instruction sentence is more UX coaching than tool semantics.

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. The latency expectation is supplied, leaving sibling differentiation as the only meaningful gap. Adequate for a 3-parameter async generation 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 actorEntityId, audioFileId and the avatarQuality enum tiers. The description only restates that actorEntityId is passed and avatarQuality is optional, adding no format or constraint 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?

The description states a specific verb and resource: 'Generate a talking-head avatar video from an ACTOR entity and an uploaded audio file.' That is clearly distinguishable from generic siblings like generate_video_clip or prompt_to_video_clip, though it never names an alternative to route against.

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 notes the two required inputs implicitly but gives no when-to-use or when-not-to-use guidance, and does not distinguish itself from the other video-generation siblings such as generate_video_clip or script_to_video. The only routing signal is the input type (actor + audio).

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

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

Annotations only declare the safety profile (not read-only, not open-world, not destructive), so the description's latency disclosure ('typically takes 15–60 seconds') and the explicit instruction to tell the user about the wait add real behavioral value an agent cannot infer from structured fields. It stops short of covering cost, failure modes, or whether generation is cancellable.

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 purpose and the conditioning modes, followed by the single operational caveat that matters to an agent. No filler or restatement of the tool name.

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

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

For a 5-parameter generative tool with a nested aspect-ratio object and an output schema, the description covers purpose, modes, and latency, and the output schema relieves it of explaining return values. It is nearly complete, though it omits any mention of cost, concurrency, or how generation interacts with workflow/tool-execution siblings.

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

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

Schema description coverage is 100%, so prompt, quality, entityIds, aspectRatio, and imageFileIds are already documented in the schema itself. The description restates the conditioning inputs at a high level without adding syntax, constraints (e.g., the 4-image cap), or defaults beyond what the schema provides; 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?

Specific verb ('Generate') plus resource ('an image') with the two operating modes spelled out: text-to-image and image-to-image conditioned on source images/entity ids. This distinguishes it from siblings like generate_video_clip, generate_avatar, and upscale_image without needing to open the schema.

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

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

The description implies usage by describing optional conditioning modes, but never states when to prefer this over siblings (e.g., vs. generate_avatar for actor likeness, or upscale_image for refinement). No exclusions or prerequisites are given; the only imperative is the latency warning to relay to the user.

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

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

Despite annotations covering safety (readOnlyHint=false, destructiveHint=false), the description adds rich behavioral disclosure: default transparent WebM output vs opaque MP4, 2–5 minute render time because VideoGen writes animation code then renders, longer for complex prompts, and polling expectations. This is exactly the extra context the annotation set cannot 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?

Front-loads the purpose, then gives use-case, output format, references, timing, and polling guidance in tight sentences. Every sentence earns its place; no redundancy or 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 7-param tool with nested objects, the description covers use case, output format, timing expectations, and polling behavior, and an output schema exists so return values needn't be explained. The few uncovered params are fully documented in the schema, leaving no critical gap for an agent to call it correctly.

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

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

Schema description coverage is 86%, so the schema already documents most parameters (including the transparentBackground default and aspectRatio semantics). The description reinforces transparentBackground and fileIds ('reference media file ids to display or animate') but omits entityIds, subToolModes, and durationSeconds. Baseline 3 is appropriate 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+resource ('Generate an animated motion graphic video from a text prompt') and immediately distinguishes it from siblings by scoping it to precise text animations (typing effects, kinetic typography, lower thirds) that stock/generated footage can't express. An agent can tell this apart from generate_video_clip or prompt_to_video_clip without opening their schemas.

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

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

Gives clear when-to-use guidance ('Best for precise text animations...') and contrasts implicitly against stock/generated footage alternatives. It also adds operational guidance (wait 2–5 minutes, keep polling calmly). It stops short of naming specific sibling tools or explicit when-not-to-use conditions, so not a full 5.

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

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds the critical long-running latency trait and an explicit UX instruction about surfacing the wait. It does not clarify whether the call blocks or returns an async handle.

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

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

Three short sentences, front-loaded with the core action, then the latency constraint, then the actionable instruction to the agent. 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?

Output schema exists so return values need no explanation, and the latency trait is disclosed. The main remaining gap is whether this is an async/task-based call that later surfaces via list_tool_executions, which matters given the sibling task-management 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?

There is a single required parameter with 100% schema coverage, and the schema description ('Genre, mood, instrumentation, and tempo') is actually richer than the description's generic 'text prompt'. Baseline 3 applies since the schema already 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 (generate) and resource (music track) from a text prompt, which cleanly separates it from siblings like generate_sound_effect, text_to_speech, and generate_video_clip. 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 gives operational guidance (1-5 minute wait, tell the user up front) but no tool-selection guidance explaining when to prefer this over generate_sound_effect or other audio siblings. Usage is implied by the resource name rather than stated.

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

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

Annotations already declare the safety profile (readOnlyHint=false, openWorldHint=false, destructiveHint=false), and the description adds nothing beyond that: no latency, cost, async/job behavior, or output format context. For a generative tool with an output schema it could still note operational traits, but it repeats only 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?

A single efficient sentence with no waste, and the key information is front-loaded. It is appropriately sized, though it is so short that it borders on under-specification rather than true conciseness.

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

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

The output schema covers return values and the tool only has two parameters, so the description needn't explain much. However, given three audio-generating siblings and an undocumented parameter, an agent lacks the routing and parameter guidance needed to call this confidently.

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

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

Schema coverage is only 50%: the prompt parameter is documented in the schema and echoed by the description ('text prompt'), but durationSeconds has no description anywhere and the description does not compensate with range or default information. The description adds no meaning beyond the schema.

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

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

States a specific verb and resource ('Generate a sound effect') plus the input modality ('from a text prompt'), so the agent knows exactly what the tool produces. It does not differentiate itself from the closely related siblings generate_music and text_to_speech, which is the only gap.

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

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

There is no guidance on when to choose this tool over generate_music or text_to_speech, despite both being present in the sibling list and producing audio. Usage is only implied by the name.

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

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

Annotations cover the safety profile (not read-only, not destructive, closed-world), so the bar is lower. The description adds genuinely non-structured behavior: expected latency of 1-3 minutes with HIGH/MAX running longer, and the polling expectation. It could go further on failure/retry behavior, but this is solid added 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?

Three sentences, front-loaded with the core action, then optionality, then operational timing. The final 'keep polling calmly' sentence is informal but earns its place as behavioral guidance. No significant padding.

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, all-optional generation tool with a full schema and an output schema, the description supplies the missing non-schema essentials: input modalities and expected latency. Sibling disambiguation is the one notable 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 every parameter (quality enum, aspectRatio units, audioFileIds vs spokenDialogue, durationSeconds, suppressBackgroundMusic) is already documented in the schema. The description repeats the quality enum values and names some input types without adding format or interaction 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 (generate) and resource (video clip) and enumerates the accepted input modalities (text prompt, images, videos, spokenDialogue, reference audio). It does not, however, distinguish itself from the sibling prompt_to_video_clip or storyboard_to_video, which appear to overlap in purpose.

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

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

It gives practical operating guidance (expect 1-3 minutes, keep polling calmly, warn the user up front), which is useful when-context. But it never states when to pick this tool over prompt_to_video_clip, storyboard_to_video, or script_to_video, so routing between siblings is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered externally. The description adds genuinely new behavior: the link only resolves after sign-in, it targets modals vs. navigation, and the agent must hand the URL back to the user rather than expecting an inline effect.

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 purpose before the usage guidance. The parenthetical action list is somewhat redundant with the enum but it efficiently conveys scope in one clause rather than bloating the text.

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 8 parameters, 1 required, an output schema present, and annotations covering safety, the definition supplies what an agent needs: what the tool produces, when to prefer it, and what to do with the result. Remaining gaps (per-action parameter requirements) are already handled by the 100%-covered 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 each parameter (including the action enum, provider, articleSlug, destination) is already documented in the schema. The description restates the action family in prose (upgrade, buy credits, top-ups, invites, feedback, integrations, settings, NAVIGATE) but adds no format, constraint, or conditional detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and artifact ('Build a VideoGen app URL') plus the outcome ('opens a modal or navigates after the user signs in'), and enumerates the concrete destinations. This is clearly distinguishable from the generation/entity-management siblings, which operate on assets rather than producing in-app links.

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 selection condition: 'Prefer this when the user needs to complete something in the VideoGen UI that MCP tools cannot do inline — especially credits or plan gates,' and states the follow-through ('Return the url to the user'). It doesn't name a specific alternative sibling, but the condition is unambiguous enough to route the agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond that: it enumerates the content covered (statuses, hosted vs local wait caps, polling, webhook scope) and discloses that it is an equivalent substitute for the `guidance://async-tasks` resource for clients that don't read resources. It says nothing about the shape of what is returned, though an output schema 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 tight sentences: scope first, trigger second, resource equivalence last. No restatement of the title and 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?

For a zero-parameter documentation tool with an output schema, the description supplies purpose, trigger, and content coverage. Return-value detail is correctly left to the output schema, so nothing necessary for correct invocation is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description correctly implies a parameterless, read-only lookup and adds no misleading parameter guidance.

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 the exact subject matter (async workflows, tool executions, exports: statuses, wait caps, polling, webhooks) and frames the tool as documentation rather than an action, which cleanly separates it from the action siblings like list_tool_executions and get_tool_execution. It never distinguishes itself from the other guidance siblings (get_workflows_guidance, get_tools_vs_workflows_guidance, get_getting_started_guidance), so sibling differentiation is missing.

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 stated as an explicit trigger: "Call before polling or when a start tool returns a still-running snapshot." That is a concrete when-to-use condition tied to observable agent state, not an implication the agent has to infer.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds useful return context (reference images are bundled, built-in entities are included and flagged), which is genuine value beyond annotations, but it says nothing about error behavior for unknown ids or auth needs.

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

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

Two short sentences, front-loaded with the core action and followed by scope notes. Nothing is wasted, though the second sentence is more about return shape than invocation.

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 return values, and it still volunteers the isBuiltIn/reference-image behavior. For a single-param read tool this is essentially complete; only usage routing to list_entities 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?

One parameter at 100% schema description coverage, so the schema already documents entityId and its vg_enti_ prefix format. The description's 'by id' adds no syntax or format detail 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 (fetch) and resource (one entity by id), and adds scope detail: reference images included, built-in catalog entities returned with isBuiltIn true. It implicitly separates itself from list_entities by saying 'one entity', but never names the sibling explicitly.

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

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

Usage is implied by 'fetch one entity by id' — the agent can infer this is the single-item lookup versus list_entities. There is no explicit when-to-use guidance, no prerequisites, and no exclusions (e.g., archived entities, permissions).

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

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

Annotations already declare readOnly/non-destructive/non-openWorld, so the safety profile is covered. The description adds genuinely useful behavior beyond that: URLs are 'freshly hydrated (non-expired)', and wait mode polls with a give-up condition implied by timeoutMs. It does not describe error behavior when a file id is unknown, keeping it short of a 5.

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

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

Two tight sentences, front-loaded with what is fetched and what it returns, then the wait/escalation guidance. No filler or redundant restatement of the title.

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

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

With an output schema present, the description need not explain return values, and it covers the key usage sequence (post-upload hydration + polling). Minor gap: no note on auth/permission requirements or not-found handling, but for a read tool with full schema and annotations this is close to 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 all four parameters are already documented in-schema, which sets the baseline at 3. The description reinforces wait's semantics ('poll until the file finishes processing') but adds nothing about timeoutMs or pollIntervalMs beyond what the schema states.

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 (file by id), and goes further by naming exactly what comes back: freshly hydrated signed URLs for thumbnail, preview, and download renditions. This clearly separates it from list_files and the upload/create sibling 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: 'Set wait: true to poll until the file finishes processing — use this right after PUTting bytes to a create_file_upload URL.' It names the sibling and the sequencing condition that determines when to use this tool and when to use wait mode.

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/non-destructive/non-open-world, so the bar is lower, and the description still adds meaningful context: it is equivalent to the guidance://getting-started resource and exists as a fallback for clients that cannot read resources directly. That explains why the tool exists and why invoking it has no side effects.

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, front-loaded sentences with no filler; the content list comes first and the resource-equivalence rationale second. The first sentence is a long enumeration but every item carries information, so it stays within acceptable length.

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

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

For a parameterless, read-only guidance tool with an output schema already defining the return shape, the description covers purpose, triggers, and the resource-fallback rationale. Nothing an agent needs in order to call it 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?

The tool takes zero parameters, so the schema imposes no semantic burden and the description correctly says nothing about inputs. Baseline of 4 applies since there is nothing for the description to compensate for.

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?

Enumerates concrete content (authentication, get_me verification, workflow example prompts, workflows vs media tools, ID conventions) with a clear verb+resource framing, so an agent knows exactly what payload it gets. It does not, however, differentiate itself from overlapping siblings like get_workflows_guidance and get_tools_vs_workflows_guidance, which cover adjacent topics.

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

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

Gives explicit trigger conditions: connecting, onboarding, 'what can VideoGen do', setting up the API or MCP. That is strong when-to-use coverage. What is missing is when-not-to-use and routing against the sibling guidance tools that cover a subset of this material.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the identity is derived from the API key rather than parameters, which is useful, but it says nothing about rate limits, error behavior, or caching. Baseline 3 with annotations carrying the load.

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 primary action and scoped with a usage note. No filler, 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?

With zero parameters and an output schema present, the description only needs to convey purpose and when to call it, which it does. Listing the returned fields is mildly redundant against the output schema but harmless; nothing an agent needs 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 the baseline is 4. The field names listed in the description (apiKeyId, email, teamId, etc.) are return values already covered by the output schema, not parameters, so they add no parameter semantics.

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

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

States a specific verb (Fetch) and resource (the account and team behind the API key), and names the returned identity fields. No sibling tool overlaps with this purpose, so an agent can identify 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 gives a use case: 'Use it as a connection test.' That is a clear context for invocation. It does not, however, describe when NOT to use it or any alternative, though no sibling competes for this function.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds that a shareable URL is returned, which is mild extra context, but nothing about permissions, caching, or error behavior beyond that.

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 efficient sentence that is front-loaded with the verb and resource. No filler or 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 present, the description need not explain return values, and annotations carry the safety profile, so the remaining need is minimal. It is adequate for a simple one-parameter read, though it does not mention what to do when a project 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?

One required parameter with 100% schema description coverage, so the schema already documents projectId. The description adds only that the target is a 'single project', which does not meaningfully extend the schema's semantics; baseline 3 applies.

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

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

The description states a specific verb and resource ('Fetch metadata and the shareable URL for a single project'), making scope clear. It implies differentiation from list_projects by saying 'single project' but never names the sibling explicitly.

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

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

There is no when-to-use guidance, no prerequisites (e.g., ID format or where to obtain projectId), and no routing to alternatives such as list_projects or export_project. Usage has to be inferred entirely from the name and description.

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

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

Annotations already declare readOnly, non-destructive, and non-open-world, so safety is settled. The description adds real behavioral value beyond that: this is a polling endpoint with three named terminal states, which tells the agent when to stop calling it.

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

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

Two short sentences, zero filler, with the core action front-loaded and the polling instruction immediately after. Nothing could be removed without losing 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 and annotations covering the safety profile, the description needs only to explain the polling loop and terminal conditions, which it does explicitly. Nothing required to call this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters (exportId, projectId) are already documented, including the exportId format and its origin. The description adds no additional parameter meaning; 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 ('Fetch the current status of a project export') and implicitly distinguishes itself from the sibling export_project by scoping to status retrieval rather than export creation. An agent can tell what it returns without opening the schema.

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

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

Gives concrete operational guidance: poll repeatedly until status reaches 'succeeded', 'failed', or 'cancelled'. It doesn't name export_project as the prerequisite alternative, though the schema's exportId description ('from export_project') covers the pairing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the result reflects 'current' status, hinting at an in-progress vs completed state, but says nothing about polling cadence, terminal states, or error cases. Modest added value on top of 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?

A single efficient sentence that front-loads the verb and resource with zero filler. 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 the description need not explain return values, and the single parameter is fully documented in the schema. For a simple read tool with full annotation coverage, this is nearly complete; only the polling/terminal-state behavior an agent would want is missing.

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

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

Only one parameter, and the schema documents it at 100% coverage including the vg_tool_... id format. The description adds no further detail about the identifier's origin or source. Baseline 3 is appropriate when the schema fully carries parameter meaning.

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

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

States a specific verb (Fetch) and resource (a single tool execution) plus what is returned (current status and results). The word 'single' implicitly separates it from the sibling list_tool_executions, though the full set of siblings is never named.

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

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

No explicit when-to-use guidance. The agent must infer that this is for polling or checking one execution, and nothing tells it when to prefer this over list_tool_executions or cancel_tool_execution. The polling context is only implied by 'current status'.

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 mark this as read-only, non-destructive, and closed-world. The description adds useful context by stating it is equivalent to the guidance://tools-vs-workflows resource and explaining why it exists as a tool, though it does not detail output format or other operational traits.

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 three tight sentences, front-loading the core purpose first, then usage guidance, then resource equivalence. Every sentence adds value with no 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?

Given no parameters and an existing output schema, the description covers purpose, usage, and resource equivalence adequately. The only notable gap is not explicitly distinguishing this guidance tool from the other guidance siblings.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description appropriately does not waste space explaining parameters that do not exist.

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 choosing between standalone generate_* tools and workflow tools. It distinguishes the two categories well, but does not differentiate itself from sibling guidance tools like get_workflows_guidance or get_getting_started_guidance.

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

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

It explicitly says 'Call when choosing between generate_* tools and workflow tools,' providing clear usage context. However, it offers no when-not-to-use guidance and does not route the agent away from other guidance tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that the response contains the run's 'current status and result', but says nothing about freshness, waiting/polling behavior, or error cases for a run that does not exist.

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 front-loaded sentence with zero filler; the verb, scope, and returned content all land in the first clause.

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 the description need not enumerate return fields, and a single-parameter read tool needs little more than this. It is adequately complete, though a note on which sibling to use when the run id is unknown would close the last 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?

The single parameter has 100% schema description coverage including the id format hint ('vg_work_...'), so the schema carries the parameter documentation. The description adds no further meaning about the id or its alternatives, which is the expected baseline when coverage is high.

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

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

The description states a specific verb and resource ('Fetch the current status and result of a single workflow run'), making the operation unambiguous. The word 'single' implicitly separates it from the sibling list_workflow_runs, but the split is left for the agent to infer rather than named outright.

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

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

Usage is implied by 'a single workflow run' (versus a list), which points the agent toward this tool when it already has an id. There is no explicit statement of when to prefer this over list_workflow_runs or any prerequisite/scoping 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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior context: it is equivalent to the guidance://workflows MCP resource and exists as a fallback for clients that cannot read resources directly, which explains duplication an agent might otherwise find confusing.

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: the routing content first, then the usage constraint, then the resource-equivalence footnote. No filler, and the most actionable material 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 an output schema present, the description need not explain the returned guidance content, and annotations cover the safety profile. It is complete enough to trigger correct use, though a hint about the scope of the guidance (which tools the flow covers) would close the last 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?

The tool takes zero parameters, so there is nothing to document beyond what the empty schema already shows. Baseline for a parameterless tool applies.

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

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

The description names a concrete resource (the canonical run → remix → export flow) and states its role as routing guidance across workflow tools, which separates it from generation siblings. It could be sharper about how it differs from get_getting_started_guidance or get_tools_vs_workflows_guidance, which are the closest alternatives.

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

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

Explicit when-to-use ('Call before starting a full video project') plus concrete selection rules between two named siblings (script_to_video for longer narrated videos, storyboard_to_video ≤3 scenes). An agent knows both the trigger and the downstream routing decisions.

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

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

Annotations already indicate this is not read-only, not destructive, and not open-world. The description adds that the output is a video, which is useful but does not cover asynchronous behavior, expected processing time, or any file/asset lifecycle implications.

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 result, with no filler. Every word 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 one-parameter effect tool with an output schema and explicit annotations, the description is largely sufficient to invoke correctly. It could be more complete by mentioning whether the generated video is synchronous or asynchronous and by routing users away from similar sibling tools.

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

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

Schema coverage is 100%, so the single parameter is already fully documented as 'Source image file id.' The description adds no extra meaning or constraints beyond what the schema provides, which is appropriate but not enriching.

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

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

The description names a specific verb and transformation: 'Add 3D parallax motion to a still image, producing a video.' It clearly distinguishes the tool from generic image or video generation siblings by specifying the input type and the effect applied.

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 its use case but gives no explicit when-to-use guidance, prerequisites, or alternatives. It does not tell the agent when this effect is preferable to sibling tools like generate_video_clip or generate_motion_graphic.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context beyond them: built-in rows carry isBuiltIn=true and cannot be updated or archived, telling the agent which results are immutable. It does not discuss pagination behavior, but the safety/immutability disclosure is real added value.

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

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

Three short sentences, front-loaded with what is listed, followed by the immutability caveat and the filter hint. Every sentence carries distinct information with no filler.

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

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

An output schema exists, so return values need not be explained, and the description covers the entity kinds, the built-in immutability constraint, and filtering. Pagination is left entirely to the schema, which is acceptable, leaving only a small 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 limit, cursor, and entityType are all documented in the schema. The description only restates the entityType filter condition, adding no format or syntax detail beyond the schema — the baseline 3 applies.

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

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

The description names the specific verb (list) and enumerates the resource kinds it returns: built-in actors, products, visual styles, slideshow themes, plus team entities. This clearly separates it from the single-item siblings (get_entity, create_entity), though 'team entities' is left slightly undefined.

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 conditional hint — 'Filter with entityType when you only need one kind' — which is genuine usage guidance. It does not state when to prefer get_entity over listing, nor any prerequisites, so guidance is implied rather than complete.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — results are scoped to the current API key's visibility/permissions — but says nothing about pagination behavior or result ordering.

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

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

A single front-loaded sentence with zero filler. Every word carries information (action, resource, scope).

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 complete parameter documentation, the only thing left for the description is scope, which it provides. Adequate, though a nod to pagination or sibling routing would round it out.

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 limit and cursor are already documented in the schema. The description adds no parameter meaning beyond that, 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+resource ("List files") and adds scope ("visible to the current API key"). It is clear on its own, but does not distinguish itself from the file-related siblings get_file, upload_file, or 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?

No when-to-use guidance and no mention of alternatives, even though get_file exists as a natural sibling for fetching a single file. The API-key scoping hints at breadth but is not framed as a selection criterion.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only that the result is the set of supported languages, which is thin context beyond the name; it says nothing about caching, stability, or auth.

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 resource and its scope front-loaded. Every word earns its place 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?

With an output schema present, return values need not be explained, and there are no required parameters. Combined with the annotations, everything needed to call the tool correctly is available; only the absence of sibling disambiguation keeps it from a 5.

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

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

Schema description coverage is 100% for the single optional 'query' parameter, which is documented as a case-insensitive substring filter. The description adds no additional meaning about the filter, so the schema-describes-everything baseline of 3 applies.

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

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

States a specific verb and resource ('List supported languages') and adds scope ('for narration and captions'), which tells the agent exactly what the enumeration covers. It does not, however, differentiate itself from the nearby sibling list_tts_voices, which an agent could plausibly confuse it with.

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

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

The phrase 'for narration and captions' implies the usage context, so an agent can infer this is a lookup for valid language codes. There is no explicit when-to-use statement, no mention of the alternative list_tts_voices, and no exclusion conditions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds only that the payload is per-project status information, with no note on ordering, scope of 'actions', or whether results can be empty.

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

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

A single front-loaded sentence with no filler, stating resource and scope immediately. Nothing is redundant or misplaced.

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 single parameter is schema-documented. Still missing is any indication of what constitutes a 'remix action' or how results are bounded, which matters for an agent deciding whether this call answers its question.

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

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

There is one required parameter (projectId) and schema description coverage is 100%, so the schema already documents it fully. The description merely implies the project scoping and adds no format or identifier guidance beyond that, 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?

Names a specific verb ('List'), resource ('remix actions'), and scope ('applied to a project'), plus the returned facet ('status'). It is distinguishable from the sibling remix_project, which creates rather than reports, though the description never states that contrast explicitly.

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

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

No when-to-use condition, no prerequisite, and no pointer to an alternative tool. An agent must infer from the name alone that this is the retrieval counterpart to remix_project.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral default (UI projects silently excluded unless opted in) that the annotations do 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?

Two short sentences, zero filler, with the default-scope constraint front-loaded before the opt-in escape hatch. 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 and pagination cursor need not be described. The description covers the one non-obvious behavior (default filtering). Minor omission: no note on result ordering or team-vs-owner scope, though selfOnly is in 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 all four parameters (limit, cursor, selfOnly, includeUiProjects) are already documented in the schema. The description only elaborates on includeUiProjects, adding nothing beyond the schema's own wording. 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?

States a specific verb and resource ('List projects') and immediately clarifies scope: API-created projects only by default. That scope note distinguishes it from a naive reading, though it does not explicitly contrast with siblings like get_project or list_project_remix_actions.

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 actionable conditional guidance: default returns API-created projects, and passing includeUiProjects widens to dashboard projects. It lacks an explicit 'use get_project for a single project' exclusion, but the condition that changes behavior is spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the ordering guarantee ('most recent first'), which is real behavioral context, but says nothing about pagination behavior, result size, or retention limits despite a cursor parameter existing.

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 short sentence, front-loaded with the verb and resource, with the ordering caveat appended where it matters. No padding, though it is arguably too terse to carry structure.

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

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

With a 100%-covered schema, an output schema, and annotations covering the safety profile, the omission of pagination and scope-filter explanation is acceptable. The description supplies only the ordering guarantee, which is the one behavior not expressed in the structured fields.

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 limit, cursor and selfOnly are already fully documented in the schema. The description adds no syntax, defaults, or interpretation for any of them, 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 ('List past tool executions') plus the ordering ('most recent first'), which is genuinely useful. It does not, however, distinguish itself from close siblings like get_tool_execution or cancel_tool_execution, so an agent gets no help disambiguating within this family.

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 word 'past' implies this is for historical/completed executions rather than in-flight ones, which is the only usage signal present. There is no statement of when to prefer this over get_tool_execution or list_workflow_runs, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The description itself adds no behavioral context such as filtering scope, deprecation handling, or pagination behavior, so it contributes almost nothing on this dimension.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though arguably so terse that it leaves room for a little more useful scope detail.

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

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

With an output schema present and annotations covering the safety profile, the description does not need to explain return values. It is minimally adequate for a simple list tool, but omits filtering/pagination cues that would round out the picture.

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 four well-documented parameters (limit, query, cursor, includeDeprecatedVoices), so the schema already carries parameter meaning. The description adds no additional parameter semantics, which is the expected baseline 3 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?

The description pairs a specific verb (List) with a specific resource (text-to-speech voices) and names the consuming features (narration, text_to_speech, workflows). It is distinct from siblings like list_languages or list_files, though it doesn't explicitly contrast itself with any of them.

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

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

Mentioning narration/text_to_speech/workflows implies when an agent would want voices, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative tool. Usage is only weakly implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds the ordering behavior ('most recent first'), which is useful context, but does not discuss pagination behavior, default limits, or scope restrictions beyond what the schema covers.

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

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

A single front-loaded sentence with zero waste. It conveys the core action and ordering immediately, which is appropriately concise for a simple list tool.

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

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

Given the output schema and annotation coverage, the description need not explain return values or safety guarantees. However, it omits any scoping or filtering context and does not help an agent distinguish this tool from get_workflow_run, leaving a clear gap for sibling selection.

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 parameters documented in the schema. The description adds no additional parameter semantics, so the baseline score of 3 applies.

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

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

States a specific verb ('List') and resource ('workflow runs') and adds a scope detail ('most recent first'). It does not explicitly distinguish itself from sibling tools like get_workflow_run or list_tool_executions, 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?

No when-to-use guidance, prerequisites, or alternative-tool routing are provided. The description only implies that this is for listing, without explaining when an agent should choose it over get_workflow_run or other list tools.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is already covered. The description adds that exactly one clip is produced and that it lands in an editable project, but says nothing about generation latency, cost, or the fact that the run can block until an MP4 is ready (a behavior that only appears in the autoExport parameter's schema text).

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity is partly the source of the definition's gaps rather than a virtue of tight writing.

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 mutation profile. But for a six-parameter, nested-object generation tool with an ambiguous sibling, the description omits the usage routing and the long-running/autoExport behavior that an agent needs before invoking it.

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

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

Schema description coverage is 83%, so most parameters are already documented in the schema and the baseline of 3 applies. The description adds nothing about duration, quality tiers, aspect ratio units, or the autoExport workflow, and does not compensate for the one undocumented parameter (durationSeconds).

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

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

The description names a specific verb and resource ('Generate one short AI video clip from a prompt') and adds a scope qualifier ('inside an editable project'), which is more than a restatement of the name. However, it does not distinguish itself from the near-identical sibling 'generate_video_clip', nor from the other prompt-to-video routes (script_to_video, storyboard_to_video), leaving an agent unable to tell them apart 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?

There is no when-to-use or when-not-to-use guidance, and no alternative is named despite several siblings that also produce video from input. The agent is left to infer that this is the one-shot, prompt-driven path versus the storyboard/script paths.

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 mark the tool as non-read-only and non-destructive, so the mutation risk is already structured. The description adds important operational context beyond annotations: CONVERT_IMAGES_TO_VIDEOS is expensive, and the operation is asynchronous enough to require polling with list_project_remix_actions.

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 are front-loaded with the core action, then a cost warning and the polling instruction. Every sentence earns its place, 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 and parameter descriptions are complete, so return values need not be explained. The description covers cost and polling status, but it leaves implicit how remix_project relates to other project-creation siblings.

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

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

Schema description coverage is 100%, and the schema already explains each edit enum value in detail, including the same expensive/cheap distinction. The description repeats some of that meaning but adds no syntax or format details beyond the structured schema.

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

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

The description states a specific verb and resource: "Apply curated edits to an existing project." It also names the polling sibling, list_project_remix_actions, but does not explicitly distinguish remix_project from other project-creation or editing siblings like storyboard_to_video or update_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?

It gives clear guidance on choosing between edit types: CONVERT_IMAGES_TO_VIDEOS is expensive, while ZOOM is cheap Ken Burns motion. It also says to poll with list_project_remix_actions for status, but it does not state when to use remix_project instead of alternative video-generation tools.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the mutation-not-read profile is covered structurally. The description adds a real behavioral constraint (built-in entity restriction) beyond the annotations. It does not state what happens if the file id is not attached, which is the 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?

Two short sentences, zero filler. The core action is front-loaded and the failure constraint follows immediately.

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

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

An output schema exists so return values need no explanation, and both params are fully documented. The entity-type restriction is the key extra context; only idempotency/nonexistent-reference behavior is left unspecified.

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% with both parameters documented (fileId vg_file_..., entityId vg_enti_...). The description's 'by file id' adds nothing beyond what the schema already states, 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 (Detach), resource (reference image), and mechanism (by file id) in one sentence. It is clearly distinguished from the sibling add_entity_reference and the other entity 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?

Gives an explicit when-not condition ('Built-in entities cannot have references removed'), which tells the agent when the call will fail. However, it names no alternative tool or fallback for the built-in case, so the routing guidance is incomplete.

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 readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the agent knows this is a non-destructive local mutation. The description adds nothing beyond that: it doesn't say whether a new file is produced, whether the original is preserved, or what the returned artifact is.

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, front-loaded sentence with no filler or redundancy. It is appropriately sized for a one-parameter tool, though it is thin enough that it borders on under-specification rather than tightness.

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. Still, for an image transformation tool the description omits the workflow context (uploaded file required, result is a new asset), leaving the agent with only the bare operation.

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 exists and schema coverage is 100%, so the schema fully documents imageFileId as the source image file id. The description adds no format, source, or constraint detail beyond that, 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 (remove) and resource (image background), so the operation is unambiguous. It does not, however, explicitly distinguish itself from the near-identical sibling remove_video_background; the agent must infer the split from the names 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?

There is no guidance on when to use this tool versus alternatives such as remove_video_background or vectorize_image, nor any stated precondition (e.g., that the image must first be uploaded and have a file id). Usage is left entirely 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 this is not read-only and not destructive, but the description adds nothing behavioral beyond that: no indication of processing time, whether it creates a new file or overwrites, or whether the operation is async. It essentially restates the title.

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 zero filler and the action front-loaded. It is concise, though that conciseness comes at the cost of substance rather than from efficient compression of useful 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?

An output schema exists so return values need not be described, but for a non-read-only media-processing tool the description omits key context such as processing duration, output artifact handling, and any input constraints. Too thin given the tool's complexity.

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

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

With one parameter and 100% schema description coverage, the schema fully documents videoFileId ('Source video file id.'). The description adds no syntax, format, or sourcing 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 ('Remove') and resource ('background from a video'), so the action is unambiguous. It implicitly differentiates from the sibling remove_image_background by media type, though it never names or contrasts that sibling explicitly.

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

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

There is no guidance on when to reach for this tool versus alternatives like remove_image_background, nor any prerequisites (e.g., video format, size limits, whether a file must be uploaded first). Usage is only inferable from the name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds that the output is editable and includes AI visuals and captions, plus the avatar narration path. However, it never discloses that generation is long-running/async (implied only in the autoExport schema text), nor any cost or duration limits, which is the most important missing behavioral fact.

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 selection guidance before the capability statement and the avatar tip. No filler, and the highest-value routing information (preferred use case and the sibling exclusion) comes 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?

With an output schema present and 100% schema description coverage, the description need not explain return values or parameters. It covers purpose, the alternative tool, and the avatar variant, which is everything an agent needs to choose and 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?

Schema description coverage is 100% and the style field's semantics are exhaustively documented in the schema, so the schema does the heavy lifting. The description only adds a light steer ('pass actorEntityId and optionally set avatarQuality'), which largely restates what the schema already says.

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') with explicit scope ('narrated / informational / explainer videos', '~1 minute or longer'). An agent can distinguish this from storyboard_to_video 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?

Opens with a clear preference statement, then names the sibling alternative and the exact condition that selects it ('Prefer this over storyboard_to_video unless the user wants a short shot-directed storyboard'). It also routes the avatar case to specific parameters, leaving nothing to inference.

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

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

Annotations declare the write/mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so safety is covered. The description adds the useful prerequisite ordering and notes the output is 'editable,' but says nothing about async behavior, runtime, or cost beyond what autoExport in the schema already conveys.

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: purpose first, then the actionable prerequisite and the optional avatar path. No filler or restated field lists.

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 rich 9-parameter schema, an output schema, and annotations, the description only needs to orient the agent — which it does by naming the required upload step. It stops short of routing among the numerous video-generation siblings, but otherwise nothing essential to invocation is missing.

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

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

Schema description coverage is 100%, so every parameter including actorEntityId, avatarQuality, aspectRatio, and autoExport is already documented at the source. The description only restates the fileId prerequisite and the actorEntityId/avatarQuality pairing, adding little 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 ('Build') and resource ('editable narrated video') with the required source ('uploaded PDF or slideshow file'). This clearly separates it from siblings like script_to_video, voiceover_to_video, and storyboard_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 concrete prerequisite sequence ('Upload the file first with upload_file, then pass its fileId') and a conditional path for avatar narration. It does not, however, contrast this tool against the many other video-generation siblings, so the agent must infer when a slideshow source is the right choice.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so safety is covered. The description adds genuinely non-structured context: it is 'much more credit-heavy' than script_to_video, there is an implicit scene cap, and the output is editable. It does not disclose runtime/async behavior or failure modes, so it is not 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?

Five sentences, each load-bearing: purpose, scene requirement, cost/scene-cap warning, alternative routing, and ambiguity handling. It is front-loaded with the routing-critical cost warning before the fallback advice.

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

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

For a 5-parameter, nested, enum-bearing tool with an output schema available, the description covers the decision-critical information an agent needs (what it builds, cost profile, scene limit, alternative tool). Return values need not be explained because an output schema exists.

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

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