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

Adds substantial context beyond the annotations: an external Sonilo API call may incur charges, variants_num is billed per brief, there is a 10-second billing floor and an 8-minute duration cap, and the upload cap applies. Annotations already mark openWorldHint=true and idempotentHint=false, and the description is consistent with those while supplying the cost and limit details the annotations cannot express.

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

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

Well front-loaded — the mode semantics and usage trigger come before the parameter list, and the cost warning is visually flagged. It is somewhat long and repeats the 'no file is written' point in both the opening and the Returns section, which costs a little efficiency but not comprehension.

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?

Covers the full call lifecycle for a 5-parameter, paid, open-world tool: input constraints, mutually exclusive parameters, duration and billing limits, the returned JSON field names per mode, and the timeout recovery path via get_sfx_task with the task_id. Even though an output schema exists, the description usefully flags that sfx_prompt is a single string rather than one per variation — a non-obvious asymmetry.

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 mode is an unconstrained anyOf string with no enum, so the description carries the full burden — and it does: it enumerates the mode values and their exact return fields, gives the 1-5 range and per-brief billing for variants_num, the 2000-character limit for prompt, the absolute/relative path resolution via SONILO_MCP_BASE_PATH for video_path, the HTTP(S) requirement for video_url, and the 'exactly one of' invariant.

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 (analyze a video, return a creative brief) and immediately clarifies the negative scope: it generates no audio, video, or file. That negative framing is exactly what separates it from the video_to_* generation siblings, and the mode values make the three output shapes explicit.

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

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

