AwesomeVideo

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description does add real value beyond them: 'drop its parts' discloses exactly what is destroyed, and 'Free' discloses cost behavior — a genuinely useful addition. But it omits what happens to the file record itself and any error behavior on an already-completed upload.

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

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

Two short sentences with no filler. The only structural quibble is that the cost note 'Free' is front-loaded ahead of the actual action, so the purpose verb arrives second, though the description remains trivially scannable.

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

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

For a one-parameter destructive tool with annotations covering destruction and idempotency and no output schema, the description is minimally adequate. It would be complete enough if it said what fileId refers to and whether aborting a completed or unknown upload errors out.

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

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

Schema description coverage is 0% for the single required parameter, fileId, so the description must carry the burden — and it says nothing about it. It does not clarify whether fileId is an upload identifier, a file identifier, or where the agent obtains it. This is a real gap for the only input.

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 ('Cancel') on a specific resource ('an unfinished multipart upload'), which unambiguously separates it from create_multipart_upload and complete_upload in the sibling list. It stops short of naming those siblings explicitly, but the resource qualifier does the differentiation work.

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?

'Unfinished multipart upload' implies the precondition (an in-progress upload exists), and 'Free' hints that there is no billing consequence. However, there is no explicit statement of when to use this instead of complete_upload, nor what happens if the target upload is already finished or nonexistent.

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

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

Goes beyond the annotations by disclosing billing semantics (dryRun debits nothing) and atomic pre-flight failure: a 402 refuses 'before any item starts' when the balance cannot cover the total. That all-or-nothing guarantee is exactly the kind of behavior an agent can't get from readOnlyHint/destructiveHint alone. It doesn't address partial failure after start or what the success response contains.

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

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

Three short sentences, front-loaded with what the tool does, then the two conditional behaviors. No filler or restatement of the title.

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

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

With no output schema and 5 parameters, the description covers the dryRun/billing contract but says nothing about what a successful batch returns (job IDs? per-item results?), what happens after the pre-flight check passes, or how preset/maxCredits interact with items. Adequate, not complete.

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

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

Top-level schema coverage is effectively 0%, so the description must compensate; it does explain dryRun's meaning and implies operation via 'transcribe or burn items'. But maxCredits and preset are never mentioned, and the per-item object shape is left entirely to nested schema 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?

States a specific verb and resource: 'Quote and run up to 10 transcribe or burn items', which pins down both scope (max 10) and the two operations. Sibling differentiation is implicit via the batching framing rather than naming transcribe or burn_captions directly, so an agent must infer 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 explains the dryRun path ('returns the quote and does not debit') and the insufficient-balance case, which is real usage guidance. However, it never says when to prefer this over the single-item siblings (transcribe, burn_captions) or what maxCredits/preset overrides are for, leaving the selection decision largely 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?

Goes well beyond the annotations: discloses paid pricing relative to transcription, x264 preset/resolution/audio-copy/scale-to-zero container behavior, the 402 insufficient_balance payload shape (requiredCents, howToBuy), 422 codes for invalid_platform and audio_visual_needs_audio_input, and that safe-zone/platform/autoFit/combined add no cost. Annotations only cover readOnly/idempotent, so this adds substantial undisclosed 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 purpose and cost, then error contract, then the alternative tool, then platform logic — a sensible order. The platform sentence is long and carries a bilingual example and a warning aside, which is slightly heavy against the value it delivers.

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 20-parameter render tool with no output schema, it covers billing, errors, safe-zone output shape, and the client-side alternative. The main gap is never stating that one of fileId/mediaUrl (or an upload id) is required despite 'required: 0', leaving the agent to guess the valid input combinations.

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 55%, and the description compensates by explaining the input-substitution rule (subtitles SRT/VTT/JSON or transcriptionJobId, plus preset id or name) and the semantic effect of platform. Still, key parameters (fileId, mediaUrl, maxCredits, presetId vs presetName precedence) are never explained in either place.

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 ('Burn captions into video') and explains the mechanism (native ffmpeg + ASS script from an AwesomeVideo preset), which distinguishes it from prepare_client_burn and caption_video. An agent can immediately tell this is the server-side paid render path.

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

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

Explicitly routes to prepare_client_burn when cost matters ('For a render that costs AwesomeVideo nothing') and gives a clear rule for platform ('pass it when the user names where the video goes ... if they did not say and it matters, ask'). It does not contrast with sibling caption_video or transcribe, so not quite a 5.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, and the description adds the non-obvious behavior: the call itself is free, it is a human-in-the-loop handoff, and credits only arrive after payment so the caller must retry. It does not say what happens on repeated calls (non-idempotent, could double-charge), which is the one meaningful gap for a paid flow.

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 cheapest fact ('Free') and then the value, the human handoff, and the alternative. No filler or repetition of the title.

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

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

With no parameters and no output schema, the description covers everything an agent needs: cost, what is returned (a checkout URL), who must act on it, when credits appear, and which sibling to use for other purchase sizes.

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 fixed 500-credit/$5 quantity is stated instead. Baseline 4 applies for a parameterless tool.

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 ('Returns a checkout URL that buys 500 credits for $5 for this exact key'), including the exact price and scope. It explicitly names the sibling create_checkout as the tool for bigger packs, so the agent can route without opening either schema.

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

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

Gives the preconditions ('works on self-serve keys, no sign-in'), the handoff step ('Show the URL to your human'), the post-payment retry instruction, and the exclusion ('For bigger packs or plans use create_checkout after the key is claimed'). When-to-use and when-not-to-use are both explicit.

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

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

Annotations only declare the safety profile (openWorld, idempotent, non-destructive), and the description adds substantial context beyond them: exact credit pricing per step, over-limit thresholds and the 422 limit_exceeded/charged:false behavior, automatic refunds, wait/waitSeconds blocking semantics with progress/eta/pollAfterSeconds, and the review:true approval flow that defers the burn charge. This is far more than 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 'PREFER THIS' routing and the one-call pipeline before pricing and edge cases, which is the right order. It is long, but for a 23-parameter job tool nearly every sentence carries operational information; a few pricing/limit clauses could be compressed.

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 what an agent needs for a complex async job tool with no output schema: return artifacts, credit cost, size/duration limits, failure and refund behavior, polling contract with pollAfterSeconds, and the human-review variant. Nothing material is left to inference.

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 96%, so the baseline is 3; the description still adds value by tying cost to parameters (translateTo +2 credits/min, faceAvoid and highlightWords same price), clarifying sourceUrl vs fileId sources, and noting review cannot combine with translateTo. It does not add much beyond the already-rich schema for the nested audioVisual/styleOverrides objects.

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 ('add/burn subtitles to this video') and names the exact pipeline it runs (transcribe -> optional translate -> burn) plus what it returns (MP4, SRT, VTT, JSON, credits). It also distinguishes itself from siblings by saying 'PREFER THIS' and naming burn_captions/transcribe/edit_transcript as the manual path.

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: prefer this one-call tool for subtitle requests, use transcribe -> edit_transcript -> burn_captions when the user wants to fix text, use quote first if unsure of cost, poll get_job or pass webhookUrl/notifyEmail if the wait times out, and resume_job if it fails after transcribing. When-not conditions (YouTube refused, audio_visual on video input) are also 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?

Adds real behavior beyond the annotations: it is free of charge, and a failed precondition returns 409 upload_incomplete with a missingParts field, which is valuable failure-mode disclosure. 'Idempotent' merely restates idempotentHint=true and there is no mention of auth requirements, so it is not a 5.

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

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

Five telegraphic fragments, no waste, cost and precondition front-loaded before the downstream instruction. The fragment style ('Then pass fileId to any tool') is efficient but slightly ambiguous about what is actually returned.

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 cost, precondition, idempotency, error shape, and the follow-up call. The main gap is that it never states what a successful call returns or that it is the terminal step of the multipart flow.

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% and the single fileId parameter is undocumented in the schema, so the description must carry the burden. It implies fileId is the upload handle passed downstream, but never says where fileId comes from (presumably create_multipart_upload) or what it identifies — only partial compensation.

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 action — assemble the file after every part is PUT — which distinguishes it from create_multipart_upload and abort_upload without naming them. 'Free' also flags no credit cost. It never explicitly names the sibling sequence it belongs to, 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?

Gives a clear precondition ('After every part is PUT') and a clear next step ('Then pass fileId to any tool'), which is exactly the workflow context an agent needs. It does not mention the abort_upload alternative or when to give up on an upload, which keeps it below 5.

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

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

Beyond the annotations (openWorldHint, non-idempotent, non-destructive), the description adds a real prerequisite, a named error response, and the 'Free.' cost signal, plus a pointer to an external account page. It doesn't cover what happens on repeated calls or what the response body looks like beyond the URL, but the annotation set already carries most of 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?

