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

Adds real context beyond the annotations: it writes into a specific directory, refuses to overwrite, and reports a local path plus SHA256 for integrity checking. That 'never overwrite' guarantee is exactly the behavior an agent needs, though it doesn't say whether a collision raises an error or picks a new name.

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 clauses, each earning its place: action plus destination, the overwrite guarantee, and the return value. Front-loaded with no filler.

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

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

Output schema exists so return values needn't be spelled out, but two gaps remain for a tool that writes to disk: behavior when the target file already exists, and behavior when the job isn't complete yet. The filename parameter's role is left entirely 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?

Schema description coverage is 0%, so the description must carry both parameters, and it explains neither. job_id is only indirectly constrained by 'completed job', and the filename parameter (default video.mp4) — the one that interacts with the 'never overwrite' rule — is never mentioned.

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 ('Download an existing completed job') plus the destination ('HEYGEN_DATA_DIR/outputs'), and the closing 'No new generation' rules out the generation siblings like heygen_submit. It never names heygen_status or heygen_receipt, so differentiation is by negation rather than explicit routing.

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?

'existing completed job' implies a precondition (the job must already be finished) but never tells the agent to verify via heygen_status first, nor what to do if the job is still running. No alternatives are named; usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true; the description reinforces this with a no-charge, no-generation guarantee and a modality restriction ('text-to-video only'), which is real added context. It doesn't say whether the estimate is deterministic or how the 'conservative' bound is derived, which keeps it below 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 short, front-loaded sentences with no filler; the safety guarantee follows immediately after the purpose. Slight loss for the jargon-heavy 'conservative USD SKU estimate' phrasing that needs unpacking.

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

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

An output schema exists, so return values needn't be explained, and annotations cover the safety profile. But with five nested parameters at 0% schema coverage, the description should say at least which fields affect the estimate and what 'capabilities' returns.

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

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

Schema description coverage is 0% and the nested VideoRequest exposes prompt, duration, resolution, aspect_ratio, and seed with no explanation anywhere. The description never mentions that duration/resolution drive the SKU estimate, so an agent gets no help mapping inputs to price.

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 action (fetch capabilities and a USD SKU estimate) and scopes it to text-to-video, which separates it from heygen_submit's generation role via 'No generation or charge.' 'Capabilities' remains vague, but the verb+resource pairing is clear enough to select the tool.

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

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

The 'No generation or charge' clause implies this is the pre-flight/dry-run option before heygen_submit, but the description never says 'use this before submitting' or names the sibling explicitly. Usage is inferable rather than stated.

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

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

The description adds meaningful behavioral context beyond the readOnly annotation: it confirms no generation occurs and notes that an UNKNOWN result requires dashboard reconciliation. It does not explain what UNKNOWN refers to or what the receipt includes, but the annotations already cover the safety profile.

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

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

The description is two short sentences with no wasted words, and the core action is front-loaded. The UNKNOWN reconciliation note is compact even if slightly cryptic.

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

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

Output schema and read-only annotations mean return values and safety need not be re-explained, but the missing definition of 'request_key' and the cryptic UNKNOWN note leave gaps for a tool whose only parameter is undocumented. The description is minimal but not quite complete for reliable invocation.

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

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

Schema description coverage for the sole parameter is 0%, and the description never explains what 'request_key' represents, where to obtain it, or how it relates to the saved request. The phrase 'saved request' is suggestive but does not compensate for the missing schema documentation.

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

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

The description uses a specific verb ('Read') and resource ('saved request and job ID') and clarifies it does not regenerate content. It is clear enough to distinguish from heygen_submit, but it does not explicitly differentiate from heygen_status or heygen_download.

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 'without generating again' and the UNKNOWN reconciliation note, but the description does not explicitly say when to use this versus heygen_status, heygen_submit, or heygen_download. The agent must infer the context from the sibling names.

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 and openWorldHint, so the safety profile is covered; the description adds genuinely new behavior — single-shot polling semantics, a recommended interval, and explicit handling of terminal failures. It stops short of describing job states or whether repeated polling has limits.

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

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

Three short sentences, front-loaded with the action, then cadence, then the failure rule. Every sentence carries information, though the terseness borders on under-specification.

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, but the description omits where job_id comes from and how this step fits the submit → status → download flow. For a polling tool in a multi-step pipeline that is a meaningful gap.

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

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

The single required parameter job_id has 0% schema description coverage — only a regex pattern — and the description never mentions it, its provenance (from heygen_submit), or its format. With one undocumented parameter the description is expected to compensate and does not.

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

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

"Poll once" implies a status check, but the description never names the resource being polled (a HeyGen generation job) or what a poll returns. Combined with the name heygen_status the intent is inferable, but it is not a stated verb+resource, and it draws no boundary against heygen_receipt or heygen_download.

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

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

It gives concrete operational guidance — poll once, ~30s between polls — and a guardrail against auto-regeneration on terminal failure. What is missing is routing: nothing says when to call this instead of heygen_receipt, or what to do after a successful/non-terminal poll.

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

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

The description adds substantial behavioral context beyond the annotations: the call is PAID, requires explicit user approval, must record consent and a cost ceiling, must never invent either, and uses request_key for idempotent receipt recovery. These details align with idempotentHint=true and openWorldHint=true and tell the agent exactly how to behave around a costly, state-changing submission.

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 PAID and the one-time approval requirement. Every sentence carries distinct operational value: approval, cost limit, and request_key reconciliation.

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 description is complete for the critical behavioral aspects of a paid, idempotent submission, and output details are covered by the output schema. The main remaining gap is that it does not point the agent to heygen_estimate for determining max_cost_usd, nor does it explain the request payload 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?

With 0% schema description coverage, the description does important semantic work for approval, max_cost_usd, and request_key, clarifying consent, spending limit, and idempotency. However, it says nothing about the request object or its fields such as prompt, duration, resolution, and aspect_ratio, leaving the main payload undocumented.

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

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

The description clearly states a specific action—submitting a paid request—but does not explicitly name the resource as video generation; that is inferred from the schema and sibling names. It distinguishes itself from retrieval siblings by emphasizing one-time paid submission and request_key receipt recovery.

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 strong usage constraints: submit once, only after explicit user approval, with recorded consent and a USD limit. It also mentions reusing request_key for receipt recovery and manual reconciliation for uncertain submissions, though it does not explicitly route the agent to heygen_estimate before setting max_cost_usd.

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