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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered; the description adds real context beyond them by noting the anonymous/free-overlay tier needs no sign-in and that sign-in instructions are returned when needed. It stops short of describing the full response shape, but the tier nuance is genuinely additive.

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

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

Three short sentences with the core capability front-loaded and zero filler. Each sentence carries distinct information: what is checked, an exemption case, and the fallback output.

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 status tool with no output schema, the description covers the essential outcome (signed-in / Pro status plus sign-in instructions). It could be slightly more explicit about what a negative result looks like, but nothing critical to invoking it is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly consumes no space on nonexistent inputs.

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

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

The description states a specific verb+resource: checking sign-in state and Pro-access validity for Modisign. It is clearly distinguishable from siblings like login or get_overlay, though it does not name any sibling explicitly to sharpen the boundary.

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

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

It gives useful context that anonymous free overlays work without signing in, which implicitly tells the agent when this check is unnecessary. However, it never states when to call it (e.g. before an authenticated operation) nor routes the agent to the login sibling when sign-in is missing.

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

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

Annotations only cover the safety profile (not read-only, open-world, not destructive). The description adds real behavioral context beyond them: async execution via job_id with job_status polling, output codec/container and resolution cap, the automatic aspect reauthorization, and the privacy guarantee that local media never uploads.

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?

Information is front-loaded: purpose, then constraints, then return contract, then the sibling routing rule last. Dense and mostly waste-free, though the aspect/output-format sentences are tightly packed and slightly harder to parse than they need to be.

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

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

With no output schema, the description correctly carries the return contract (job_id + job_status polling) and the output characteristics. The one gap is output_path semantics, which is neither in the schema description nor the tool description.

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

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

Schema description coverage is only 25% (only configuration is documented). The description adds meaning for start_seconds ('must fit the overlay within the video') and clarifies the aspect return, but video_path and output_path receive no explanation despite being required/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 gives a specific verb+resource ('Render an overlay ... composite it onto one local video') plus scope constraints (up to 60 seconds, positioned at start_seconds). It is clearly distinguishable from siblings like render_overlay and edit_video without opening any schema.

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

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

It explicitly routes the agent: 'Use edit_video for longer or multi-clip edits', and states the precondition that the start must fit the overlay within the video. The when-to-use and when-to-use-something-else conditions are both present.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, setting a lower bar. The description adds genuine side-effect context not in the annotations: temporary files get cleaned and a completed artifact is retained. It still omits what happens to the job's recorded state, whether the call is idempotent, and error behavior for an unknown or already-finished job.

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

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

Two short sentences, action first, then the retention nuance. Every clause carries meaning and nothing is repeated from the schema or annotations.

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

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

For a one-parameter tool with no output schema, the description covers the action, the eligible job states, and the cleanup/retention outcome, which is close to sufficient. It could still say what the tool returns or how it behaves on a missing/already-completed job.

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

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

Schema description coverage is 0% for the single required job_id, so the description carries the full burden of documenting it and says nothing: no format, no source (e.g., where job_id comes from), no example. The name is largely self-explanatory, which keeps this from a 1, but the low coverage is uncompensated.

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 (queued or running local video job) and even scopes which job states are eligible. It stops short of naming or contrasting a sibling like job_status, so an agent gets the action but no explicit sibling differentiation.

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

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

The phrase 'queued or running' implies when the tool applies and the retention clause hints at the edge case of completed jobs, but there is no explicit when-to-use/when-not statement, no mention of the alternative job_status for inspecting a job first, and no prerequisites.

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

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

The annotations already declare this is a non-read-only, open-world, non-destructive operation, and the description adds real value on top: it discloses the return payload (configuration URL plus free/Pro tier), the error-recovery behavior (field errors list allowed inputs so you can correct and retry), and a tier limitation on free presets. It does not mention whether reconfiguring is idempotent or overwrites prior config.

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 front-loaded sentences, each carrying distinct information (capability, return value, error behavior, tier caveat), with no filler. Slightly dense in the first sentence where the field list is packed in.

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

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

For a 7-parameter mutation tool with a nested 'values' object, no output schema, and zero schema description coverage, the description covers outcome, tier gating and error recovery well but leaves parameter semantics and any sibling routing unexplained. Adequate but with clear gaps on the input side.

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

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

Schema description coverage is 0% across 7 parameters, so the description carries the full burden — but it only echoes five field names ('values, look, aspect, duration or background') without format, ranges, or enum details, and never mentions the two REQUIRED parameters, family and preset. An agent still cannot tell what a valid family/preset value is.

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 ('Configure') and resource ('animated overlay') plus the editable dimensions, so an agent knows it produces a configuration rather than a rendered file. It is distinguishable from render_overlay and get_overlay, though it never names those siblings explicitly.

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

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