Information-dense with no filler: the price table, prerequisite, and alternative all earn their place, and the scoping is front-loaded. However, it reads as a long semicolon-chained fragment, and the opening 'Free.' is ambiguous enough to make the agent pause.

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 still identifies the return value (a checkout URL), the error case (account_required), and the precondition, which is everything needed to invoke this 2-param tool 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% and the two enums are opaque on their own; the description fully compensates by mapping each product enum value to its price and credit amount, and by explaining that interval=year means 10x the monthly figure. This is exactly the semantics an agent needs and the schema cannot supply.

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 makes clear that this produces a checkout URL for a 'pack or plan' and enumerates every product with its price/credit value, so an agent knows exactly what resource is involved. The verb itself is implicit rather than stated ('Checkout URL for a pack or plan:'), relying on the tool name, and the leading 'Free.' is unexplained. Still clearly separable from siblings.

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

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

It states the prerequisite (the key must be claimed by an account at the given URL), the failure mode if not met (returns account_required), and the alternative tool for that case (buy_credits). That is explicit when-to-use / when-not / alternative routing.

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 past the annotations (which only cover safety/idempotency) by disclosing the credit pricing formula with a worked example, reservation-and-refund semantics, automatic refund on failure, and the specific 422 refusals for YouTube/TikTok/Instagram source URLs. Also states the wait cap (50s) and that jobs continue server-side afterward.

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 routing decision and then the pipeline, so an agent reading only the first clause already knows when to call it. The rest is a dense run-on that repeats schema defaults (reframe, captions, platform, preset) and could be split into short labeled blocks for easier scanning at 27 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 27-parameter, no-output-schema job tool this is close to complete: it spells out the returned clips array with every field and its sort order, plus pricing, async polling, and error behavior. An agent can decide, budget, and parse the result from the description alone.

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 78%, and the description still adds meaning the schema lacks: default count 3 / max 10, minSeconds-maxSeconds default 15-60 within 5-90, and what each reframe mode actually does (face-follow with center fallback vs plain crop vs source shape). A few parameters (glossary, webhookUrl, brandPresetId, idempotencyKey) get no explanation anywhere, keeping it below 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 ('turn this long video/podcast/stream into shorts/clips/highlights') and enumerates the exact pipeline: transcribe, LLM-select moments, sentence-boundary cut, render. It explicitly claims precedence over the sibling 'shorts' tool with 'PREFER THIS', so an agent can route without opening schemas.

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

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

Gives a clear use trigger and internal alternatives (reuse transcriptionJobId/subtitles to skip cost, quoteOnly to price, get_job/webhookUrl/notifyEmail for long jobs). It stops short of naming when to use a sibling instead — e.g. caption_video or burn_captions when the user only wants captions burned on an existing clip.

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

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

Adds substantial behavior beyond annotations: no sign-in, zero starting credits, one-time token return, required storage and Authorization header usage, downstream 402 responses with checkoutUrl, pricing, and per-network daily key limits. These details materially help an agent understand the auth and billing flow.

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

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

The description is compact and front-loaded: the free/no-sign-in bootstrap context comes first, followed by token handling, downstream paid-tool behavior, and rate limits. Every sentence adds useful operational context without waste.

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

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

Given one optional parameter, no output schema, and annotations covering safety hints, the description supplies everything an agent needs: why to call it, what it returns, how to use the token, and what happens when credits run out.

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

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

The schema has 100% description coverage for the single optional `name` parameter, so the schema already carries parameter meaning. The description adds no additional guidance about the `name` field, which is acceptable but not enriched.

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

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

States a specific verb and resource: create a new AwesomeVideo API key. It also distinguishes itself from credit-purchase tools by emphasizing that it is free, requires no sign-in, and works without an existing key.

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?

Clearly establishes the bootstrap context: call this when no key exists, then store the returned token and use it as a Bearer token. It also explains the downstream 402/checkout behavior for paid tools. It does not explicitly name a sibling alternative or state when not to call it, which keeps it below 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?

Beyond the annotations, the description discloses cost (free), size and duration limits, rate limit (30 per hour), return payload, PUT URL validity, and that part URLs need no API key. It also explains parallel/out-of-order uploads and replacement behavior for re-sent parts, which is exactly the operational 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?

It is front-loaded with purpose, limits, return shape, and workflow, so the agent can extract key facts quickly. It is somewhat long and includes redundant part-size details plus two shell examples, but the density is largely justified by the multipart workflow.

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 multipart creation tool with no output schema, the description covers return fields, upload mechanics, resume behavior, completion, downstream fileId usage, and limits. Nothing essential for correct invocation or recovery 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 100%, so the baseline is 3. The description adds useful semantics for sizeBytes by giving an effective 80 MB to 2048 MB operating range and repeats the partSizeBytes default/range in MB, though it does not add much for filename or contentType beyond the schema.

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

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

The description states a specific verb and resource (create multipart upload) and immediately scopes it to files over 80 MB or flaky connections. That size/condition threshold distinguishes it from simpler sibling upload tools without requiring the agent to inspect other 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 clearly says when to use this tool (large files, flaky connections) and names get_upload_status and complete_upload for the resume/complete workflow. It does not explicitly name the small-file alternative such as create_upload, so the routing guidance is clear but not fully exhaustive.

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

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

Adds substantial behavior beyond the annotations: the URL is single-use, expires in 15 minutes, is tied to the key or account, and the PUT needs no API key. It also discloses the 80 MB/2048 MB thresholds, the 422 use_multipart_upload error, the 30-per-hour rate limit, and that the PUT must be raw bytes with matching size and headers.

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 front-loads the core promise (free, fileId plus single-use PUT URL) and then packs thresholds, error path, example command, downstream tools, and rate limit into a dense but waste-free paragraph. The single block is slightly run-on, but every sentence carries operational information.

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

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

For a three-parameter tool with no output schema, it covers the full workflow: create the upload, PUT the raw bytes with returned headers, and pass fileId to plan, quote, transcribe, burn_captions, shorts, trim, dub, or preview. The size-based failure path and rate limit leave nothing an agent needs 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 already 100%, so the baseline is 3. The description still adds consequences the schema does not: sizeBytes determines whether this endpoint succeeds or returns a 422 multipart redirect, and contentType must be the actual raw PUT Content-Type header rather than multipart.

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 action and outputs: it returns a fileId and a single-use PUT URL for a local video/audio file. It distinguishes itself from the closest sibling by naming create_multipart_upload as the path for files over 80 MB, and its scope (local byte upload) separates it from upload_base64 and import_url.

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 clearly framed: try this first, and if the file exceeds 80 MB (up to 2048 MB) the API returns 422 use_multipart_upload and you should call create_multipart_upload instead. It stops short of explicitly ruling out siblings like upload_base64 or import_url, so an agent still has to infer those alternatives.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered structurally. The description adds one genuinely new fact — the call consumes no credits — but says nothing about permanence or recoverability beyond what the hints imply.

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

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

Two short sentences, front-loaded with the action and resource; nothing is padded. The trailing "Free." fragment is terse but carries real information, so it earns its place.

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

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

For a one-parameter destructive delete with full annotation coverage and no output schema, the definition supplies the action, target, ownership scope, and cost. The main residual gap — what `id` refers to — is a parameter-level issue already captured above rather than a completeness failure.

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 burden for the single required parameter, yet it never says what `id` identifies. The phrase "for this key or account" is ambiguous and could be read as describing the id itself or the ownership scope of the preset.

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 ("Delete a saved brand preset") with a scope hint ("for this key or account"). It does not explicitly distinguish itself from the sibling delete_custom_preset, so an agent must infer the brand-vs-custom distinction from the name alone.

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

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

The only usage signal is the word "Free," which is a cost note rather than guidance. Nothing says when to use this instead of delete_custom_preset, or what prerequisite state (preset must exist, ownership) is needed.

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 destructive, idempotent and non-read-only, so the safety profile is covered. The description still adds two genuinely non-obvious facts: the operation is free (no credits), and an already-approved community copy survives the deletion. It stops short of saying whether the preset itself is recoverable.

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 no filler; the cost signal is front-loaded and the exception clause follows the main action. The leading 'Free.' is slightly abrupt but earns its place by answering the cost question early.

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

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

For a one-parameter destructive tool with annotations covering reversibility and idempotence, the description covers cost and the community-copy side effect. The unresolved 'id' semantics and the lack of any guidance on locating or confirming the target preset keep it at minimum-viable rather than 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% and the single 'id' property is undocumented. The description only hints that the id refers to one of the caller's own saved presets; it does not state the identifier format, where to obtain it (e.g. list_custom_presets), or what happens with another user's id.

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 ('Delete') and resource ('one of your saved custom presets'), which implicitly separates it from delete_brand_preset and delete_glossary by scope. It does not explicitly name a sibling, so the differentiation rests on the reader's inference.

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?