Names the trigger condition ('when the user does not know what music or sound effects the video should get') and the downstream action (feed a variation's prompt into video_to_music, video_to_sfx, video_to_sound, or the video-to-video counterparts). It also states the gating rule — only use when explicitly requested by the user — because of the cost warning.

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

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

Beyond annotations, it discloses cost implications, API call behavior, input duration and size caps, video handling and muxing, and timeout recovery via task_id. These are important behavioral traits for a non-read-only, open-world 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?

The description is front-loaded with purpose and a cost warning, then organized into Args, constraints, and Returns. The length is justified by the tool's complexity, and there is no redundant 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 media-processing tool with five parameters, the description covers inputs, formats, constraints, limits, return values, and failure recovery. Even though an output schema exists, the extra return and timeout details are helpful and 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 0%, but the description explains every parameter: voice_path/voice_url, music_path/music_url, output_directory, their allowed formats, path resolution, and the exactly-one-of constraints. It fully compensates for the schema's lack of descriptions.

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

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

The description states a specific verb and resource: ducking a music bed under a voice track, including how Sonilo lowers and lifts the music. It clearly distinguishes this from sibling tools like text_to_music or video_to_sfx by focusing on the ducking mix operation.

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 a clear usage condition: only use when explicitly requested by the user due to API cost. It does not name explicit alternatives or when-not scenarios, but the cost constraint and input rules provide strong guidance.

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

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

Annotations only declare the generic profile (not read-only, open-world, non-idempotent); the description goes far beyond with billing semantics, the two-hour backend ceiling, and the crucial "an hour-long wait is normal, not a hang — do not cancel" guidance plus the fact that the job keeps charging server-side even if abandoned. It stops just short of stating idempotency/retry behavior explicitly, so it isn't flawless, but the destructive-in-wallet sense is unusually well disclosed.

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

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

Front-loaded with purpose, then the cost warning before anything else — correct priority given real billing risk. The Args and Returns blocks are dense but largely non-redundant; the Returns section is somewhat long given an output schema exists, and a few clauses (background bed rebuilt, ducking unaffected) repeat context. Justified in size overall, not padded.

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

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

For an 8-parameter, zero-schema-coverage, expensive, long-polling call, essentially every decision an agent must make is covered: input format limits (300s duration, 300MB, https-only), default languages, billing, expected wait, cancellation policy, and timeout recovery via get_sfx_task. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the entire burden and does: language codes are enumerated with regional disambiguation (pt vs pt_br, es vs es_419, ar caveat), subtitles are clarified as TARGET-language scripts rather than source transcripts with a key-matching constraint, lipsync's false branch is spelled out in consequence terms, and the exactly-one-of constraint on video_path/video_url is stated. This is meaning the schema cannot provide.

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 ("Dub a video into one or more other languages") and immediately disambiguates the output form: "the result is a new .mp4 per target language, not an audio track" — which separates it from audio_ducking and the video_to_sound siblings. An agent can identify the tool 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?

Explicit gating: "Only use when explicitly requested by the user," plus a concrete free-preview path (one language, no subtitles, 15-second trim) and a stated cost multiplier per language. It also gives a positive condition for the non-default branch ("Use it for footage with no on-camera speaker"). This is the when/when-not/alternative pattern at full strength.

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 (readOnly, idempotent, non-destructive), yet the description adds substantial behavior: the exact failure mode (402 trial_exhausted, no retry fixes it), the meaning of a missing trial key vs. a missing per-service entry, and the dubbing allowance being a 15-second preview rather than a full run. This is context no structured field carries.

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 shape, then errors and edge cases in descending priority, so an agent can stop reading early. Some sentences are long and the dubbing preview detail is narrow, but each carries actionable information rather than restating the 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?

There is no output schema, and the description fully documents the returned dict fields (available_services, rpm_limit, concurrency_limit, discount_factor, max_upload_size_mb, optional trial). It also covers the failure path an agent must handle, so nothing needed for correct invocation or interpretation 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 schema has nothing to document. The description instead spends its space on return-value semantics, which is a reasonable use given no input parameters 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?

States a specific verb and resource ('Get the authenticated account's available Sonilo services') and enumerates exactly what is returned (rate limits, concurrency limit, discount factor, upload size, trial allowance). An agent can distinguish this from generation siblings (text_to_music, dubbing, etc.) immediately.

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

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

Explicitly says to use it 'to discover what generation endpoints are available before calling them' and gives a concrete precondition for paid calls ('Check trial[service]['remaining'] before calling a paid generation tool'). It does not explicitly differentiate from the sibling get_usage, leaving a small ambiguity about which account-introspection tool to pick.

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

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

Beyond the annotations it discloses non-obvious behavior: no polling, no charge for the check itself, per-status outcomes (processing/succeeded/failed), whether a failed task was refunded, and that variant files are saved with -0/-1 suffixes. These are exactly the operational facts an agent needs and none are recoverable from the annotation flags.

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

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

Purpose and usage are front-loaded, and the Args/Returns layout makes it scannable. The Returns block is long and enumerates per-task file types that an output schema already covers, so it is somewhat over-specified even though each item is task-specific rather than 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 tool with 2 params, ten upstream producers, and a filesystem side effect, the description covers the trigger, the invocation semantics, the possible statuses, and the refund behavior on failure. Nothing needed to call 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?

Schema description coverage is 0%, so the description carries the full burden and does: task_id is defined as 'the task id returned in the timeout message' and output_directory as the destination defaulting to SONILO_MCP_BASE_PATH. That is meaning the bare string types in the schema do not convey.

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

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

The description opens with a specific verb ('Check') plus the exact resource set (six-plus named generation task types) and immediately follows with the retrieval role ('download its result file(s)'). It is unambiguously distinct from every sibling, which all create tasks rather than check 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?

It names the exact condition for use — recovering a result after one of the ten listed generation tools timed out — and tells the agent where to find the task_id (in the timeout error message). It also rules out an incorrect usage pattern with 'Does not poll: a single status check per call.'

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral facts beyond that: results are scoped to the authenticated account and the payload contains both a summary and a per-day breakdown. It does not mention pagination, rate limits, or how empty usage periods are represented, 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 front-loaded sentences state purpose and use case, followed by a compact Args block that adds range information not present in the schema. Every element earns its place; nothing is restated from structured fields.

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-required-parameter read-only tool, the description covers purpose, use case, account scoping, return shape (summary plus per-day breakdown), and the full semantics of the one argument. Without an output schema, more detail on the exact fields of the breakdown would help, but an agent has everything needed to call it correctly.

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

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

Schema description coverage is 0% and the schema gives only a bare integer with a default, so the description carries the full burden — and it does: the single parameter is optional, typed int, bounded 1–365, defaults to 30, and its meaning (lookback window) is spelled out. No ambiguity remains for the caller.

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: fetching the authenticated account's usage summary with a per-day breakdown. This is unmistakable against all siblings, which are generation/processing tools, though no sibling is named explicitly. The scope ('authenticated account's') is a valuable qualifier that avoids ambiguity about whose usage is returned.

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 contexts where the tool applies: cost reconciliation and tracking generation history. That is enough for an agent to recognize the trigger, but no exclusions or alternatives are stated, and there is no guidance on what to do if the lookback window needs to exceed 365 days.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the description only needs to add beyond that — and it does: the output device used, the exact set of accepted container formats, and how relative paths resolve. It stops short of saying whether playback blocks until completion or returns immediately, which matters for sequencing.

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

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

Front-loaded with the core action, then compact Args/Returns sections. The Returns block is minor redundancy since an output schema exists, but it costs only one line.

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

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

For a single-parameter tool with annotations and an output schema, the essentials are covered: accepted formats, path resolution, and target device. The one meaningful hole is synchronous-vs-asynchronous playback behavior, which an agent needs to know before chaining a follow-up call.

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 carries the load and delivers: input_file_path is an absolute path or relative to SONILO_MCP_BASE_PATH, a resolution rule absent from the schema. It doesn't mention extension requirements or what happens when the path is a directory or missing.

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: play a local audio file through the system's default output device, plus an enumerated list of supported formats. That resource (playback of an existing file) is unmistakably distinct from every sibling, which are all generation/analysis 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?

Usage is only implied by the verb 'play' — nothing states when to reach for this versus the generation siblings, nor any prerequisite such as the file needing to already exist. No exclusions or alternatives are named, though in this toolset the alternative set is far enough away that the risk is low.

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

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

Beyond the annotations (which only flag openWorldHint and non-read-only), the description discloses per-language billing math, a 10-second billing floor, free-trial limits, the 300s duration cap, the audio-track requirement, and that warnings never block file output. It also gives failure recovery (task_id in timeout errors, use get_sfx_task). This is unusually complete behavioral disclosure for a costly external API call.

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

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

Purpose and the critical cost warning are front-loaded, and the Args/Returns structure is scannable. It is long, and the cost paragraph could be tightened, but nearly every sentence carries operational information an agent needs before spending money.

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

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

For a 5-param, zero-schema-coverage, paid external call, the description covers inputs, mutual exclusion, limits, cost, output file naming, and error recovery. 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?

Schema description coverage is 0%, so the description carries the full burden — and it does: it explains each of the five params, including the https-only constraint on video_url, the 300 MB upload limit, that language codes match the dubbing tool's, the empty-list semantics for languages, and the source_language hint behavior. It also states the cross-parameter constraint (exactly one of video_path/video_url).

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 (transcribe a video, translate its script into target languages) and immediately delimits what it does NOT do ("Nothing is spoken and no video is produced"), which cleanly separates it from the `dubbing` sibling. An agent can distinguish it from every other sibling 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?

It gives explicit routing: use this as the step BEFORE the dubbing tool, then feed the edited .srt files back as `subtitles` on `dubbing`. It also states the gating condition ("Only use when explicitly requested by the user") and the transcript-only case (omit languages). This is the full when/when-not/alternative set.

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

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

Goes well beyond the annotations: upfront cost warning, licensing/commercial-use status, async vs streaming mode switching, 75-minute stems wait, linear cost scaling with variants, trial-account billing exception, and how to interpret a stems_error as a missing extra rather than a failed generation. This is exactly the context annotations cannot carry.

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

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

Front-loaded and organized into Args/Returns blocks with the cost warning early, which is the right priority order. It loses a point for repeating the 'requires backend async generation mode (handled automatically, same as output_format=wav)' clause three separate times, which bloats an otherwise tight spec.

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?

Covers the full lifecycle: what is produced, where it lands, the default base path, per-variant/per-stem return shapes, and failure semantics for stems. Even with an output schema present, the description supplies decision-relevant behavior (billing, waits, licensing) that the schema cannot express.

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 carries the full burden and does: prompt length range, duration bounds with the omit-to-auto behavior, format enum with bitrate and mode implications, variants range and cost/scaling semantics, stems default and side effects. No parameter meaning is left to guesswork.

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 music from a text prompt') and adds the differentiating outcome — saving audio files to a local directory. Among siblings like text_to_sfx, video_to_music and video_to_video_music, the text-prompt-to-music scope is unambiguous.

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

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

Gives an explicit guardrail ('Only use when explicitly requested by the user') and a conditional rule for stems ('set it only when the user asks for stems or separated tracks'). It doesn't name sibling alternatives for the video- or SFX-based cases, so routing between siblings is left mostly to the 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?

Adds substantial context beyond the annotations: asynchronous backend execution, that the call blocks until completion, a cost warning about Sonilo API charges, disk-write behavior with default base path, and that timeout errors carry a task_id recoverable later. None of this is derivable from readOnlyHint/openWorldHint/idempotentHint alone.

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

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

Purpose and the cost warning are front-loaded, and the Args/Returns blocks are scannable. Slightly verbose given the Args section largely duplicates what a filled-in schema would carry, but with 0% schema coverage that duplication is justified.

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 cost-incurring, disk-writing async tool, the description covers invocation, side effects, timeout recovery, and return value. Nothing an agent needs before calling it is missing, and the returns note complements the output schema rather than replacing 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 0%, so the description carries the full burden and does: prompt length bound (1–2000), duration range (0.5–180) and the meaning of omitting it, the allowed audio_format values with the aac→.m4a default quirk, and output_directory resolution against SONILO_MCP_BASE_PATH. This is materially more than the bare schema types.

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

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

States a specific verb+resource ("Generate a sound effect from a text prompt") plus a side effect (saves the audio file to a local directory). This clearly distinguishes it from audio-producing siblings like text_to_music, video_to_sfx, and video_to_sound, whose input modality differs.

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 gates usage with "Only use when explicitly requested by the user" and explains the timeout recovery path via get_sfx_task. It doesn't name the sibling alternatives (e.g. video_to_sfx for video input), so the agent must infer modality routing, but the when-to-use condition is clear.

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

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

Goes far beyond the annotations: discloses cost/billing behavior (variants above 1 never covered by free trial, cost scales linearly), internal async-mode switching conditions, a 360s duration cap and ~300 MB upload limit, and how to interpret a stems_error partial result. Annotations only give the generic openWorld/non-idempotent profile; the description supplies the operational and financial risk details.

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 purpose then the cost warning, so the highest-stakes information is early. It is long and repeats the 360-second cap across two paragraphs, and the returns block is somewhat verbose, but almost every sentence carries operational value.

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 10-param, expensive, open-world generation tool with an output schema, this is thorough: it covers licensing, cost, duration/size limits, async latency (up to 75 min), error semantics, and result labeling. An agent has everything needed to decide and invoke 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 0%, so the description must carry all meaning — and it does, documenting every one of the 10 params: defaults, valid formats, ranges (variants_num 1-10, prompt_influence 0-1), file extensions, path resolution against SONILO_MCP_BASE_PATH, and non-obvious semantics (ducking is default-OFF server-side, stems splits generated music not source audio).

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 original score for a video') and immediately describes the mechanism (pacing, motion, emotion analysis, beat alignment, exact duration match). This clearly differentiates it from text_to_music and video_to_sfx siblings because the input medium (video) and output (score) are both explicit.

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

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

Provides an explicit when-not: 'Only use when explicitly requested by the user' backed by a cost warning, which is exactly the gating condition an agent needs. It also clarifies the input requirement ('Exactly one of video_path and video_url'). It does not name sibling alternatives (e.g., use text_to_music when there is no video), so it stops short of a 5.

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

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

Goes well beyond the annotations (readOnly=false, openWorld=true, idempotent=false, destructive=false) by disclosing the external paid API, the 300 MB upload cap, the 8-minute duration cap, asynchronous backend with a blocking wait, and the timeout/task_id recovery path. It also notes invalid segments are rejected before any charge, which is exactly the cost-safety context an agent needs.

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

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

Front-loaded with purpose and the cost warning before the argument detail, and every Args line earns its place given the empty schema. It is long, but the length is driven by real constraint content rather than 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?

Covers purpose, cost, input mode exclusivity, per-parameter constraints, output location, and failure recovery, which is everything needed for a paid, non-idempotent, open-world generation tool. The return value is also summarized even though 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?

Schema description coverage is 0%, so the description must carry all parameter meaning, and it does: it documents every one of the six params, including the full segment contiguity/ordering/non-empty rules, max 30 segments, accepted formats, defaults, and path resolution against SONILO_MCP_BASE_PATH.

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 sound effects for a video") and names the backend (Sonilo) plus the analysis step, so the agent knows exactly what happens. However, the sibling list contains several near-duplicates (text_to_sfx, video_to_video_sfx, video_to_sound, video_to_video_sound) and the description never distinguishes this tool from 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?

Gives an explicit exclusion with the cost warning ("Only use when explicitly requested by the user") and states the input-mode constraint ("Exactly one of video_path and video_url"). It also covers recovery routing to get_sfx_task on timeout, but it never tells the agent when to prefer this over video_to_video_sfx or video_to_sound.

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 convey readOnly=false and openWorld=true; the description supplies the operationally important facts an agent cannot infer: asynchronous with a blocking wait, per-call charge, validation happens before any charge, licensing/clearance, linear cost scaling with variants_num, variants >1 never trial-covered, and timeout recovery via get_sfx_task. It also discloses a default-state trap (ducking has no keep_original_sound, so the result excludes source speech 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?

Front-loaded with purpose and the sibling-routing decision, then cost warning, then parameters. Nearly every clause carries unique information, but the density is high — the ducking/preserve_speech explanation and the output_format comparison to video_to_video_sound repeat context. Given 0% schema coverage this length is largely justified rather than 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 10-parameter, asynchronous, billable, file-writing tool this covers everything an agent needs: input formats and limits, validation-before-charge, cost model including the trial carve-out, variant naming, and failure recovery. Output-schema existence notwithstanding, it still explains the variant file naming and the timeout error's task_id, which are behavioral rather than structural.

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 10 parameters, so full burden is on the description — and it delivers for nearly every one: accepted formats and 300 MB / 480 s limits for video_path, max 2000 chars for both prompts, max 200 chars and six backend contiguity rules for segments, defaults and semantics for preserve_speech/ducking, allowed enum-ish values and stem caveat for output_format, range and billing behavior for variants_num, and the default base path for output_directory. It also adds the cross-parameter constraint the schema omits ("Exactly one of video_path and video_url").

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 music AND sound effects for a video") plus the output shape ("mixed into a single audio track (no video)"), which immediately distinguishes it from video_to_music/video_to_sfx (separate layers) and video_to_video_sound (returns mp4). The parenthetical "(no video)" resolves the one ambiguity an agent would have against its sibling.

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 routing: "Use this instead of calling video_to_music and video_to_sfx separately" with the reasons (backend balance, single charge). It also states the gating condition "Only use when explicitly requested by the user" and gives a redirect for a related need ("Pass preserve_speech instead to bring in the isolated speech"), so both when-to-use and when-not are covered.

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 write/open-world profile; the description adds the substantive behavior: asynchronous execution that blocks until done, no re-encoding of the source picture with an accepted codec/container list, the default of discarding source audio, ducking's silent best-effort fallback, and that variants above 1 are billed even on trial. This is well beyond what the annotations convey.

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

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

Front-loaded with the distinguishing output type and the cost gate, then a well-structured Args block. It is long, and the 'music ALONE' default is stated twice (prose and keep_original_sound), but the length is largely justified by ten undocumented-in-schema parameters.

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 paid, async, ten-parameter mutation tool with an output schema, nothing material is missing: input constraints, format rejection rules, mode interactions, cost behavior, and return shape (including variant naming and timeout recovery) are all covered.

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 carries the full burden and does: it documents all ten parameters including segment structure rules (first start 0, ≥5s apart, label enum values), ducking's precise meaning and no-op conditions, supersede relationships between keep_original_sound/preserve_speech, variant cost scaling, and prompt_influence's 'leave it alone' default.

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 an original score for a video and return a NEW VIDEO with the music muxed in') and explicitly distinguishes itself from the audio-only sibling by parenthesizing 'not just an audio file'. An agent can pick it apart from video_to_music / video_to_video_sound without opening a schema.

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

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

Gives explicit when-to-use guidance ('Only use when explicitly requested by the user' due to cost), the exact-one-of constraint on video_path vs video_url, and a decision path for the audio modes (default alone, keep_original_sound, +ducking, or preserve_speech). It also names the recovery route via get_sfx_task on timeout.

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 flag a non-idempotent, open-world write, but the description adds substantial behavior beyond them: third-party Sonilo API charges, asynchronous execution that blocks until completion, pre-charge validation of segments, upload/duration caps (300 MB, 480 s), and a recovery path via get_sfx_task using the task_id in timeout errors. This is exactly the cost, latency, and failure-recovery context annotations cannot express.

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

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

Front-loads the key differentiator and the cost warning before any parameter detail, then uses Args/Returns structure that is easy to scan. The Args block is dense and long, but nearly every line is load-bearing constraint information rather than 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 costly, slow, open-world generation tool with zero schema description coverage, the description covers cost gating, async semantics, input formats and limits, segment validation, output location, and timeout recovery. An output schema exists, yet the Returns section still adds the timeout/task_id behavior an agent needs to recover, so nothing essential is missing.

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

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

Schema coverage is 0%, so the description carries the full burden and does: each of the five parameters is documented with format constraints (.mp4/.mov/.webm/.m4v, animated gif), size/duration limits, the nested segment object shape {start, end, prompt}, and all six backend segment validation rules. This meaningfully exceeds what the bare anyOf schema conveys.

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, and output artifact: generate SFX and return a NEW VIDEO with the SFX muxed in. The parenthetical "not just an audio file" explicitly separates it from the audio-returning siblings (video_to_sfx, video_to_sound, video_to_video_sound) without the agent needing to open 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 gate ("Only use when explicitly requested by the user" due to cost) and the input-exclusivity rule ("Exactly one of video_path and video_url must be provided"). It implies but never names the alternative tools, so an agent weighing video_to_video_sfx against video_to_sfx must infer the split from the output-format hint alone.

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

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

Annotations only cover the generic safety profile (not read-only, open-world, non-idempotent); the description adds the substantive behavior: asynchronous generation with blocking wait, per-call and linearly scaling charges, trial exclusions for variants, licensed/cleared music, default removal of source audio, the keep_original_sound/preserve_speech interaction, and timeout recovery via get_sfx_task.

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?

It is long but front-loaded: purpose and sibling differentiation first, then a clearly flagged cost warning, then per-argument details, then returns. Each sentence carries actionable information (rules, defaults, interactions, recovery path) rather than restating the name or schema titles.

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 10-parameter, costly, asynchronous generation tool, nothing an agent needs is missing: input source rules, format/size/duration limits, segment constraints, variant output naming, timeout/task_id recovery, and billing caveats are all covered. Return values are additionally described despite an output schema existing.

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 carries the full burden and does: it documents defaults, formats and limits for video_path, backend validation rules for segments (contiguity, max 30, 200-char prompts), variants_num cost implications, output_directory default, and the precedence and no-voice no-op semantics of keep_original_sound, preserve_speech, and ducking.

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 opening sentence names a specific verb and resource ('Generate music AND sound effects for a video') and states the distinctive output ('return a NEW VIDEO with the mixed soundtrack muxed in (not just an audio file)'). It explicitly contrasts itself with the siblings video_to_video_music and video_to_video_sfx, so an agent can route correctly without inspecting 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?

It gives an explicit preference rule ('Use this instead of chaining video_to_video_music and video_to_video_sfx') with the reasons (backend balancing, single charge) and a hard gating condition ('Only use when explicitly requested by the user' due to cost). It also states the input exclusivity rule ('Exactly one of video_path and video_url must be provided').

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