Usage is implied by the mention of tier gating ('free preset text generally need Pro to render') and the retry-on-field-error note, which hints at an iterative configure-then-render workflow. However there is no explicit when-to-use versus render_overlay or get_overlay, and no stated prerequisites for family/preset.

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

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

Annotations only declare non-read-only, non-destructive, open-world. The description adds substantial behavior beyond that: 300-clip/180-second caps, transition clamping to adjacent limits, v1-only caption/pause detection even when muted, ripple behavior when removing pauses, an explicit error on conflicting v1 transitions, and no automatic sync/drift correction. It also discloses the free/Pro gating, no-upload and no-history behavior, and default 1080p/720p handling.

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?

Nearly every sentence carries unique constraints, but they are packed into a single unbroken wall of text mixing purpose, limits, quota, captions and an embedded example. Front-loading is decent (core create behavior first) but the density hurts scanability and the login/Pro caveat arrives late.

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 very complex 8-parameter nested tool with no output schema, it covers limits, track semantics, transition behavior, captions, quota and the async job_id/polling contract, which is what an agent needs to invoke it correctly. Minor gaps remain on output_path/aspect/quality defaults but the return-value contract (job_id, poll job_status) is stated.

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 schema description coverage reported at 0%, the description carries the load and does so for the highest-risk fields: track/start rules per version, crop as source-edge percentages, place modes including custom normalized box, omitted defaults, pan/zoom ranges, and the tricky 'after_clip indexes the request array and must target v1' semantics. Several scalars (volume, fades, slow_zoom, mute, quality, output_path, remove_silences sensitivity) are left to the schema, so it is strong but not exhaustive.

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

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

The description opens with a concrete verb+resource+scope: 'Create a local video with sequential v1 clips and nonoverlapping v2 clips above them.' That clearly distinguishes compositing work from the sibling overlay tools (configure_overlay, render_overlay, add_overlay_to_video), though it never names them. It is dense but specific.

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 partial routing and conditions: returns job_id so 'poll job_status', overlays must come from configure_overlay, and free-vs-Pro limits are stated. However, it never explicitly tells the agent when to choose edit_video versus add_overlay_to_video or render_overlay, so the alternative-selection guidance is only implied.

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

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

Annotations already establish readOnly, non-destructive, open-world behavior, so the bar is low; the description earns credit by enumerating what the inspection returns (editable fields, types, allowed values, limits, looks, aspects, duration, free status). No auth, rate-limit, or error behavior is disclosed, which keeps it out of 5 territory.

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

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

A single front-loaded sentence with no filler; the inspection target precedes the 'before configuring' rationale. It is dense but every clause maps to actual returned content, so little is wasted.

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

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

With no output schema, the field enumeration usefully covers what an agent receives back. However, for a tool with two required, undocumented parameters, the description omits how to discover valid family/preset values, which is the main missing piece.

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 two required params (family, preset) carry only regex patterns with no meaning attached. The description hints that 'preset' is an overlay preset but never explains what 'family' is or the expected identifier format, so it does not compensate for the coverage gap.

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

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

Specific verb 'Inspect' paired with a precise resource: an overlay preset's editable fields, types, allowed values, limits, looks, aspects, duration and free status. This clearly separates it from write siblings like configure_overlay and render_overlay, though it never names those siblings explicitly.

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

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

'before configuring it' gives a clear sequencing cue pointing at configure_overlay, so the when-to-use is implied rather than stated. It does not say how to obtain valid family/preset identifiers (list_overlays) or when this is unnecessary, leaving an actionable gap.

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 (readOnly, non-destructive), while the description adds substantial context the annotations cannot convey: media and transcript are never sent to Modisign, the transcript is surfaced to the assistant/provider, the first call downloads the speech model and later calls work offline, and returned line times are in source seconds. This is exactly the extra behavioral load the description should carry.

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

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

Every sentence earns its place: purpose and limit first, then parameter semantics, then privacy/output routing, then the when-to-call constraint, then the model-download behavior, then the sibling alternative. No filler or repetition.

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

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

There is no output schema, and the description covers the return contract (transcript text delivered to the assistant, line times in source seconds) plus runtime behavior (model download, offline operation, 180s cap). Nothing an agent needs to invoke this correctly appears to be missing.

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

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

Schema coverage is 0%, so the description must compensate, and it explains the two non-obvious parameters: 'in/out' are optional trim seconds, and returned line times remain referenceable to source seconds. 'path' is left unaddressed but its meaning is self-evident from the name; a note on path format/resolution would be needed for a 5.

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 ('Transcribe English speech in one local video'), including the hard 180-second scope and the local/English-only constraint. It also differentiates itself from the sibling edit_video by routing corrections to 'captions.corrections', so an agent can distinguish it without opening any schema.

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

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