'one of your saved custom presets' implies an ownership precondition, and the gallery note clarifies a boundary case. But there is no explicit guidance on when to use this versus delete_brand_preset or how it relates to submit_custom_preset/update_custom_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 already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to re-state danger. It does add real value by disclosing that the call is "Free" (no credit cost) and by clarifying the two deletion scopes, but it omits what happens with missing/nonexistent terms or whether deletion is reversible.

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

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

Two short sentences, front-loaded with the "Free" cost signal and then the two deletion modes. No filler, though the single-word "Free." fragment is slightly cryptic out of context.

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 destructive, 2-parameter tool with no output schema and zero schema descriptions, the definition is minimally adequate: both parameters get some explanation and the cost is stated. It lacks edge-case behavior (empty terms, mixed all+terms, nonexistent term) that an agent would need to call it confidently.

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

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

Schema description coverage is 0%, so the description must carry the load, and it partially does: it explains that "all: true" clears everything and that terms can be removed individually. It does not explain the `terms` array's semantics in detail, whether `all` and `terms` can be combined, or what happens when both are omitted.

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 ("Remove") plus resource ("saved glossary terms") makes the operation unambiguous and clearly distinguishes it from save_glossary and get_glossary. The scope is stated up front, though it doesn't explicitly name those siblings.

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

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

The two operating modes (per-term removal vs. "all: true to clear it") imply when each form is used, but there is no explicit guidance on prerequisites, when not to use it, or pointers to the sibling save/get glossary tools.

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

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

Adds substantial context beyond the annotations: per-language credit pricing, voice providers by tier, 1.25x timing fit, one rewrite, -18 dB ducking, output formats (MP4, SRT/VTT/JSON, optional M4A), 422 pre-charge validation, and refund-on-failure behavior. These details are consistent with readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true.

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 information is relevant, but it is delivered as one very long run-on sentence that opens with credit pricing rather than the action. The density and lack of paragraph structure make it harder to scan than necessary.

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 13-parameter mutation with no output schema, it explains outputs, failure/refund behavior, and reuse options well. It does not explain how to supply source media via fileId vs mediaUrl, nor what maxCredits does.

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?

Explains several important parameters beyond the schema: keepOriginalAudio defaults to duck and can mute, audioTrack adds an M4A, and the two job/subtitle reuse paths. It leaves voice, fileId, mediaUrl, maxCredits, and sourceLanguage largely to the schema, which is acceptable at 62% coverage but not fully compensating.

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: dubbing a video into another language, then details the full pipeline (transcribe, translate, voice, timing-fit, mix, return). This clearly separates it from siblings like translate (text-only), caption_video, and burn_captions.

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 useful prerequisites and reuse paths: call plan first for unsupported languages/tiers, reuse via transcriptionJobId/subtitles and translationJobId/translatedSubtitles. It also excludes voice cloning and lip sync, but does not explicitly name translate or caption_video as alternatives.

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely new traits: zero cost and the downstream billing effect on burn_captions. It also clarifies that edits are a full replacement of cues rather than a merge. Missing: what happens to the previous cues or the returned job state.

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 padding; the primary action and the cost caveat come first. The telegraphic fragments ('Cost is zero.') are efficient rather than noisy, though they read slightly clipped.

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 3-parameter mutation tool with no output schema, the description covers the cost model and input formats but omits return behavior, whether the job must already be complete, and cue timing units. An agent could invoke it but might guess wrong on payload format or state assumptions.

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 has to compensate, and it partially does by naming the two optional inputs and the accepted subtitle formats (SRT, VTT, JSON). However, it never explains jobId, whether cues and subtitles are mutually exclusive or which wins, or the units for start/end (seconds vs. milliseconds) — a significant gap for a timing-critical payload.

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: 'Replace the cues on a finished transcription.' The phrase 'without running Whisper again' implicitly contrasts it with transcribe, so an agent can distinguish the edit path from the re-transcription path. It stops short of naming a sibling tool explicitly, which keeps it from a 5.

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

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

Gives clear context for use: after transcription is finished, before caption burning, and explains the cost relationship with burn_captions (passing this transcriptionJobId charges only the burn price). No explicit exclusions or preconditions (e.g., job must be in a completed state) are stated, so it falls 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?

With annotations already covering safety hints, the description adds substantial behavioral context: exact credit pricing, added transcription cost for video-only input, ~40 s wait before polling get_job, platform-specific output norms, language default, and YouTube chapter timing rules. This is far beyond what the annotations provide.

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

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

The description is dense and information-rich, with most critical constraints stated up front and no obvious filler. However, it is a long single paragraph and leads with pricing rather than the core action, which slightly reduces scanability.

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 11-parameter paid async tool with no output schema, the description provides unusually complete context: result shape, chapter constraints, platform behavior, language default, and polling guidance. It still leaves out maxCredits, quoteOnly, and durationSeconds behavior, which matter for cost control and previewing.

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 low at 36%, and the description compensates well for the core inputs: transcriptionJobId job types, subtitles, fileId/mediaUrl, platforms and defaults, language behavior, titleCount range/default, and context notes. It still omits meaningful detail for maxCredits, quoteOnly, and durationSeconds, so coverage is strong but incomplete.

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: writes publishing metadata (titles, description, hashtags, YouTube chapters) from what is said in a video. It distinguishes this from transcription by saying no re-transcription is needed when a transcript exists, and it clearly defines the generated artifacts per platform.

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

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

It gives clear input-selection guidance: pass transcriptionJobId or subtitles, otherwise fileId or mediaUrl, and for trimmed videos use the trim job so chapter times match. It also explains the async wait/poll fallback. It lacks explicit when-not guidance and does not mention cost-checking siblings like quote or plan.

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

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

Annotations already declare this is a read-only, idempotent, non-destructive operation. The description adds useful domain behavior beyond the annotations: server burns spend the burn price, which is higher than transcription, and the client render path does not spend balance.

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

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

The description is three short sentences with no wasted text. Purpose is front-loaded, and the following two sentences add spend-model context that is directly relevant to interpreting the returned balance.

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?

Although there is no output schema, the description explains that the balance is returned in cents and in transcription-equivalent audio seconds. Combined with the annotations, this is sufficient for a no-parameter read tool.

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

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

There are zero input parameters, and the description correctly does not attempt to explain any. The baseline for a no-parameter tool is 4, and there is no parameter ambiguity to resolve.

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

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

The description gives a specific verb and resource: 'Read the prepaid balance for this API key.' It also states the units returned (cents and transcription-equivalent audio seconds), making it clearly distinct from sibling tools like get_usage or buy_credits.

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

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

The description implies this tool is used to check available prepaid credits, and it explains that server burns consume balance while the client render path does not. However, it never explicitly says when to call this instead of alternatives such as get_usage or before buy_credits, so usage guidance remains implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds two useful non-annotation facts: the call is free (no credit cost) and it returns the full style JSON rather than a summary. It says nothing about behavior for a missing id or whether brand presets are covered.

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 fragments with no filler, and the cost note plus the resource scope are front-loaded. The telegraphic style ('Free. One saved custom preset...') is efficient but slightly stenographic compared to a full sentence, costing a bit of readability.

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

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

For a one-parameter read tool with no output schema, the description covers the key unknowns: cost, id format, and that the full style JSON comes back. It is thin only on the not-found error path and on disambiguation from the preset-listing and style-reference siblings.

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

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

Schema description coverage is 0% and the single id parameter carries no description at all, so the description is the only source of format information. It supplies the accepted id shapes (cp_... or custom:cp_...), which is exactly the missing operative detail for this one required param.

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 the specific resource (a saved custom preset) and scopes it to exactly one item fetched by id, which distinguishes it from list_custom_presets and list_presets. It does not name any sibling explicitly, so an agent must infer the single-vs-list split rather than being told.

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 "by id" phrasing implies this is the follow-up call once a preset id is known, but there is no explicit when-to-use vs when-to-use-instead guidance. No mention of what to do when the id is unknown (use list_custom_presets) or how this differs from get_style_reference or list_presets.

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-open-world, non-destructive, so the safety profile is covered. The description adds two things the annotations do not: that the call is free (relevant given buy_credits/get_balance siblings) and that the returned glossary is automatically enforced on transcribe/translate — real behavioral context. It stops short of describing response shape or empty-state 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?

Two sentences, zero waste. The cost signal ('Free.') is front-loaded, followed immediately by what the resource contains, and the last sentence carries the one behavioral fact that matters. Nothing is repeated from the title 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?

With no parameters and no output schema, the description carries the burden of describing the return value, and it does so semantically by enumerating the glossary's entry types. Adequate for a zero-arg read; only the concrete response field names and empty-glossary behavior are absent.

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

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

Zero parameters, so the baseline is 4. The description nonetheless clarifies the scope of the implicit target — the glossary belongs to 'this account (or key)' — which tells the agent the result is scoped to its credentials rather than globally addressable.

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

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

Names a specific resource (the saved glossary of this account/key) and enumerates its contents — preferred spellings, brand names, alias fixes, do-not-translate terms — so the agent knows exactly what comes back. The verb is only implied by the name rather than stated in the description, and no sibling (save_glossary, delete_glossary) is explicitly contrasted, which keeps it from 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?

Usage is implied rather than stated: by saying the glossary 'is applied to every transcribe and translate automatically,' it hints the agent should read this to know what corrections will be applied. It never says when to call it, whether it is a prerequisite to anything, or how it differs from other read tools like list_presets or get_custom_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 already declare readOnly/idempotent/non-destructive, yet the description still adds substantive behavior: the result URL is expiring, eta is derived from media length times rolling per-step averages, and burn progress is real ffmpeg progress. These are things an agent cannot infer from the annotations or schema and directly affect how it should poll and consume results.

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, and every clause in the long enumeration conveys distinct, useful information about a returned field. It is a dense run-on list rather than cleanly structured prose, but nothing is redundant.

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

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

With no output schema and only one input param, the description carries responsibility for explaining what comes back, and it does so field-by-field (step enum values, progress scale, eta sources, cost, expiring URL). Combined with the resume_job handoff for failed jobs, an agent has enough to call it and interpret results 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?

There is a single parameter with 100% schema description coverage ('Job id returned by transcribe or burn_captions'), so the schema already carries the semantics. The description adds nothing about jobId itself, which is the baseline case for a high-coverage single-param schema.

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

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

Opens with a specific verb+resource ('Read any job') and immediately scopes it as a single-job lookup by id, which implicitly separates it from the batch-oriented list_jobs sibling. It doesn't name list_jobs explicitly, so the differentiation is implied rather than stated.

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

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

Gives real operational guidance: 'pollAfterSeconds (wait that long before the next poll)' tells the agent how to poll, and 'A failed caption job with resumable:true can be restarted with resume_job' names a sibling and the exact condition for switching to it. It lacks an explicit statement of when to use list_jobs instead, which keeps it from a 5.

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

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

Annotations already cover readOnly/idempotent/non-destructive, yet the description still adds real value: 'Free' (no credits consumed by polling), the full enumeration of terminal states, that rejection charges nothing, and that approval carries burnJobId plus a video URL. It does not state auth or rate-limit behavior, but the state machine disclosure is the useful part here.

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 dense sentence that front-loads the cost signal ('Free.') and then the outcome branches. Every clause carries distinct information; the parentheticals are compact rather than wasteful.

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 carries the return-value burden and does so by enumerating all four states and their payloads. What's missing is minor: how to obtain reviewId and what to do with a burnJobId once returned.

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% for the single reviewId parameter, so the schema alone gives no guidance. The description only indirectly signals provenance by tying the review to request_review, which lets an agent infer the ID comes from that call's response, but it never says so outright or states the ID format.

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

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

States a specific resource (a review's status) and its origin ('from request_review'), which cleanly separates it from the sibling request_review that creates the review. The verb is implicit ('get status') rather than explicit, but the intent 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?

The phrase 'from request_review' implies the polling flow: call request_review, then call this to check status. There is no explicit when-to-use statement, no polling cadence, and no note about whether to prefer get_job instead once a burnJobId exists.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), and the description adds the cost/auth fact the annotations cannot express: 'Free, no key.' It also discloses the shape of what comes back — type, allowed values or range, description, JSON examples — which is genuinely useful since there is no output schema. It stops short of saying how the response is structured or how large it is.

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

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

The lead is front-loaded and high-value ('Free, no key'), and every clause carries information. The long field enumeration is dense but purposeful for a reference tool. The only friction is that it reads as two run-on sentences rather than cleanly separated intent.

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 parameters and no output schema, the description bears the burden of describing the payload, and it does so by listing the covered fields and their per-field metadata. What is missing is the response envelope — whether it returns one JSON object, a keyed map, or prose — which an agent preparing to parse the result would want.

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

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

The tool takes zero parameters, so the schema has nothing to document and the baseline is 4. There is no argument semantics left for the description to carry, and it correctly spends no words on parameters.

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 resource — the caption style field reference — and enumerates exactly what it covers (font, colors, stroke, background, wordStateStyles, smartEmphasis, caption forms, faceAvoid). It also explicitly separates itself from the visual sibling by pointing to style_preview for on-video rendering.

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 prerequisite chain: call this before styleOverrides, highlightWords, save_custom_preset, or validate_preset_style. It also names an alternative (style_preview) and the condition that selects it (see styles on the actual video). Both when-to-use and which-alternative 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?

The annotations already declare this as read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral context beyond those annotations, including cost ('Free'), the returned status fields, and the resume workflow.

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 tight sentences with no wasted language, front-loading cost and returned fields before the resume workflow. Every sentence contributes directly to correct invocation.

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

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

There is no output schema, so the description must explain return values; it does so by enumerating state, completedParts, missingParts, and bytesReceived. For a one-parameter status tool, that is complete enough to support the resume workflow it describes.

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

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

Schema description coverage is 100%, and fileId is already documented as coming from create_multipart_upload. The description references create_multipart_upload URLs but does not add meaningful semantics for the single parameter beyond the schema.

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

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

The description states the specific resource and returned information: state, completedParts, missingParts, and bytesReceived for a multipart upload. It also distinguishes the tool's role by tying it to resuming interrupted uploads and naming create_multipart_upload and complete_upload.

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

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

It explicitly scopes usage to resuming an interrupted upload and gives the next steps: PUT only missing parts using the same URLs then call complete_upload. It does not state when not to use this tool or explicitly contrast it with abort_upload.

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 read-only, idempotent, non-destructive behavior. The description adds useful context beyond annotations: the 30-day window, key-vs-account scope, and the transcription/server burn split. It does not describe rate limits or full return shape, but the added behavioral detail is substantial.

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

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

The description is three concise sentences with no wasted text. The scope and key data are front-loaded, followed by the split and parameter units.

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 simple read-only usage tool with no output schema, the description covers the essential window, scope, split, and parameter units. It is slightly incomplete because it does not clarify the default date-range behavior when from/to are omitted or what the response structure looks like.

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 correctly documents that from and to are unix milliseconds, which is valuable. However, it does not explain default behavior when these optional parameters are omitted, nor whether from/to override or refine the 30-day window.

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 resource and scope: 30-day credit usage for the current key or for the whole account when the key has been claimed. It also specifies that the data splits transcription and server burn. It does not explicitly distinguish itself from sibling tools such as get_balance, so it is clear but not sibling-differentiated.

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

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

The description explains the data scope but gives no explicit guidance on when to use this tool versus get_balance or other sibling tools. The only conditional statement is about account-level scope when the key has been claimed, not about when to invoke the tool.

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

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

Goes well beyond the annotations, which only declare openWorldHint and non-idempotency. The description discloses cost ('Free'), size ceilings tied to Content-Length (2048 MB vs 80 MB), the 422 limit_exceeded code with charged:false, SSRF-style address blocking, and a 30/hour rate limit — exactly the operational facts an agent cannot infer.

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 create_upload equivalence are front-loaded, then constraints in descending importance. Dense but waste-free; the single unbroken paragraph mixes limits, errors, and routing advice, which costs some scannability.

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

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

A mutation tool with no output schema, so the description carries the burden — and it does: return value (fileId), cost semantics, failure modes, and rate limits are all covered. 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 coverage is 50%: url is documented, filename is not. The description compensates richly for url by enumerating accepted link classes (direct http(s), Drive share links with large-file confirm pages handled, Dropbox, OneDrive) and rejected ones. It says nothing about filename, leaving that half of the gap unfilled.

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 a public link into the platform) and immediately anchors the result: 'get a fileId (same as create_upload)'. This lets an agent distinguish it from create_upload, upload_base64, and caption_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?

Explicit when/when-not: use this only to reuse one file across several tools, because 'caption_video accepts sourceUrl directly'. It also names the excluded cases (YouTube/TikTok/Instagram) and prescribes the alternative ('upload the file instead').

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, openWorldHint=false, destructiveHint=false. The description adds real content beyond that: 'Free, no key,' which tells the agent there is no auth or credit cost, plus an inventory of what the payload contains. It stops short of describing response shape, but the 'free, no key' disclosure is genuinely useful non-annotation context.

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

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