Gives a clear usage condition ('call only when the user wants to review or correct it') and names the alternative path for fixing names/phrases (edit_video captions.corrections). It stops short of stating when transcription is unnecessary (e.g. video already has captions), so it is strong but not a complete decision rule.

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=true, so the safety profile is covered. Beyond that, the description adds genuinely useful non-obvious behavior: the progress scale (0–1), what a completed job returns, and the crucial lifetime constraint that jobs last only for this server process.

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

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

Two tight sentences, front-loaded with the core action and followed by return-value and lifetime detail. No filler.

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

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

With no output schema and no annotation-level return detail, the description usefully enumerates the fields of a done job (artifact path, MIME, bytes, duration, warning) and the retention window. It stops short of naming the possible state values or the behavior for invalid ids.

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 single job_id parameter has only a minLength constraint. The description never explains what a job_id is, where it comes from, or what happens for an unknown/expired id, so it fails to compensate for the schema gap.

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

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

The description states a specific verb and resource ('Check a local video job's state and progress') and scopes it to local, server-process-lifetime jobs, which separates it from network/account siblings. It doesn't explicitly name a sibling like cancel_job, but the purpose is unmistakable.

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: poll this after submitting a video job. There is no explicit statement of when to use it versus cancel_job or how to obtain a job_id, and no guidance on polling frequency or terminal states.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds real behavioral context beyond them: the return shape ('compact preset choices and editor links') and the cursor-based pagination contract. It does not say whether results are exhaustive or bounded by default.

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, no filler: identification first, then return content, then the pagination instruction. Each sentence carries distinct 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?

With no output schema, the description correctly compensates by describing what comes back and how to page. Five parameters with zero coverage means a gap remains around free_only and the semantics of query, but for a read-only listing tool this is largely sufficient.

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 parameter meaning. It maps reasonably onto query/family/niche ('by topic, family or niche') and explains cursor usage well, but leaves free_only entirely undocumented and never clarifies filter combination or defaults.

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

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

The description names a specific resource (animated overlays) and the discovery dimensions (topic, family, niche), and it distinguishes itself from the singular sibling get_overlay by framing itself as returning 'compact preset choices and editor links'. It never explicitly contrasts with get_overlay, so it stops short of a 5.

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

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

There is concrete guidance on pagination ('Reuse the same filters and pass the returned next_cursor as cursor'), which is genuinely useful. However, there is no statement of when to prefer this over get_overlay, or any exclusion such as when not to use it, leaving the discovery-vs-fetch choice 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?

Adds substantial behavior beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false): the flow is asynchronous with background polling, requires explicit human approval, never opens a browser, and never returns credentials. That last point pre-empts the main agent misconception for a sign-in tool.

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

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

Four short sentences, each doing work: what it starts, what to do with the output, how completion is signalled, and what it will not do. The primary action is front-loaded 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 no input parameters, no output schema, and annotations already covering the safety profile, the description supplies everything an agent needs: the initiation semantics, the human-in-the-loop requirement, the async polling model, and the handoff to account_status.

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 for the description to disambiguate; the baseline for a parameterless schema applies. No misleading parameter detail is present.

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

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

States a concrete verb and resource: "Start Modisign device sign-in." It also names the completion-check path (account_status), so an agent can tell what this tool initiates versus what merely reports status on it.

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 operational context: show the verification URL/code to the user, the user approves via Google, polling continues in the background, and account_status is the place to check completion. It supplies no explicit when-not-to-use or prerequisite conditions, so it falls short of 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 declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds meaningful context beyond that: async job semantics (returns job_id), a hard dependency on the user's FFmpeg, and auth/tier gating. It doesn't cover failure modes or output location behavior.

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

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

Front-loaded with the purpose and return value, then format behavior, then prerequisites, then the follow-up action. Dense and every clause is actionable; 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?

No output schema exists, and the description correctly summarizes the return (job_id) and the polling pattern. Combined with format semantics and auth prerequisites, an agent has enough to invoke it, though async completion details and output_dir defaulting are 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?

Schema coverage is only 33% and output_dir has no schema description, so the description carries weight. It explains the format enum well (MP4=green screen, MOV=transparent ProRes 4444, WebM=transparent VP9), which the bare enum cannot convey; output_dir remains unexplained but is largely self-evident.

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

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

Specific verb+resource: 'Start a local animated overlay render and return job_id'. It also distinguishes itself from configure_overlay by noting the configuration comes from configure_overlay, and from job_status by naming it as the polling follow-up.

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 real preconditions (needs the user's FFmpeg, free configurations need no login, others need Pro) and the correct next step ('Poll job_status for the file'). It stops short of explicitly stating when to use this versus add_overlay_to_video or edit_video.

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