It is front-loaded with 'Free, no key,' which is good, but the remainder is a dense run-on: '10 variants with every config field and its default, the bars presets, frame sizes per aspect, and pricing (same as the burn).' Jargon like 'the bars presets' and 'same as the burn' requires rereading. Little fat, but poor parseability.

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 params and no output schema, the description carries the full burden of explaining what comes back. It lists categories of content (variants, defaults, presets, frame sizes, pricing) but not the shape or format of the response, leaving the agent to guess how to consume 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?

The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to disambiguate. The audioVisual and style_preview references describe how to consume the result in other tools, not params here, and they add a small amount of useful connective tissue.

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 never states outright that this tool returns the visualizer catalog. The clearest fragment, '10 variants with every config field and its default, the bars presets, frame sizes per aspect, and pricing,' is a noun phrase with no verb, so purpose is inferred from the name. It does distinguish itself from siblings by naming caption_video, burn_captions, and style_preview, which helps.

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?

'Pass the chosen look as audioVisual' implies you call this first when running caption_video or burn_captions on audio-only input, and 'style_preview with audioVisual shows it free' implies a preview alternative. But neither the workflow nor any exclusion is spelled out explicitly. The agent has to reconstruct the call sequence.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: results are scoped to the key, or to the whole account once the key is claimed, and the operation is free (no credit cost). Only the return shape/pagination is unstated.

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 with no filler, and the scoping rule is stated early. The phrasing is telegrammatic ('Free.') and the missing verb makes it slightly harder to parse than it needs 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?

For a zero-param list tool with no output schema, the agent still doesn't know what a returned preset record looks like or how it differs from custom presets. Annotations carry safety, but the description should have clarified the list-vs-custom-preset distinction.

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

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

Zero parameters, so the baseline is 4. The description does add implicit scoping semantics — results depend on whether the key is claimed — which is useful context even though there is no parameter to document.

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

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

The description names the resource contents (font, color, position, logo) but never states the verb — an agent must infer from the name that this returns a list. It also does not distinguish itself from sibling list_presets, list_custom_presets, or get_custom_preset, which overlap heavily.

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

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

There is no explicit when-to-use guidance and no mention of alternatives. With four preset-related sibling tools (list_presets, list_custom_presets, get_custom_preset, get_style_reference), the absence of routing guidance is a real 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 already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful context beyond them: the call is free, the payload contains the full style JSON, and the review status can be pending/approved/rejected. It doesn't say whether presets are ordered or paginated, a minor gap.

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

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

A single tight sentence with no waste, front-loaded with the cost signal and the resource. The 'Free.' fragment is slightly abrupt but carries real decision value for a paid API.

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 does the work of characterizing the return value (style JSON plus review status) and confirmation that the call is free and argument-free. Only secondary details like list ordering or volume limits are absent, which is acceptable for a simple listing tool.

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

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

Zero parameters, so the baseline is 4; the schema is empty and fully described. The description correctly implies the call needs no inputs, matching the empty object schema.

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

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

States the specific resource (the user's saved custom caption presets) and what is returned (full style JSON plus community review status with enum values). The word 'custom' implicitly separates it from list_brand_presets/list_presets, but it never names those siblings explicitly, so an agent must infer the distinction.

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

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

There is no when-to-use guidance and no mention of alternatives in a cluster of related tools (list_presets, list_brand_presets, get_custom_preset). The only contextual cue is 'Free' and 'Your saved', leaving the agent to reason out that this is the zero-argument listing of user-owned presets.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new behavior — results widen to all account keys when the key is claimed, and the download URL is ephemeral ('while the result is still available'). It says nothing about ordering beyond 'recent' or the pagination model the cursor implies.

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

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

Two sentences, zero waste, with the scope rule front-loaded and the ephemeral-URL caveat second. Nothing is repeated from the title 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 read-only list tool with annotations covering safety and no output schema, the description covers scope and the notable download-URL caveat, but leaves the response shape (job fields, ordering) and all pagination behavior unexplained. Adequate to call, thin on how to page through or interpret results.

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?

Both parameters (limit, cursor) have zero schema description coverage and are never mentioned in the description. An agent gets no default page size, no maximum (100 is only in the schema), and no explanation of cursor semantics or whether 'recent' means a bounded time window — a real gap at 0% coverage.

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 clear verb ('list') plus the resource ('transcription and burn jobs') and even scopes the result set by key ownership. It never names the closest sibling, get_job, so an agent must infer on its own that get_job returns a single job rather than a collection.

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 context ('recent jobs') implies when to call it and the paid-key scope note hints at account-level behavior, but there is no explicit 'use X instead when Y'. In particular, nothing routes the agent to get_job for a specific job's details or status.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered; the description adds genuinely new context: 'Free, works without a key', which tells the agent no authentication is required. It also discloses the return shape including the meaning of safe-zone margins, though it says nothing about result size or ordering.

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

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

Cost/auth information is front-loaded and the usage instruction comes last, so the structure is sensible. The middle sentence is dense with a nested parenthetical about safe-zone margins, which costs some readability but every clause carries information the agent needs.

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

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

With no output schema, the description takes on the job of describing the return fields and does so, and it covers cost, auth, and downstream consumers. What remains unstated (ordering, whether the list is exhaustive) is minor for a small static enumeration tool.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description instead spends its words on the response fields, which is the right allocation for a no-arg tool.

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 (list) and resource (platforms), then enumerates the returned fields (id, name, aliases, expected aspect, safe-zone margins) so the agent knows exactly what the payload contains. It also names the consumer tools (burn_captions, shorts, preview, prepare_client_burn, plan), which separates it from the similarly named list_presets and list_voices siblings.

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

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

It states the concrete trigger: 'Use it to map what the user said ("para Reels", "for YouTube Shorts") to an id', and it identifies which downstream tools accept the resulting value. That gives the agent both the when-to-use condition and the reason the output matters, leaving little to infer.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds non-obvious behavior beyond that: the call is free, results are scoped by API key presence, the returned style document matches what the web editor stores, and fonts are returned as a side output. Only the exact response shape/pagination is left unstated.

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 cost ('Free.') and the three result categories, then adds the handoff to save_custom_preset and the fonts note. Dense but every clause carries information; the parenthetical 'source custom, id custom:cp_...' is slightly jargon-heavy but functional.

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, so the description must convey returns — and it does describe three preset categories, the style-document format, the id convention, and the fonts collection. Complete enough to invoke correctly; only finer details (ordering, pagination, per-preset fields) remain unstated, which is acceptable for a zero-param read tool.

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

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

With zero declared parameters the baseline is 4, and the description adds relevant semantic context by explaining that output contents depend on whether the caller supplies a key. No invented parameters or misleading nomenclature.

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 set: it lists built-in, community-approved, and (key-dependent) custom presets, plus bundled font families. That is clear and more specific than the title. It never mentions the sibling tools list_custom_presets / list_brand_presets, which overlap with the custom/brand preset portion, so the agent has to infer the distinction.

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 usage context: copy a returned style JSON 'as a starting point for save_custom_preset', and notes that custom presets only appear 'with a key'. It stops short of stating when to prefer this over list_custom_presets or list_brand_presets, so routing among near-duplicate siblings is left implicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that with pricing semantics (basic 5 credits/min, standard 12), the keyless/free call model, and the purpose of sampleUrl for auditioning before choosing.

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 dense sentences: cost/free access first, then the catalog fields, then filtering and downstream use. Nothing is repeated from the schema and every clause adds information.

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

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

With no output schema, the description fully documents the return shape, and it also covers the default-voice behavior and pricing relevant to choosing a voice. Nothing an agent needs to select or call this tool correctly is missing.

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

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

Schema coverage is 0%, so the description must carry the parameter burden, and it does: language is specified as ISO 639-1, and the tier enum values are qualified with their credit cost. Only the absence of examples or default-filter behavior keeps it from 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?

The description names a specific resource (the dub voice catalog) and enumerates the exact fields returned (id, language, tier, provider, gender, default, creditsPerMinute, sampleUrl), which cleanly separates it from siblings like list_presets or list_custom_presets. An agent knows precisely what it gets back before calling.

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 downstream guidance: 'Pass an id as voice to dub or plan; omit voice for the default,' and states the tool is free and keyless. It doesn't explicitly name a contrasting sibling it should be preferred over, which keeps it 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 readOnly/idempotent annotations: no key required, no charge, no download (mediaUrl is HEAD-only), auto-inserted transcribe/translate steps, and unsupported dub languages surfacing in limitViolations rather than erroring. The only ambiguity is what happens when the plan itself is unusable — it implies violation reporting but doesn't say if the call still succeeds.

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 free/no-key/no-charge constraint is correctly front-loaded, and little is pure filler, but the steps sentence is a single 60-word clause pile that is hard to scan. A short bulleted op-to-parameter mapping would carry the same content with far less parsing cost.

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, yet the description enumerates the return shape well (steps with credits, totalCredits, totalUsd, freeAlternatives, feasible, limitViolations with code/limit/actual/unit/message/hint) and the balance behavior when a key is present. Completeness is only dented by the unmentioned voice parameter and style_preview op.

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 burden and mostly does: it maps sub-parameters to ops (count/minSeconds/maxSeconds/reframe for shorts, keepSeconds for trim, renderer for burn, targetLanguage/voiceTier/sourceLanguage for dub) and explains source.durationSeconds/bytes/via/transcriptCues/mediaUrl plus hasTranscript/hasTranslation. Gaps remain: the 'voice' string parameter and the 'style_preview' op appear in the schema but are 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: 'Price a whole pipeline before running it and check it against the limits.' Immediately distinguishes itself from the execution siblings (caption_video, burn_captions, dub) by being the dry-run cost/feasibility check, and the opening 'Free, works without a key, never charges' reinforces that it is non-executing.

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 about the timing: price before running, and the note that 'Paid tools return limit_exceeded with the same violations before charging' tells the agent what this buys them. It does not name the nearest alternative (quote or batch), so the agent must infer which of the two pricing paths applies.

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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: zero cost, nothing debited, ffmpeg never started, and it is a seam for a future client-side renderer. It stops short of describing what comes back (raw script text vs. a reference/URL) or whether a job/ID is created.

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 sentences, front-loaded with the artifact and the zero-cost guarantee before the renderer rationale. The "seam for a future WebMCP renderer" sentence is useful positioning but is the weakest use of space relative to the missing return-value information.

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

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

For a 13-parameter tool with a nested styleOverrides object and no output schema, the description leaves the response shape undefined — an agent cannot tell whether it receives the ASS text, a file reference, or a job id. Cost and no-ffmpeg behavior are well covered, so it is adequate but with a clear gap.

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

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

Schema coverage is only 46%, but the description compensates on the two axes that matter: the subtitle source (inline subtitles vs. transcriptionJobId) and the preset reference (id or name), plus the undocumented PlayRes default of 1280x720 for width/height. It does not clarify whether any of the 13 params are required or how the id/name pairs interact on conflict.

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?

"Build an ASS subtitle script from an AwesomeVideo preset without starting ffmpeg" gives a specific verb and artifact, and the ffmpeg/cost framing implicitly separates it from the server-render sibling (burn_captions). The sibling is never named, so an agent still has to infer which tool does the actual burn.

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 says what to pass (subtitles or transcriptionJobId plus preset id or name) and hints at the client-side/browser use case, which implies when to prefer it. There is no explicit "use X instead when you want server-side rendering" exclusion, and no note about the mutually exclusive parameter combinations an agent must choose between.

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

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

Annotations already declare non-destructive, idempotent, open-world behavior, but they say nothing about cost. The description fills that gap precisely: flat price, at most 1 credit by default, and explicitly not billing full media duration, plus the 5-second clip cap. It still omits whether the call is synchronous or returns a job to poll, which is a real gap given the get_job/resume_job siblings.

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, output form and price front-loaded, no filler. The opening is a sentence fragment with no verb, which slightly undercuts the front-loading, but every sentence contributes information.

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

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

For a 17-parameter rendering tool with no output schema, the description is far too thin. It does not describe what is returned (asset URL? job id?), whether the result must be polled, how the two input modes (fileId vs mediaUrl) differ, or how a preset is chosen without knowing presetId semantics.

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 17 parameters and only 41% schema description coverage, the description carries a heavy compensation burden but adds meaning for only two things: the preset selection and the 5-second cap on clipSeconds. It says nothing about mode, fileId vs mediaUrl, platform, atSeconds, maxCredits, or transcriptionJobId, so more than half the surface is undocumented in both places.

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

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

The description names the output artifact (a still PNG or a ≤5s clip rendered with the chosen preset) but never states a verb or what it operates on (a video via fileId/mediaUrl). Against siblings like style_preview and burn_captions it does not explain how this preview differs from those, so an agent must infer the distinction from the name alone.

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

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

There is no explicit when-to-use statement, no prerequisites, and no named alternative. The presence of style_preview and burn_captions in the sibling list makes the omission costly: the agent is left to guess whether 'preview' is a cheap pre-render check or a styling dry run.

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 say readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses that nothing is charged, that it works unauthenticated in one mode, that duration is probed from media in the other, per-operation pricing units, and the caveat that a trim media quote is an upper bound. These are exactly the behavioral facts an agent needs before calling a pricing 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?

Front-loaded with the single most important fact ('Free'), then prerequisites, then a per-operation rate table. Dense but every clause carries pricing or invocation information; the semicolon-chained rate list is harder to scan than it could be but nothing is 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?

Seven parameters, no output schema, and the description does explain the unit of the return value (cents/credits) plus that dub quotes include a breakdown. It stops short of describing the general response shape or what an unknown/failed probe returns, which matters given the media-probing mode.

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 only 43% schema description coverage, the description carries most of the burden and mostly does: it explains the durationSeconds vs fileId/mediaUrl tradeoff, ties voiceTier to dub (basic vs standard), translateTo to caption, and targetLanguage to dub. Gap: the enum value 'style_preview' is present in the schema but never mentioned, and fileId vs mediaUrl is not distinguished from each other.

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?

Opens with a specific, unambiguous statement of what the tool does: returns cents/credits a job would cost without charging. That distinguishes it from the execution siblings (caption_video, dub, transcribe) which actually spend credits. It never names the potentially confusable sibling 'plan', so differentiation from that one is left to inference.

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 invocation contexts: no key needed if you pass operation + durationSeconds, keyed usage allows fileId or mediaUrl with duration probed automatically. That is real when/how guidance. It does not state when to prefer this over plan or when a quote is unnecessary (e.g., already knowing the rate), so no explicit exclusions.

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

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

Beyond the annotations, the description discloses pricing and billing basis, returned outputs and stats, the transcript requirement, fade-on-cut behavior, and how optional caption burning reuses the burn_captions renderer. These are material behavioral details for a paid media-processing 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?

The description is dense but front-loads cost, output, and transcript requirements before moving into silence and filler mechanics. The length is largely justified by 24 parameters, though the long single block could be easier to scan with clearer segmentation.

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 24-parameter tool with no output schema, the description is sufficiently complete: it enumerates the return artifacts and stats, states the transcript requirement, explains billing, and covers the main processing modes. Remaining gaps are covered by schema descriptions.

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 coverage at 63%, the description compensates substantially by explaining defaults and effects for silenceGapSeconds, paddingSeconds, silenceNoiseDb, fillerMode, fillers/keepFillers/removeFillers, burnCaptions, transcriptionJobId, and subtitles. It leaves source selection (fileId/mediaUrl), maxCredits, quoteOnly, highlightWords, faceAvoid, and styleOverrides mostly to the schema, so it is strong but not complete.

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: removes silences and filler words from a talking video. It distinguishes itself from burn_captions by making caption burning optional and by requiring a transcript, and it names the returned artifacts, so 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?

It clearly states the transcript prerequisite (transcriptionJobId from transcribe or caption_video, or subtitles) and explains several behavioral switches such as detectSilences:false, removeFillers:false, and fillerMode 'aggressive'. It does not explicitly compare the tool against trim or burn_captions for adjacent use cases, which keeps it from 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 far beyond the annotations: discloses the cost model (free review and waiting, charge only on approve at 4 credits/min, same as burn_captions), link constraints (private, up to 7 days, no login, scoped to one video), the reviewer's capabilities (edit text/timing, approve/reject with note, add glossary terms), and event semantics (review.approved/review.rejected/review.expired delivered once each, plus job.succeeded). Nothing here contradicts readOnlyHint=false / destructiveHint=false.

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?

High information density with no filler — price, trigger, mechanics, and follow-up path are all load-bearing. The one knock is structure: everything is packed into a single run-on paragraph mixing pricing, link properties, and event semantics, so an agent must parse rather than scan.

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 15-parameter, no-output-schema tool that gates a paid, irreversible burn behind a human approval, the description supplies everything needed: required input provenance, the returned reviewUrl, how to await the outcome, and what triggers the charge. No output schema is needed because the return value and event names are spelled out.

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

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

Schema coverage is already 87%, so the schema carries most weight, but the description adds real meaning: transcriptionJobId must be a finished transcribe job, preset/brandPresetId govern the burn after approval, webhookUrl/notifyEmail bind to the named events, and the 7-day link lifetime clarifies expiresInDays. It doesn't touch maxCredits, autoFit, styleOverrides, or highlightWords specifics, which the schema handles well.

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: it creates a human review gate over captions before a burn, returning a reviewUrl. It explicitly separates itself from burn_captions ('Only on Approve does burn_captions run') and from get_review (polling status), so an agent can pick 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?

States the trigger condition ('when the person wants to check the captions before they are burned') with multilingual example phrasings, and names the alternatives: burn_captions for the unconditional path, get_review / webhookUrl / notifyEmail for tracking the outcome. When-to-use and when-to-use-something-else are both explicit.

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

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

Goes far beyond the annotations: it discloses chunk-level billing (1 credit/min, only missing 30s chunks charged), that a finished transcript/translation is reused so caption_video usually only pays the 4 credits/min burn, that the failed job stays fully refunded, and that calls are idempotent with no second charge (confirming idempotentHint). It also names the error codes and whether they are charged, which an agent cannot infer from structured fields.

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

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

The purpose and resumable-job list are front-loaded, and the pricing/idempotency/error details follow in a logical sequence. The no_speech parenthetical is quite dense and slightly over-elaborate, but nearly every sentence carries actionable information.

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

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

Covers the return value indirectly ('Returns a new job id; poll get_job'), error codes, billing implications, and idempotency despite no output schema. The remaining gap is the unexplained webhookUrl/notifyEmail parameters, which is minor given the overall richness.

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 50%: jobId and maxCredits are documented in the schema, while webhookUrl and notifyEmail are undocumented in both places. The description adds an example call and enough billing context to make maxCredits meaningful, but it never explains the webhook/email parameters, so it only partially compensates 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?

States a specific verb ('Restart') and resource ('a failed job'), enumerates exactly which job types are resumable (caption_video, transcribe, create_clips, dub_video, trim/remove_silences, generate_metadata), and clearly differs from siblings like get_job or caption_video. An agent can immediately tell this is the recovery path, not the creation path.

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

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

Explicit when-to-use (a failed job) plus concrete routing for edge cases: 422 resume_not_supported/resume_media_expired means call the original tool again, and 409 job_not_resumable with reason no_speech explains that a resume would reproduce the same failure. These are genuine alternatives, not vague hints.

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

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

Annotations declare readOnlyHint=true, yet the description describes storing user-supplied data ('Save a font... optional logoBase64'), which is a persistent write. An agent reading both gets conflicting signals about whether the call mutates state. The title annotation ('Prepare client burn') also does not match the described behavior, compounding the confusion.

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?

Everything is packed into two sentences with no filler — the allowed-values list and the follow-up call are both actionable. The opening is field-enumeration rather than a scope statement, so it is dense but slightly back-loaded on the 'what am I creating' question.

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 should say what comes back; it only implies a brandPresetId exists by telling the caller to pass it onward. The required `name` field and any overwrite/idempotency behavior (what happens when saving a preset with an existing name) are absent, which matters for a tool whose annotations are already unreliable.

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 has to carry the load, and it does well: it lists the permitted font family values, the #RRGGBB color format, the three position values, and the accepted image encodings for logoBase64. The one gap is the required `name` parameter, which is never mentioned anywhere, leaving the caller to infer it.

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 enumerates exactly what gets stored (font, #RRGGBB color, position, optional logo) and names the downstream consumers (burn_captions, preview), so an agent knows the resource being created. It never states the noun directly — 'Save brand preset' is only implied by the name/title — and it never distinguishes itself from the sibling save_custom_preset, which is the main ambiguity.

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?

'Free. Pass brandPresetId to burn_captions or preview.' gives concrete downstream usage and cost, which is real guidance. But there is no statement of when to pick this over save_custom_preset, whether a preset must exist before burn_captions, or how to inspect saved presets (list_brand_presets).

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 unambiguously describes a persistent write ('save your own full caption preset', 50-preset / 20 KB quotas, private-until-submitted state), but the annotations declare readOnlyHint=true and carry a title copied from another tool ('Prepare client burn'). An agent trusting the annotation would treat this as a non-mutating read, which is the opposite of the described 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 cost ('Free.') and the core action, then packed with actionable detail; almost every sentence carries a constraint or routing hint. It is dense and run-on rather than wasteful, so only lightly penalized for readability.

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 return value (id custom:cp_... and where to pass it), error behavior, quotas, privacy state, and a validation workflow — strong for a 5-param tool with no output schema. Gaps remain around the required `name` field and the `description` field's purpose.

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?

Adds real meaning beyond the schema: overrides are deep-merged and 'null removes a field', basePreset accepts id/slug/name/custom:cp_ forms, and invalid styles return 422 invalid_style with [{path, message}]. The required `name` and the optional `description` parameters are never explained, keeping it from 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 ('Design and save your own full caption preset') and scopes it to 'this key (or the account when the key is claimed)'. It is distinguishable from sibling mutations like update_custom_preset, save_brand_preset and submit_custom_preset 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?

Explicitly describes the two calling modes (pass a full `style`, or `basePreset` plus `overrides`), names the lifecycle step ('Private until you call submit_custom_preset'), and routes the agent to prerequisites: get_style_reference, validate_preset_style, and preview before a paid burn.

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

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

Annotations already declare this is non-read-only, idempotent, non-destructive, and closed-world. The description adds useful behavior beyond that: it is 'Free', merges by term unless mode is replace, replaces aliases word-for-word, and enforces limits of 'Up to 200 terms, 10 aliases each.' It leaves the full effect of mode=replace somewhat ambiguous.

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 'Free. Save...' and packs useful examples and limits into one paragraph. It is dense but mostly earns its length, though the parenthetical example about term 'po' aliases ['pues'] is slightly distracting.

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 nested glossary-save operation with no output schema, the description covers purpose, merge/replace behavior, alias handling, doNotTranslate, and size limits. It is not fully complete because note is undocumented and replace-mode semantics are not fully spelled out.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does for term, aliases, doNotTranslate, and mode with examples and limits. The optional note field is not explained in the description, and field length limits are left entirely to the schema.

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

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

The description gives a specific verb and resource: 'Save brand names, product names, people, slang and dialect spellings' so future transcriptions recognize them. It clearly distinguishes saving glossary entries from retrieving or deleting them through the action and examples, though it never names a sibling tool explicitly.

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

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

The use case is clear: save terms 'so future transcriptions get them right.' It gives a strong positive context but does not explicitly say when not to use this tool or name alternatives such as get_glossary or delete_glossary.

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: pricing (6 credits per source minute), reframe fallback behavior (face → center), platform safe zones, clip length constraints with error codes (422 limit_exceeded), and balance errors with checkoutUrl (402 insufficient_balance). These details are critical for an agent to predict costs and handle failures.

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 well-structured and each sentence generally earns its place by conveying pricing, behavior, or constraints. It is slightly front-loaded with pricing rather than the core action, but overall it remains efficient and scannable.

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

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

Given the tool's complexity (16 parameters, multiple options, no output schema), the description covers most essential aspects: core action, pricing, error conditions, reframe behavior, and platform handling. It omits guidance on when to use versus alternatives, but that is addressed in usage guidelines; overall it is fairly complete for correct invocation.

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

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

Schema description coverage is 63%, so some parameters are already documented. The description adds meaning for reframe (face fallback), platform (example mapping 'shorts para Reels'), and min/max seconds (error behavior). However, it does not compensate for undocumented parameters like fileId, preset, mediaUrl, subtitles, and transcriptionJobId, leaving gaps.

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: 'Pick 1-5 non-overlapping moments from a transcript, reframe each to 720x1280 (9:16), and burn captions.' This clearly distinguishes the tool from siblings like burn_captions or create_clips by combining moment selection, reframing, and caption burning into a single 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?

The description provides no explicit guidance on when to use this tool versus alternatives like create_clips or burn_captions. It implies usage through phrases like 'Pick 1-5 non-overlapping moments from a transcript,' but does not name or exclude any sibling tool or state conditions for selection.

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 say readOnly/idempotent/non-destructive; the description adds cost behavior (FREE, never charges, no transcription), rate limits with the exact error code and retryAfterSeconds, cache semantics for repeats, and the audioVisual 422-not-charged case. It also discloses fidelity details: rendering uses the burn's engine, output size, safe zone and words-per-caption, and fullText deliberately does not match a burn.

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 two things that matter (FREE, use before caption_video), and nearly every sentence carries information. However it is one dense paragraph that interleaves routing, rendering internals, return shape and rate limits, which makes it harder to scan than it needs 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?

No output schema exists, yet returns are named (sheetUrl, per-preset frames[], captionVideoArgs) and the passthrough contract is spelled out. Combined with limits, defaults and error codes, an agent has everything needed to call it correctly on the first attempt.

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 20 params and only 60% schema coverage, the description carries real weight: it explains atSeconds as one second or up to 3 (one sheet row each) with the default frame heuristic (a face, else the middle), the 80-char sample phrase and its language default, truncated vs fullText, and that the look fields mirror caption_video. It also documents the return contract (captionVideoArgs) needed to chain into the burn.

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 (renders each caption preset into a labeled contact sheet) and immediately draws the boundary against caption_video, which is the nearest sibling. An agent can tell from the first sentence that this is a non-charging preview, not the actual burn.

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 BEFORE caption_video whenever the person wants to see or choose how captions will look', reinforced with example user phrasings including Spanish. It also names the escalation path ('pass that object unchanged to caption_video') and the alternate input path when a transcript already exists.

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: free/no credits, pending state, human moderation with no automatic approval, and a hard rate limit of 5 submissions per day. The annotations only flag readOnly=false and non-idempotent, so this lifecycle and quota detail 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?

Four tight sentences, front-loaded with the cost ('Free.') and then the action, moderation outcome, rate limit, and status-check route. No filler.

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

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

For a non-idempotent write with openWorldHint, the description covers cost, moderation, quota, and result verification, which is what an agent most needs before calling. The remaining gap is the undocumented submission fields (id, tags, previewText).

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?

Five parameters with only 20% schema description coverage, and the description says nothing about id, tags, description, or previewText limits. Only 'author' is documented, and that is in the schema, not the description, so the description 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?

States a specific verb (propose/submit) plus the exact resource (one of your custom presets) and destination (public AwesomeVideo community gallery). The name and title could be confused with save_custom_preset or update_custom_preset, but the description makes the distinct publish-to-community action 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?

Gives clear context: the submission goes to a human moderator and only shows in list_presets after approval, with a pointer to get_custom_preset (community.status) for follow-up. It never explicitly says to create the preset first with save_custom_preset, so the precondition 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?

Goes well beyond the annotations: discloses that audio is extracted and downsampled to 16 kHz mono while video frames are not decoded, that this is a prepaid operation, the exact 402 insufficient_balance payload fields and that no job starts, and that cache hits are keyed by API key plus language/format/duration hint with cross-key isolation. This is exactly the operational 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 model and processing behavior, then billing, then failure payload, then caching, with no filler sentences. Every clause (downsampling, 402 fields, cache key scoping) carries decision-relevant information.

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

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

Covers inputs, processing, pricing, failure mode, and caching for a 10-parameter tool with no output schema. The notable gap is execution model: the presence of webhookUrl and a get_job sibling implies asynchronous job submission, but the description never says whether the call returns a job id to poll or a result synchronously.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds value by reinforcing the mediaUrl-vs-fileId choice, the auto language default, and format output content, and by tying language, format, and the duration hint to cache scoping. It does not explain glossary vs useSavedGlossary or maxCredits semantics, keeping it from 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 plus the exact model ('Transcribe speech with Workers AI Whisper @cf/openai/whisper-large-v3-turbo') and the accepted input forms (media URL or uploaded file id). It is distinguishable from caption_video/burn_captions, but it never explicitly names those siblings to route the agent, 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?

Offers input guidance ('Pass a media URL or an uploaded file id') and default behaviors ('Language defaults to auto'), which implies when the tool applies. However there is no explicit when-to-use / when-not-to-use statement and no comparison to caption_video, burn_captions, or dub, which produce overlapping subtitle output.

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?

Strong on cost and side effects: 2 credits/min, +4 credits/min for burn, cue timing preserved, word-level highlight dropped, and burn requires media+preset — all beyond what the annotations declare. However the annotations' title is "Transcribe" while the tool and description are about translation, which creates a mild signal conflict the description never resolves, and failure/partial-failure behavior is not described.

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?

Cost is front-loaded, then inputs, then outputs, then the burn variant — a sensible order with no filler. The burn clause is compressed to near-telegraphic style ('needs media plus a preset'), which is efficient but slightly terse for a param with extra requirements.

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 13-param paid mutation with no output schema, it covers price, inputs, preserved/removed output traits, and return formats (SRT, VTT, JSON). Remaining gaps are secondary params and behavior on invalid input or partial failure, which are not blocking for a correct 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 only 38% across 13 params, so the description must compensate, and it only meaningfully explains transcriptionJobId/subtitles, burn, and indirectly mediaUrl/preset. Parameters like sourceLanguage, maxCredits, fileId, faceAvoid, highlightWords, and styleOverrides are left entirely to the schema.

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

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

States a specific verb+resource (translate captions) plus the exact input modes (transcriptionJobId or subtitles) and the engine (Workers AI m2m100). An agent can distinguish this from transcribe, dub, and burn_captions without opening the schema.

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

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

Gives concrete routing conditions: pick transcriptionJobId or subtitles as the source, and burn:true requires media plus a preset. It does not explicitly say when to prefer this over the sibling burn_captions or dub, so the alternative-selection guidance is implied rather than stated.

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

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

Goes well past the annotations: pricing (3 credits per kept minute, +4 with burnCaptions), that billing is on kept duration, exactly what gets cut and with what defaults, how cuts are joined (audio fade so joins do not click), and the full output shape. The annotations only cover safety/idempotency, so this added context is doing real work.

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?

Dense but nearly every clause carries operational information; nothing is filler. The ordering is slightly off — the actual purpose sentence arrives third, after the alias and the pricing paragraph — so a scanning agent meets cost before function.

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 24-parameter, no-output-schema mutation with an open-world job submission, the description covers the missing pieces an agent needs: the transcript prerequisite, the exact stats returned, cost model, and the optionality of the caption burn. No output schema is a gap the description closes inline.

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?

At 63% schema coverage the description compensates well, defining the semantics that the schema does not: fillerMode 'clear' vs 'aggressive' word lists, fillers/keepFillers/removeFillers interaction, detectSilences being an ffmpeg silencedetect pass inside word timings, and the burnCaptions style cluster. Several of the 24 parameters (maxCredits, highlightWords, faceAvoid, styleOverrides, quoteOnly) are left to the schema, and some defaults it repeats verbatim from schema fields.

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 (removes silences and filler words from a talking video) and immediately anchors it as an alias of remove_silences, then names the return artifacts. The burn_captions renderer cross-reference disambiguates the caption-burn path from the sibling burn_captions 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?

Explicitly states the prerequisite (needs a transcript via transcriptionJobId from transcribe or caption_video, or subtitles), and names when the caption-burn branch routes through the same renderer as burn_captions. It does not, however, say when to prefer trim over remove_silences, or when to use quoteOnly/preview instead of starting the job.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, yet the description describes mutating operations ("Rename, re-describe, or restyle", "style replaces the whole document"). That is a direct conflict between the stated behavior and the structured safety hints, and the annotation title "Prepare client burn" does not even match this tool. The rich detail about style replacement, override merging, and community-copy snapshots is otherwise valuable, but the contradiction dominates.

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

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

Four short sentences, front-loaded with the cost signal "Free." and the operation scope, then the style-vs-overrides merge rule. Nothing is padded, though deferring validation semantics to "Validated like save_custom_preset" forces a cross-tool lookup.

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

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

Given six parameters, nested objects, no output schema, and effectively unreliable annotations, the description still supplies the core behavioral model an agent needs (replace vs deep-merge, basePreset fallback, immutable community snapshots). It stops short of describing error cases for an unknown id or the response shape, but those are secondary for a preset mutation.

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 whole burden and does so for the hardest parameters: style ("replaces the whole document"), overrides ("deep-merge onto the current style (or onto basePreset when given)"), basePreset, plus name/description via rename/re-describe. Only id is left unexplained, and the validation rules are deferred to save_custom_preset rather than spelled out.

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?

"Rename, re-describe, or restyle a saved custom preset" gives a specific set of verbs plus the resource, so the agent immediately knows this mutates an existing preset rather than creating one. It distinguishes itself implicitly from save_custom_preset by referencing it as the validation counterpart, but never names the create/delete/submit siblings outright.

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

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

Usage context is implied by "a saved custom preset" (i.e., the preset must already exist) and by "Validated like save_custom_preset" for the rule set, but the description never states when to choose this over save_custom_preset, submit_custom_preset, or delete_custom_preset. There are no explicit preconditions or exclusions, so the agent must infer the branch.

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 by disclosing cost ('Free'), the 10 MB size ceiling, the exact failure mode (422 limit_exceeded with charged:false), and a rate limit of 30/hour. Annotations only carry the generic safety hints, so these operational details are 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.