AutoShort

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

Annotations declare idempotent/readOnly=false/destructive=false, and the description adds substantive context beyond them: off-session charging against a saved card, the 202 async response, the follow-up poll via autoshort_get_credit_balance, and the guarantee that a repeated idempotencyKey never double-charges.

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 action and preconditions, then idempotency, then return/polling behavior, then the alternative. No filler.

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

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

No output schema exists, and the description covers the async return code plus the polling tool needed to resolve the outcome, and the fallback path. An agent has everything required to invoke and follow up correctly.

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

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

Schema coverage is 100% and the single parameter is already documented. The description still reinforces the idempotencyKey contract ('same idempotencyKey never charges twice'), linking the parameter to observable behavior rather than just restating the schema.

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

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

States a specific verb and resource ('Buy the owner-approved credit pack on their saved card, off-session') with the exact preconditions. It is clearly distinguishable from autoshort_get_buy_credits_url, which it names as the non-auto-recharge 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 gates: only when auto-recharge is ACTIVE and within its monthly cap. It also names the alternative for the negative case ('Without auto-recharge use autoshort_get_buy_credits_url'), so the routing decision is fully specified.

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: explains the refund goes through the credit ledger net of earlier refunds and is never paid twice (concretizing idempotentHint), that the video will never render later, the exact refusal code, and that the operation costs nothing. Nothing here contradicts destructiveHint=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?

Three tight sentences: eligibility first, refund semantics second, refusal/cost caveats last. Every clause carries information an agent needs and nothing repeats the annotations verbatim.

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-param mutation with no output schema, it covers eligibility, refund behavior, refusal modes, and cost — enough to call it correctly. It doesn't say what the response contains (refunded amount, resulting balance), which would close the last gap.

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

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

The single parameter videoId has 0% schema description coverage, and the description never explains it directly — it only implies which video via the cancel semantics. The meaning is inferable from the tool scope, but no ownership, format, or lookup guidance is added.

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 ('Cancel a video') and immediately narrows the scope to statuses PENDING or DRAFT. It also separates this tool from adjacent flows by noting that operator-fulfilled clips cannot be cancelled, so an agent can tell it apart from render/update/delete 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?

Explicitly says when to use it (video not yet rendering) and when it will fail (rendering started → CANNOT_CANCEL_STARTED; operator-fulfilled clips). No sibling alternative is named, but there is no obvious competing cancel path, so the guidance is close to complete.

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

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

Far exceeds the annotations (which only say idempotent, non-destructive, open-world). The description discloses cost behavior (credits held at start, refunded for unanimated shots, full refund on failure), the 409 price-change guard that charges nothing, runtime of 10-25 minutes with polling guidance, and concurrency/quota limits. This is exactly the operational context an agent needs before a paid, long-running mutation.

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 highest-value facts — cost, prerequisites, quote-first — before secondary details, and every sentence carries non-obvious information. The density is achieved with comma splices and em-dash-free run-ons, which makes it slightly harder to parse than it needs to be, but nothing is wasted.

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

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

For a 12-parameter, credit-charging, 10-25 minute async job with no output schema, the description covers everything an agent must know: what it returns (an id), how to retrieve the result (autoshort_get_video with {id: <returned id/videoId>, reporting status, stage, videoUrl}), how failures resolve financially, and how to avoid duplicate charges. Nothing material is missing.

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

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

Schema coverage is 100%, so the schema already documents every field, which sets the baseline at 3. The description goes beyond it by tying parameters to workflow semantics: confirm+expectedCredits must match the quoted price or the call 409s, idempotencyKey prevents double-charging on retry, and plan-derived values (voice, language, style, look, outfit) mean most optional params should be omitted. That cross-parameter coupling is added meaning, though it does not restate the shots-vs-script tradeoff itself.

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 ('Make the episode') and immediately constrains scope: 3-8 shots, 30-60 seconds, one recurring character, narrated captions. Sibling routing is implicit but clear — autoshort_quote_character_episode is named as the mandatory prior step, and the episode-creation boundary against autoshort_generate_video / autoshort_draft_video is legible from the season-plan requirement.

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 explicit preconditions (season plan REVIEWED + CONFIRMED, episode must match the plan), the mandatory quote-then-confirm sequence, and the exact error codes returned when preconditions fail (SEASON_PLAN_REQUIRED / SEASON_NOT_REVIEWED / EPISODE_NOT_IN_PLAN). Also names the alternative completion paths — poll autoshort_get_video with the exact argument shape, or use a webhook — and the rate limits (one at a time per account, 3 per day).

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: states credit price by subject type, that credits are captured upfront and fully refunded on failure, partial-success behavior with `partial: true` and `missingViews`, partial charging with `creditsCharged`, typical latency, face-consistency behavior across views, and content-policy rejections with no charge. The annotation profile (not read-only, idempotent, open-world) is consistent with this and the description supplies the operational detail annotations cannot.

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

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

Front-loads the purpose, output shape and price before costs and edge cases, and nearly every sentence carries distinct information. It is dense to the point of being a single breathless block, so a small amount of structural separation would improve 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?

With no output schema, the description fully compensates by describing the return payload (`partial`, `missingViews`, `creditsCharged`, images included inline), failure modes, and the refund rule. An agent has everything needed to call it, set expectations with the user, and interpret the result.

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 adds real meaning by tying `subjectKind` to pricing (21 vs 10 credits) and to view-consistency behavior, explaining the default of 5 for `imageCount`, and justifying `idempotencyKey` as retry protection. It does not explain the `description` field's 8-400 char constraints, but the schema already does.

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 ('Make a character sheet for one of your series') plus the exact output ('4-6 AI images ... of ONE fictional character, from a text description'). The 'ONE character' emphasis and the enumeration of views distinguish it cleanly from sibling tools like autoshort_create_character_episode and autoshort_select_character_image.

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

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

Gives an explicit prerequisite ('call autoshort_get_character_sheet first and tell the user'), a hard quota ('A series can hold 3 sheets in total; the first sheet is chosen automatically'), and a clear exclusion list of rejected inputs. It does not, however, contrast itself with the adjacent episode-generation sibling, leaving that routing 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?

Adds substantial behavior beyond the annotations: creating/editing a series is free, billing happens per video at render time, an insufficient balance skips the run rather than failing or overdrawing, scheduled videos count against the key's daily agent spending cap, and TikTok auto-post lands in Drafts. These are exactly the side effects and constraints an agent needs before invoking a mutating, non-idempotent 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-loads what the tool does before the cost and scheduling details, and nearly every clause carries decision-relevant information. It is a single dense block though; splitting the billing/scheduling rules from the parameter guidance would make it easier to 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 13-parameter creation tool with no output schema, it covers the costly and risky behaviors (billing, caps, pause, auto-post prerequisites) well. It does not say what the call returns (presumably a series object/id) or tie that to the follow-up tools, and leaves quality/name unguidanced.

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 69% schema coverage across 13 params, the description adds real meaning where the schema is thin — brief is 'the user's own words the generator writes from', and startPaused ties to resume. However, name, quality (HD_720 vs FULL_HD_1080), and autoPostYouTube carry no explanation in either place, and the interval default is only restated from 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?

Opens with a specific verb+resource ("Create a series") and immediately defines what a series does: makes a video on the niche/brief every scheduleIntervalDays and can auto-post. The scope is unambiguous versus one-off generators. It stops short of naming a sibling such as autoshort_update_series or autoshort_generate_video to sharpen the create-vs-modify choice.

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 conditional guidance: use startPaused:true to create without generating and resume with autoshort_resume_series; auto-post requires the platform connected (autoshort_get_connection_status); per-day caps are visible via autoshort_get_limits. It never explicitly contrasts this with a single-video tool like autoshort_generate_video, so the key alternative 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?

Goes well beyond the annotations: discloses the signing secret is returned only once, the exact HMAC-SHA256 signature header and format, that private/internal addresses are refused, the 10-per-account cap, free pricing, and ~1 minute delivery latency. These are non-obvious operational facts an agent cannot infer from readOnly/openWorld/idempotent hints.

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

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

Three dense sentences with zero filler; the primary action and trigger come first, followed by return/verification semantics, then constraints. Every clause 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?

With no output schema, the description fully covers the return value (secret once) and verification procedure, plus constraints and latency. An agent has everything needed to call and handle the result 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 67%, and the description compensates by explaining that the url must be public with private/internal addresses refused, plus the account cap constraint. It also names the two event values, though the events parameter's default and wildcard are already covered by 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 (register a webhook URL) and the exact triggers (video.completed / video.failed) with delivery mechanism. An agent can distinguish it from autoshort_list_webhooks and autoshort_delete_webhook without opening a schema.

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

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

Explicitly frames the use case as an alternative to polling ('instead of polling'), which tells the agent when this is the right call. It does not explicitly route away from siblings (e.g., use delete_webhook to remove), 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?

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered; the description adds genuine value on top by naming the immediate effect on deliveries and stating the call is free (no credit cost). It does not, however, say whether deleting an unknown webhookId errors or is a no-op, which matters for an idempotent, destructive 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?

Two short, front-loaded clauses with zero filler; the highest-value fact (deliveries stop immediately) appears before the secondary billing note.

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 deletion tool whose annotations already carry destructiveness and idempotency, and with no output schema to explain, the description covers purpose, consequence, and cost adequately. The remaining gap is how to source the webhookId and the behavior on a missing id.

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 parameter 'webhookId' is completely unmentioned in the description. The name is largely self-explanatory, but the description does nothing to compensate for the missing schema documentation — e.g., it does not say where to obtain the id (autoshort_list_webhooks) or the accepted 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 verb and resource ('Delete a webhook') and immediately adds the operational consequence ('deliveries to it stop immediately'), which cleanly separates it from sibling autoshort_create_webhook and autoshort_list_webhooks.

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

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

There is no guidance on when to use this versus alternatives, nor any preconditions (e.g., whether the webhook must exist, whether deletion is reversible, whether subscriptions/billing are affected). The only signal is the implied usage from the tool name.

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

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

Annotations only declare the generic profile (not read-only, idempotent, non-destructive). The description adds real operational context beyond that: the effect is immediate, reversal is gated on owner approval, and the call is free. Slight ambiguity in 'autoshort_buy_credits stops charging' — unclear whether that means the sibling tool becomes unusable or simply that no charges accrue.

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

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

Three short clauses, front-loaded with the action and its immediacy. The middle clause about buy_credits is the weakest link — its phrasing is ambiguous, so it does not fully earn 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 parameterless toggle with no output schema, the description covers the key facts an agent needs: what changes, that reversal requires owner approval, and that it costs nothing. What is missing is the explicit pointer to the tool that re-enables auto-recharge.

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 schema carries no semantics to explain; baseline is 4. The description correctly implies a no-argument toggle.

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: 'Turn auto-recharge off'. An agent can tell what it does immediately, and the mention of autoshort_buy_credits hints at the related flow. It stops just short of naming autoshort_setup_auto_recharge as the enabling counterpart, which is the natural sibling to disambiguate against.

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

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

Usage is implied rather than stated: use it when you want auto-recharge disabled. There is no explicit 'use setup_auto_recharge to re-enable' routing, and the 'needs the owner's approval again' clause describes a consequence without pointing the agent at the tool that performs the reversal.

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

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

Annotations only declare the generic non-readonly profile; the description supplies the operationally important behavior: draft creation is free, credits are charged only at render, brief mode requires a positive balance and is capped at 20/hour, narration is never rewritten, image_url downloads are cleaned of EXIF/GPS and served by AutoShort, and mismatch warnings are surfaced. That is well beyond what annotations cover.

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

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

Front-loads the free/draft distinction and the workflow before the per-field detail, and nearly every sentence carries unique information. It is dense and long for one paragraph, but the density is substantive rather than padding.

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

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

With no output schema, the description still names the return payload (draftId, scenes, estimatedDurationSeconds, estimatedCredits, warnings[]) so the agent knows what to show the user. Combined with the workflow, credit behavior, and verbatim-narration rule, an agent has everything needed to invoke this correctly and hand off to the next tool.

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

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

Schema coverage is already 86%, and the description adds real semantic context: narration is read verbatim and never rewritten, each scene with a visual gets exactly that image plus the art style, image_url substitutes the user's own photo and is marked imageSource "your image", and targetDuration is preserved even when narration cannot fit. Minor gap: aspectRatio and artStyle's enum behavior 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?

Opens with a specific verb+resource pair ('Create a video DRAFT') plus the key qualifier that nothing is rendered or charged, which cleanly separates it from autoshort_render_draft and autoshort_generate_video. The Director-mode workflow makes the tool's role in the pipeline 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 an explicit four-step sequence naming the sibling tools (autoshort_update_draft, autoshort_render_draft) and the condition that gates each: agree a script first, render only after user approval when credits are charged. It also distinguishes the two invocation modes (scenes[] for an agreed script vs. brief for an AutoShort-written draft) with their different cost/rate-limit profiles.

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 the description reinforces this with 'Nothing is created or charged. Free.' while adding genuinely new behavior: it returns the maximum credits committable, the balance required, whether balance and the key's daily cap cover it, and when the charge would occur. That is substantive disclosure an agent could not get from the annotations or schema.

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 is front-loaded in an imperative clause, followed by usage, then return values — a sensible order. It is dense and slightly run-on in the returns sentence, but every clause carries information; there is no filler.

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

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

With no output schema, an accurate description of the return fields is essential and is provided in detail (max credits, required balance, coverage verdicts, charge timing). For a zero-required-parameter, read-only estimation tool, nothing an agent needs in order to call it or interpret the result is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics: it explains how `tool` and `arguments` compose as a hypothetical replay of a future call, and clarifies that `draftId` is a shortcut equivalent to {tool: 'autoshort_render_draft', arguments: {draftId}}. That contract between the parameters is not obvious from the nested schema alone.

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/estimate the cost of a paid tool call before executing it, and names the priced tools (autoshort_generate_video, autoshort_render_draft, autoshort_ugc_render_batch). It does not explicitly distinguish itself from sibling quoting tools like autoshort_quote_video or autoshort_quote_character_episode, which is the only missing piece for 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?

Clear temporal guidance — call this BEFORE making the paid call — plus a concrete invocation recipe ({tool, arguments} or the {draftId} shortcut). It stops short of naming when to prefer a sibling quote tool instead, so the routing vs. alternatives is only partially resolved.

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 say non-read-only, open-world, idempotent, non-destructive): it discloses exact credit cost (40, +25 for ElevenLabs), that images don't change price, that rendering is asynchronous with a 20-30s polling loop against autoshort_get_video, and that polling must stop on blockedReason. It also enumerates the two failure modes (IMAGE_IGNORED warning vs CHAT_NO_IMAGE_INPUT refusal before charging), which is precisely the kind of mutation-and-side-effect context an agent needs.

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

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

Front-loaded with purpose, then alternatives, then parameters, then routing — a sensible order with no filler sentences and every claim carrying operational weight. It is long and dense for a 10-parameter tool, and the routing block arguably belongs earlier, but nothing is genuinely wasted.

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

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

With no output schema, the description compensates by describing return signals: status values COMPLETED/FAILED, blockedReason, warnings["IMAGE_IGNORED"] with warningText, replayed: true for idempotent retries, and scene counts for images. For an async, credit-charging, open-world generator this covers everything an agent needs to call it and handle the response.

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 90%, yet the description still adds meaning the schema cannot: image_urls are positional (image 1 = scene 1) and are the ONLY way to attach images — 'Naming an image inside the brief does NOT attach it'. It also explains captionSecondaryLanguage's 'none' vs omitted (= account default) semantics and the 30s/6-scene default for targetDuration. Only aspectRatio is left uncovered, a minor omission.

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

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

The opening states a specific verb and resource — 'Create a video from a natural-language creative brief' — and immediately discloses the key mechanic (AutoShort writes the script). It then distinguishes itself from the two nearest siblings, autoshort_draft_video (verbatim script) and autoshort_generate_motion_clip (as-written prompts), 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?

Explicit positive and negative routing: use this for 'narrated stories and facts', use draft_video for word-for-word scripts with own shots, and a dedicated ROUTING paragraph excluding cinematic/video-model prompts in favour of autoshort_generate_motion_clip. It also names preconditions (VEO_3_1_OPERATOR eligibility) and a fallback path (proceedWithoutImage: true).

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?

Far beyond what annotations give: 40-credit cost charged on acceptance rather than delivery, automatic refund on FAILED, the duplicate:true 24-hour retry window, idempotencyKey to force a new clip, never-paid-account limit, ~13 minute render with 20-30s polling, and the aiGenerated label that must be preserved. Only the query parameters for polling autoshort_get_video are left unspecified.

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 core action and its sibling alternatives are front-loaded, which is good, but the block is dense and crammed with caps-locked labels and parentheticals that could be split or trimmed. Nearly every sentence carries information, yet the density makes it harder to scan than a shorter, structured version would be.

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

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

With no output schema, the description still covers the response shape (FAILED with reason, duplicate: true, aiGenerated: true) and the full lifecycle from charge to delivery or refund. An agent has everything needed to call it, poll it, and handle 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 coverage is 80% and already documents image_url/imageBase64, so the baseline is 3; the description adds real value by explaining that the stdio package also accepts a local imagePath (a parameter absent from the schema), that the photo becomes the first frame, and that idempotencyKey forces a separate clip from identical inputs. imageFileName is never mentioned.

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

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

States a specific verb and resource: animate ONE reference image into a silent 5-second clip, and explicitly contrasts itself with autoshort_generate_chat_video (multi-scene via image_urls) and autoshort_generate_motion_clip (text-to-motion). An agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use (single photo → clip), when-to-use-something-else for the two closest siblings, accepted versus rejected content classes, ownership requirements, and the follow-up polling procedure. Exclusions (real people, sexual content, children) are stated as pre-charge rejections.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true and openWorldHint=true, so the core safety profile is pre-declared. The description then adds genuinely non-obvious behavior: credits are held and refunded on failure, a fixed server suffix is appended to the prompt, the prompt is passed verbatim, trial/concurrency/daily-cap limits, and async polling every 20 s via autoshort_get_video. That is well beyond what the annotations cover, so a 3 understates the description's contribution — it would score higher if the omission bar did not already discount annotation-covered facts.

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

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

Front-loaded with purpose and the use/don't-use routing, then moves through pricing, policy, optional params, limits and polling. It is dense and largely earned, though it reads as a single long block and the pricing/trial-limit details are repeated in places, which costs it one point.

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: it echoes promptSent and the seed, and explains that the asynchronous result comes from polling autoshort_get_video until COMPLETED (videoUrl MP4) or FAILED (errorCode, creditsRefunded). Combined with cost, policy, and limit disclosures, an agent has everything needed to invoke and follow up correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema does not: prompt-wins-over-templateId precedence, templateId pulls a ready prompt/seconds/aspect ratio and an unknown id is INVALID_INPUT with no charge, character_id starts the clip from the sheet's chosen image but does not guarantee an identical face and yields CHARACTER_NOT_FOUND when not owned/ready, plus the seed echo for repeatable takes. These are decision-relevant rules an agent could not infer from the schema alone.

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

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

States a specific verb and resource ('Turn a text-to-video prompt into ONE AI motion clip'), names the model (Seedance 1.5 Pro), and explicitly distinguishes itself from autoshort_generate_chat_video. An agent can route between the two video-generation siblings 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 an explicit positive trigger (user pastes a cinematic/video-model prompt with camera, lens, lighting, aspect-ratio syntax) and an explicit negative route ('For a narrated story or facts video use autoshort_generate_chat_video'). It also states a mandatory prerequisite workflow: call autoshort_quote_video first and quote the price before creating.

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: minimum cost of 40 credits, quote checked before the page is fetched, asynchronous rendering with a recommended polling cadence, terminal states, and blockedReason handling. The openWorldHint/readOnlyHint/idempotentHint flags are all consistent with this narrative, and the description adds the operational detail the flags 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?

Four sentences, each carrying distinct information: what it builds, what it costs and when the quote happens, how to poll, and how to handle blockedReason. The action and cost caveat are front-loaded before the async mechanics.

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 covers the important return semantics (status values, blockedReason) and the follow-up call to make. It does not state what the create call itself returns (e.g. a video id to poll with), leaving that link implicit, which keeps it from a 5.

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

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

Schema coverage is 80% and the schema already explains url, artStyle, language, and idempotencyKey. The description adds no parameter-level meaning of its own (nothing about duration bounds, artStyle sourcing, or language values), so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a product marketing video') and pins the input source to 'a public product page', which separates it from the other generate_* siblings that take prompts, images, or drafts. It also summarizes the pipeline (extract details and images, write the ad, create editable scenes), so an agent knows the output is an editable ad, not a raw clip.

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 implied by the input contract (public product page URL) and the cost note preempts an unnecessary estimate/quote call. It gives concrete operating instructions (poll every 20-30s, stop on COMPLETED/FAILED, act on blockedReason) but never names an alternative tool or an explicit 'don't use this for X' exclusion, so it stops short of a 5.

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

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

With annotations present the bar is lower, yet the description still discloses the credit cost breakdown (65 = 40 render + 25 voice), that art style and images do not change price, the 402 INSUFFICIENT_CREDITS refusal, and the asynchronous render contract including the 20-30s polling cadence and how to handle blockedReason. That is substantially 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 purpose, then cost, then async contract, then an explicit ROUTING block — a well-ordered structure where nearly every sentence carries decision-relevant information. It is dense and the price facts are stated twice in slightly different form, which keeps it from a 5.

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

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

For an 8-parameter, paid, asynchronous mutation with no output schema, the description covers cost, failure modes, polling lifecycle, and routing. It stops short of describing the success payload beyond the status field, so an agent still learns the result shape only by calling autoshort_get_video.

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 a baseline of 3 applies, but the description adds real meaning for image_urls: positional scene mapping, download/strip-EXIF/re-host behavior, hourly quotas, and that excess images are refused rather than dropped. It does not add anything for niche, quality, language, or idempotencyKey beyond the schema, so it stops short of 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?

Opens with a specific verb+resource ("Generate a video from a topic") and immediately distinguishes itself from autoshort_draft_video, which renders an already-agreed script. The ROUTING sentence further separates it from autoshort_generate_motion_clip, so an agent can pick the right sibling without opening any schema.

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

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

Gives explicit when-to-use (topic-driven narrated still-image video), explicit alternatives with their selecting conditions (draft_video for an approved script, generate_motion_clip for a pasted cinematic prompt), and even names the follow-up tool (autoshort_get_video). Both the positive and the negative routing cases are covered.

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

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

Annotations declare a read-only, idempotent, non-destructive operation, and the description is consistent with that while adding real context: no email or personal data is embedded in the link, purchases are one-time with no renewal, credits persist while the account is active, and the first-purchase discount and trial terms are spelled out.

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 core purpose is front-loaded in the first clause, but the text sprawls into promotional and tangential detail ('AI-generated video.', expiry policy, the free-video daily-cap aside) that a selection decision does not need, including a sentence fragment that earns no 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 two-optional-param, no-output-schema tool, it covers selection criteria, payment flow, and the follow-up action adequately. The only real gap is that it never explicitly says the return value is the URL string itself, though 'A checkout link' strongly implies it.

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

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

Schema coverage is 100% with enums documented, so baseline is 3, but the description adds meaning the schema lacks: the plan implies a 3-day trial, EPISODE is characterized as 350 credits (one 30-second episode), and pricing ($3.49 first purchase vs. $6.99 regular) informs the choice between packs.

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 — returning a checkout link to buy a credit pack or start a plan on Whop — and immediately marks its scope ('for the human to open and pay once'). It also distinguishes itself from the sibling autoshort_buy_credits by naming that tool for the auto-recharge case.

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 rules: use this when a link is needed, use autoshort_buy_credits instead if auto-recharge is enabled, and poll autoshort_get_credit_balance after payment. It also flags the free-watermarked-video path and notes it is unavailable through API keys or MCP, which prevents a wrong call.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description's one genuine addition is 'Free' (no credit cost) plus the note that it discloses the only steps a human must do and the limits — useful, but nothing about response size, freshness, or whether it is cached.

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 entry-point directive and then the payload summary. The hyphenated stage list is dense but earns its place by signalling the breadth of the workflow overview; the trailing 'Free' is a small but load-bearing cost signal.

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 no-param, read-only orientation tool with no output schema, the description covers when to call it and roughly what it returns (workflow steps, human-only steps, limits). It could be slightly more explicit that the response is a structured capability document rather than prose, but nothing an agent needs to call it correctly is absent.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The empty input schema is fully consistent with the described behavior.

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 clear directive verb ('Describes the whole agent workflow end to end') and enumerates the workflow stages (make, approve, render, publish, automate, pay), which distinguishes it from the sibling action tools. It never literally says 'returns capability/limits data', so the resource is implied rather than stated, 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?

'Start here' is an explicit entry-point instruction that no sibling can claim, and the workflow-stages list implies the alternatives (the individual make/render/publish tools) it precedes. There is no explicit 'do not use this when...' clause, so it stops just 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?

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), but the description adds genuinely non-inferable facts: the call is free, the series quota is 3 sheets total, and a new sheet costs 21 credits for a person or 10 for an animal/mascot. It does not mention pagination or edge cases like an empty sheet list.

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 verb and resource, then layers in useful payload details. The single long sentence is slightly dense and mixes return-shape, pricing, and usage-sequencing into one breath, but nothing is wasted.

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

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

There is no output schema, and the description compensates well by enumerating the returned structure (images with id, view, url; which sheet and image are chosen; remaining quota). Combined with pricing and the free-call note, an agent has everything needed to call it and relay 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?

Schema coverage is 100% and the single parameter is already documented as 'A series id from autoshort_list_series.', so the description carries no additional parameter detail. Baseline 3 applies when the schema does all the work.

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

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

States a specific verb and resource ('Read the character sheets of one of your series') and immediately defines what a sheet is (a set of AI images of one fictional character). It also names the sibling it precedes (autoshort_create_character_sheet), so the agent can distinguish it from create/select operations without opening a schema.

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

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

Gives clear sequencing guidance: 'Use this before autoshort_create_character_sheet and tell the user the price.' Also flags 'Free', which helps the agent decide when to call it. No explicit when-not condition is 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?

Adds substantial context beyond the annotations: link is short, single-use, expires in 15 minutes, and polling reuses the same unexpired link (consistent with idempotentHint=true). It also discloses plan requirements per platform and the PLATFORM_PENDING_APPROVAL response, plus the fact that the tool is free — none of which the annotations convey. No contradiction: minting a link is consistent with readOnlyHint=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?

Front-loads the core question and answer shapes, and nearly every clause carries new information (expiry, polling, plan gating, error code). The flow is somewhat stream-of-consciousness with trailing fragments like 'Free.', but there is little 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 single-parameter tool with no output schema, the description covers the full lifecycle: what is returned in each state, how to deliver the link, the polling cadence, link reuse and expiry, plan prerequisites, and a named failure state. An agent can complete the entire connect flow from this text 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 0%, so the description must carry the meaning — and it does, mapping four of the five enum values (YouTube, Facebook, Instagram, Threads) to a paid-plan requirement, which implies TikTok is free. That is real semantic value beyond the bare enum list, though it never explains the platform argument itself or the YOUTUBE-vs-TIKTOK distinction explicitly.

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 direct question form ('Is this platform connected?') and then states both outcomes precisely: returns the account when connected, returns a connectUrl when not. A specific resource (platform connection status) and its two result shapes are unambiguous, and it is clearly distinct from siblings like autoshort_list_social_accounts.

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

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

Gives concrete operational guidance: hand the link to the user, poll every 10 seconds (pollAfterSeconds), keep going until connected is true, and note that consent is the only human step and happens once per platform. It also flags plan gating and the PLATFORM_PENDING_APPROVAL outcome. It never names an alternative sibling or an explicit when-not-to-call case, so it stops short of 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely non-redundant context: the required 'credits:read' scope, that it is default on new keys, and that the call is free — all of which affect whether an agent can or should invoke it.

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

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

Two short sentences, front-loaded with the payload description followed by the access constraint. Every clause carries information an agent needs; nothing is padding.

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

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

With no output schema, the description usefully enumerates the returned fields and covers the auth prerequisite, which is what an agent needs for a zero-parameter read. It stops short of stating units/currency or whether 'plan' is a name versus full plan details, but nothing essential to calling it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate and it does not waste words inventing parameter guidance.

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

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

Names a specific resource (credit balance) and enumerates exactly what is returned: monthly allocation, bonus credits, and plan. This separates it from siblings like autoshort_get_usage_stats or autoshort_get_limits by implication, but it never explicitly contrasts itself with them.

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

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

The phrase 'Your current credit balance' implies a pre-generation or monitoring use case, but there is no explicit when-to-use guidance and no reference to the adjacent tools (get_limits, get_usage_stats, estimate_cost, buy_credits) that an agent could easily confuse it with.

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 bar is lower; the description still contributes non-obvious context by declaring the call is 'Free' (no credit consumption) and that it works on both drafts and submitted director videos.

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

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

A single front-loaded sentence with no filler; the return-payload list follows the action statement and every clause carries 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 compensates by enumerating the returned fields and the cost profile. Only minor gaps remain, such as behavior on an invalid or non-existent draftId.

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

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

Only one parameter and schema coverage is 100% – the schema already explains that draftId comes from autoshort_draft_video. The description adds no further parameter meaning, so baseline 3 applies.

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

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

States a specific verb (read) and resource (a draft / submitted director video) and enumerates the content returned (scenes, narration, visual, timing, credits, warnings). It is distinguishable from siblings like autoshort_get_video and autoshort_render_draft, though it never names those alternatives explicitly.

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

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

Usage is only implied: the parenthetical '(or a submitted director video)' hints at its scope, but there is no explicit statement of when to call this versus autoshort_get_video or autoshort_update_draft, nor any prerequisite such as 'call after autoshort_draft_video'.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes genuinely new behavioral information beyond the annotations: the call is 'Free' (consumes no credit), and it returns live spent/remaining/reset figures rather than static config. It does not describe the response shape or freshness of the reset timestamp.

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 sentence, front-loaded with the framing clause before the colon so the agent gets the concept before the enumeration. The list items each add a distinct capability category rather than padding, and the trailing 'Free.' is a deliberate one-word addition that 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?

With no output schema, the description carries the burden of explaining returns, which it does at the category level (balance, daily cap with spent/remaining/reset, recharge status, publishing limits, hourly caps). An agent knows what it will learn but not the field names or nesting of the response; given the read-only, zero-argument nature of the tool this is a minor 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?

There are zero parameters and no schema to compensate for, so the baseline of 4 applies. The description correctly implies no arguments are needed by not mentioning any.

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

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

The description opens with a scoping frame ('Everything that can stop a call') and then enumerates the exact categories returned: credit balance, daily agent spending cap with spent/remaining/reset, auto-recharge status and monthly cap, publishing limits, and hourly free-AI caps. That makes it distinguishable from narrower siblings such as autoshort_get_credit_balance or autoshort_get_subscription by implication, though it never names those siblings or states that it is the aggregate superset view.

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: an agent can infer 'call this before attempting a paid generation to check whether anything blocks it.' There is no explicit when-to-use, no exclusion of alternatives like get_credit_balance or get_usage_stats, and no guidance on whether this should be checked pre-flight or only after a failure.

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 readOnly/idempotent annotations, it discloses cost ("Free"), the status state machine (none, saved, reviewed, confirmed) and the downstream consequence of that status for episode creation and quoting. That is genuine behavioral context an agent could not infer from the annotations, though pagination/size limits on a full season of episodes is not mentioned.

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 verb and resource, then the payload, then the workflow relevance; nothing is throwaway. It is dense — the long parenthetical inventory is a bit heavy — but every clause carries information an agent needs.

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

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

There is no output schema, and the description compensates by enumerating the returned structure (plan fields, hash, status, season review checklist, price, AI review). Combined with the workflow note, an agent knows what it will get and what to do with 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 single parameter has 100% schema coverage and already documents that it comes from autoshort_list_series; the description adds no format, validity or scoping detail beyond that. Baseline 3 applies when the schema carries the meaning.

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

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

States a specific verb and resource ("Read the season plan of one of your series") and enumerates exactly what the plan contains: logline, genre, narrator voice, cast, episodes, hash, status and review. This clearly separates it from siblings like autoshort_list_series or autoshort_save_season_plan, which either enumerate series or write the plan.

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

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

Gives a concrete use case ("use this to see where the plan stands and which episodes can be quoted") and explains the gating rule that an episode can only be made from a reviewed and confirmed plan. It does not name an explicit alternative tool to use instead when the plan is not ready, so it stops short of full when/when-not 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?

Annotations already cover read-only/idempotent/non-destructive, and the description adds meaningful context beyond them: data provenance ('views come from daily YouTube snapshots'), an explicit limitation ('audience retention is not available'), a cost note ('Free'), and a scope constraint ('only your own videos'). These are exactly the caveats an agent needs before relying on the output.

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 core resource and metric set is front-loaded, followed by usage intent and then caveats, with no redundant sentences. The metric enumeration is dense but every element adds information an agent would otherwise have to guess.

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 full burden of describing return values and it does so thoroughly (cardinality of top/bottom lists, definition of outlierScore, delta windows), plus data source and a known limitation. An agent can call this correctly and interpret results without further documentation.

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

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

Schema coverage is 100%, with both `days` (default 30, max 90) and `seriesId` (sourced from autoshort_list_series) fully documented in the schema. The description adds no further syntax or semantic detail on the parameters, so it sits at the baseline where the schema does the work.

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

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

The description names a specific resource (posted YouTube Shorts, per series) and enumerates the exact metrics returned: videos posted/measured, total/median/mean views, top/bottom 3 with outlierScore, and 7-day vs prior-7-day deltas. The clause 'Only your own videos' plus the analytics framing cleanly separates it from siblings like autoshort_list_videos or autoshort_get_usage_stats, so an agent can identify it without opening the schema.

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

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

It gives explicit decision context: 'Use it to decide what to make next: repeat the formats of the best videos, drop the worst.' That is a clear application, but it never names an alternative tool or a when-not condition, so routing is inferred rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the description isn't needed for safety. It does add two pieces of information the annotations lack: the required 'billing:read' scope and the fact that the call is free, both of which affect whether an agent should attempt it.

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

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

Two very short sentences, with the core payload (what is returned) front-loaded before the auth prerequisite. Nothing is repeated from the schema or annotations, and no sentence 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?

For a zero-param read tool the description covers prerequisites, but with no output schema in place the description is the only place to learn what actually comes back, and it only gestures at three fields (plan, status, credit allocation) without shape. Adequate but leaves a real gap for an agent planning to consume the result.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for an empty schema is 4. No parameter-level detail is missing because none exists.

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 (subscription plan, status, credit allocation) but uses no verb, leaving the read action implied by the name alone. It also overlaps with sibling tools like autoshort_get_credit_balance and autoshort_get_limits without distinguishing what makes this one different.

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 the alternatives (get_credit_balance, get_limits, get_usage_stats) that an agent would need to choose between. 'Free' hints at cost but is not stated in terms an agent can reason about without inference.

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

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

Annotations already establish readOnly, idempotent, non-destructive, and closed-world behavior, so the bar is lower; the description still adds real value by naming the required authorization scope and confirming the call is free. It does not cover freshness/refresh cadence of the counters, but nothing is contradicted.

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 compact sentence that front-loads what is returned, followed by the two operational facts (scope, cost). Every clause carries information and nothing is redundant.

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

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

With no output schema, the description must convey the return shape, and it lists the three data categories returned. The remaining gap is sibling disambiguation against get_credit_balance and any note on data freshness.

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 document and the baseline of 4 applies. The description correctly implies no inputs are needed by framing it as a fixed stats read.

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 ('API usage statistics') and enumerates the contents: credit balance, API call counts (today/total), and recent credit transactions. Clear enough to know what comes back, but it does not distinguish itself from the sibling 'autoshort_get_credit_balance', which covers overlapping data.

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 prerequisite ('Requires the "usage:read" scope') and cost note ('Free') give useful context for deciding whether the call will succeed, but there is no explicit when-to-use guidance versus get_credit_balance or get_limits, which overlap with the stats returned here.

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 signal a safe, idempotent read, and the description goes far beyond them by documenting the full status state machine (PENDING/GENERATING_*/RENDERING/COMPLETED/FAILED), what each returns, blockedReason handling, and motion clip extras with creditsRefunded. This is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with purpose then packed with status-specific return details, nearly all of which earn their place. Slightly dense run-on sentences around the motion clip clause, but no real 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?

No output schema exists, so the description carries the return-value burden and does so thoroughly: every status outcome, the blocked path with credits fields and topUpUrl, and motion clip return shape are all covered. An agent has enough to call 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?

Schema coverage is 100% and both params (id/videoId alias) are fully documented in the schema, so the description correctly does not duplicate param syntax. Baseline 3 applies since it adds no param meaning beyond the structured 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 ("Get one video's status and details by id") that is unambiguously distinct from the sibling list_videos and the create/generate tools. The scope (single video by id) is explicit and the alias behavior is a small bonus.

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

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

Provides concrete workflow guidance: poll while rendering, and "stop polling and resolve it" when blockedReason appears, with the topUpUrl as the resolution path. It does not name list_videos for the alternative listing case, but the when-to-use context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive/closed-world behavior, so the safety profile is covered. The description adds one piece of genuinely new behavioral information — that the call is "Free" and therefore consumes no credits — which matters in a toolset full of paid generation endpoints. Return shape is left unstated beyond the entity categories.

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 what is listed and finished with the cost note. Nothing is redundant or padded.

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

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

With zero parameters, full annotation coverage, and no output schema, the description is nearly sufficient — it names the four value categories an agent needs. A hint about the return structure (e.g., grouped lists per category) would close the remaining gap.

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

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

The tool takes no parameters, so there is no schema semantics to clarify and the baseline of 4 applies. The description correctly does not waste space describing arguments.

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 ("List") and enumerates exactly which resources are returned: content niches, art styles, video qualities, and durations. That is far more concrete than a bare name restatement, but it never distinguishes itself from close siblings like autoshort_list_options or autoshort_get_capabilities, which likely overlap.

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 "the generation tools accept" implies this should be called before generating so the agent picks valid values, and "Free" signals there is no cost barrier. However, there is no explicit statement of when to prefer this over list_options or get_capabilities, so usage must be inferred.

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/openWorld=false, and the description adds two traits beyond them: the data comes "from the live constants" (current, not cached/static) and the call is "Free" (no credit spend). That cost/source detail is exactly the kind of context annotations cannot express. It stops short of 5 because it doesn't say how large the payload is or whether it varies by plan.

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 scope statement is front-loaded and the em-dash enumeration, while long, is load-bearing because it tells the agent exactly which enums can be resolved here. The closing "Use it instead of guessing an enum. Free." lands the two most decision-relevant points last. Slightly list-heavy, but no sentence is pure filler.

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

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

With one optional param and no output schema, the description carries the return-shape burden, and it does so reasonably by promising options, prices, flags (premium/PRO), allowed durations, and a per-option "which tool lets you choose it" mapping. That mapping hint is valuable for chaining. It doesn't describe the structure or size of the response, so it isn't fully 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 coverage is 100% for the single optional `language` parameter, so the schema already carries the semantics (default "en", max length 10). The description only hints at it indirectly via "voices for a language," which suggests the parameter scopes voice results but doesn't say whether other sections are language-independent. Baseline 3 is appropriate.

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

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

It concretely states this is a catalog of every accepted option and price from live constants, and enumerates the categories (voices, art styles, niches, caption themes, aspect ratios, durations, providers, prices). An agent can distinguish it from siblings like autoshort_list_niches or autoshort_get_capabilities because it advertises aggregate coverage plus a tool-mapping. It lacks an explicit verb ("List"/"Get"), opening with a noun phrase, which keeps it 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?

"Use it instead of guessing an enum" is an explicit, actionable when-to-use rule that directly competes with trial-and-error or guessing from sibling tool schemas. It does not name an alternative or a when-not (e.g., when a narrow list tool like list_niches suffices), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral detail beyond that: result ordering (newest first), the fields surfaced per item (schedule, auto-post flags, brief, video count), pagination, and that the call is free — meaningful since no output schema exists.

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

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

One sentence, front-loaded with the verb and resource, then ordering, then returned fields, then pagination. No filler and every clause carries 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 usefully enumerates what each listed series contains, and annotations cover the safety profile, so an agent can call it correctly. Minor gaps: default page/limit values and whether ordering or filtering can be changed are unstated.

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 names both parameters ('Paginated (page, limit)') but supplies no defaults, no page-size guidance, and omits the schema's 1–100 limit constraint. It compensates enough to identify the pagination mechanism but adds little semantic depth.

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

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

States a specific verb and resource ('List the user's series (autopilot channels)') and disambiguates the term 'series' with a parenthetical. It also specifies ordering ('newest first') and what each item contains, which lets an agent separate it from autoshort_list_videos and the create/update/pause series siblings without opening a schema.

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

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

Usage context is implied by 'Free' and by listing, which is a useful signal relative to credit-consuming siblings like autoshort_buy_credits or generation tools. However, it never states when to prefer it over autoshort_get_series_performance or autoshort_list_videos, and gives no prerequisites or exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower, and the description still adds real context: 'Never returns tokens' (a security guarantee), 'Free' (no credit cost), and that limits returned are 'today's'. It does not cover ordering, empty-state behavior, or pagination, but those are minor for a fixed-size list.

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

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

Two sentences, front-loaded with the resource and its returned fields, then the routing rule and cost note. The field enumeration is dense but justified since there is no output schema; only minor tightening is possible.

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, no output schema, and safety fully covered by annotations, the description carries the remaining burden well: it enumerates the return payload, discloses the token-exclusion guarantee, states cost, and provides the next-step tool for unconnected platforms. Nothing an agent needs 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?

Zero parameters, so the baseline is 4; nothing needs explaining and the description correctly implies the tool returns all connected accounts without filtering. No parameter-level gaps exist by construction.

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 (List) plus a precisely scoped resource (connected publishing accounts per platform) with the five platforms enumerated and the returned fields named. An agent can distinguish this from autoshort_get_connection_status or autoshort_list_videos 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 routes the agent to autoshort_get_connection_status when a platform is not connected, giving a clear when-not rule and an alternative. It stops short of stating a positive trigger (e.g. 'call before publishing to check account health'), so it is strong but not fully complete.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this with 'Nothing is created or charged' and 'Free', plus a caution to show the user the price before generating. It also discloses non-obvious return-shape details (motion six-slot breakdown, demoVideoUrl presence, silent clips with silhouettes only). Strong added context beyond annotations.

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

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

Front-loaded with the key facts (counts and kinds), but the body is a dense run-on paragraph that re-enumerates genre and category lists already encoded in the enum schemas. Several clauses could be trimmed without losing meaning.

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 list tool with no output schema, the description enumerates what each template kind returns (prompt, length, price, six-slot breakdown, script/logline/cliffhanger) and explains the downstream workflow. An agent has everything needed to call it and act on the 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?

Schema coverage is 100%, yet the description still adds meaning: kind defaults to video+motion, episode scripts are returned only with kind "episode" or an explicit id, genre filters motion and episode only, niche filters video only. It also explains how to feed a motion template's id into autoshort_generate_motion_clip as templateId or as an edited prompt.

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 with exact counts and the three template kinds enumerated: 12 video templates, 26 motion clip templates, 6 episode scripts. It also states what each kind contains, so an agent knows precisely what comes back. Distinguishes itself from siblings like autoshort_list_niches and autoshort_list_options by naming the template kinds.

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

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

Gives explicit filtering guidance (kind, id, genre, niche) and a full episode workflow: save to a season plan with autoshort_save_season_plan, review/confirm, then autoshort_quote_character_episode. Also instructs to edit the prompt before use and show the price first. Missing only a statement of when NOT to use this versus list_niches/list_options.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds value beyond them by disclosing result ordering ('newest first') and that the call is free, which matters in a credit-based API. It stops short of describing the shape of returned video entries.

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

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

One dense sentence: resource and ordering first, then pagination and the filter, then the cost note. Every clause carries information and nothing is padded.

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

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

With no output schema, the description does not say what a listed video contains (e.g., an id usable with autoshort_get_video, status field, timestamps), which is the main gap for an agent that needs to chain calls after listing. Filter, pagination, ordering, and cost are otherwise covered.

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

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

Schema coverage is 67%: limit and offset are already documented in the schema, and the description mostly repeats the status enum values rather than explaining filtering semantics. The one added signal is that pagination applies to a newest-first ordering, which affects how offset should be interpreted.

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

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

States a specific verb+resource ('List your videos') plus ordering ('newest first'), pagination, and an optional status filter, so it is clearly distinct from the singular autoshort_get_video and from sibling list_* tools for series, niches, templates, etc.

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 (use this to enumerate videos), but there is no explicit when/when-not guidance nor any pointer to alternatives such as autoshort_get_video for a single item or autoshort_list_series for series-level listings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds genuinely new context: which fields come back, that signing secrets are deliberately withheld (so an agent must not expect to recover them here), and that the call is free of credit cost.

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

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

Three short sentences, front-loaded with the action and the returned fields, then the two constraints an agent actually needs (no secrets, no cost). No filler.

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

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

With no output schema and no parameters, the description carries the burden of describing the response, and it does so by enumerating the five returned fields and flagging the one omission (secrets). An agent has enough to call it and interpret the result 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?

The tool takes zero parameters, which sets the baseline at 4; there is no parameter semantics for the description to clarify. Nothing in the text misdescribes the argument-less signature.

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

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

States a specific verb and resource ('List the registered webhooks') and enumerates the fields returned (URL, events, active, last delivery, failures), which is far beyond a restatement of the name. The verb alone separates it from autoshort_create_webhook and autoshort_delete_webhook, though no sibling is named explicitly.

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

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

Usage is only implied: an agent can infer this is the read/inspection step before create_webhook or delete_webhook, but the description never says when to call it or what alternative exists. No exclusions or prerequisites are given.

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 (idempotent, non-destructive), the description adds meaningful context: charging stops, and existing videos are untouched, plus it costs nothing. It doesn't cover side effects on scheduled-but-unmade videos or required permissions, keeping it out of the top band.

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

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

Three short clauses, front-loaded with the action and its effect, with zero wasted words. Every sentence 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 single-param idempotent toggle the description covers effect, cost, and impact on existing assets. It could mention how to obtain a seriesId, but overall it is nearly 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 coverage is 0% and the description never explains seriesId, though with a single self-evident identifier parameter the gap is small. Adequate but adds no meaning beyond the schema.

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

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

The description states a specific verb ('Pause') on a specific resource ('a series') and explains the concrete effect: the scheduler stops making videos. Implicitly contrasts with autoshort_resume_series, so an agent can tell what this tool does without inspecting 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?

'until resumed' clearly signals the counterpart tool (autoshort_resume_series) and the condition for it. However, no explicit when-to-use/when-not guidance or prerequisites are given, so it falls short of the top band.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds substantial non-obvious behavior: it is free, spends no credits, starts nothing, saves nothing, is rate-limited per hour, refuses real people/brands/sexual or graphic content, and returns needsEditing: true with an `issue` when an episode cannot be sized to fit. The cliffhangerLine contract (last sentence exactly equals it, hook vs. payoff on final episode) is disclosed precisely.

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 transformation before the mechanics and pipeline, and nearly every clause carries information an agent needs. However, it is delivered as a single dense paragraph mixing output contract, failure mode, pricing, content policy and workflow, which makes it harder to scan than it could 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?

There is no output schema, so the description must explain returns — and it does: character bible contents, per-episode fields, the cliffhangerLine spoken-script invariant, and the needsEditing/issue failure signal. Combined with explicit workflow handoffs, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% so the baseline is 3; the description adds real meaning beyond the schema — the premise is a one-line hook, the resulting scripts are pre-sized to pass autoshort_quote_character_episode (30-60s narration), and casting yields 1-4 characters with name, role, look. Genre/language enum meaning is left to the schema, so not 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 artifact: turn a one-line premise into a short-drama season, and enumerates exactly what is produced (character bible of 1-4 characters, 2-8 episode scripts with title, logline, script, cliffhangerLine). This is unmistakably distinct from siblings like autoshort_generate_video or autoshort_save_season_plan.

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

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

Gives an explicit ordered pipeline of next steps naming the sibling tools (autoshort_create_series, autoshort_create_character_sheet, autoshort_save_season_plan, then quote/create per episode), plus a customer-approval gate before rendering. It doesn't state when an agent should skip this tool in favor of alternatives, but the sequencing guidance is concrete and actionable.

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 idempotency key (videoId, platform), the QUEUED/POSTED/FAILED async status flow for Meta, NOT_CONNECTED with connectUrl, per-platform rate caps (YouTube ≈5/day, Facebook 25, etc.), and that nothing is appended unless addAttribution. These are exactly the traits an agent needs and cannot infer from readOnlyHint/openWorldHint/idempotentHint.

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 well-organized by platform (YOUTUBE / TIKTOK / FACEBOOK-INSTAGRAM-THREADS), with cross-cutting rules (idempotency, caps, NOT_CONNECTED) at the end. Long for a single tool, but nearly every clause carries actionable information; minor redundancy with schema param descriptions.

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

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

Despite no output schema, the description explains return values (QUEUED, POSTED with url, FAILED, NOT_CONNECTED with connectUrl) and the retry path, plus per-platform constraints. Nothing an agent needs to invoke it correctly across five platforms 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 already 80%, so baseline is 3; the description adds genuine value by tying madeForKids to the COPPA/kids-audience question, framing userConsent as a consent gate, and clarifying addAttribution's default-off intent. It doesn't cover every param (e.g., caption limits are left to the schema), so not 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+resource: 'Publish one of the user's COMPLETED videos', then immediately disambiguates per platform (YouTube upload, TikTok drafts, Meta public Reels). This clearly separates it from siblings like draft_video, render_draft, and generate_video, and the 'COMPLETED' qualifier is a concrete precondition.

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 strong conditional guidance for optional params: retry only after a FAILED attempt, userConsent only after the user agreed, addAttribution only when the user asked for 'Made with AutoShort'. It doesn't explicitly route to an alternative sibling (e.g., draft_video for unfinished work), but the COMPLETED-video prerequisite does most of that work.

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 the description adds substantial context: it spends nothing and starts nothing, runs the same safety checks as the real call (CONTENT_POLICY refusal categories), and enumerates failure modes with nextActions. This is rich behavioral disclosure beyond 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?

Front-loaded with the core purpose and the free/paid distinction, and content is dense with little waste. However, it is a single long paragraph bundling workflow, error codes, safety policy, and field locking, which could be split for faster scanning.

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, but the description fully covers return values (shot plan, exact credits, ready-made nextAction) and all error outcomes, leaving nothing an agent needs to invoke and interpret it correctly.

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

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

Schema coverage is 100%, so the schema already documents every parameter, including the script-vs-shots split and the locked sheetId/language fields. The description reinforces the locking constraint and resolution pricing rationale but adds little per-parameter syntax beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb (price) and resource (one planned episode of a series with a confirmed season plan), including scope constraints like 30-60s / 3-8 shots. It explicitly names the create sibling it hands off to, so an agent can distinguish it from autoshort_create_character_episode 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 explicit when-to-use and when-not: 'call the create tool only after they say yes,' plus error-routing conditions (SEASON_PLAN_REQUIRED, SEASON_NOT_REVIEWED, EPISODE_NOT_IN_PLAN, SEASON_FIELD_LOCKED) and the instruction to point to autoshort_get_season_plan for the plan. The workflow alternative is fully specified.

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 by stating nothing is created, reserved or charged, that the call is free, and what is returned: the balance, whether it covers the price, this key's remaining daily cap, and canStart/blockedBy. That is decision-grade behavioral context an agent cannot infer from annotations alone.

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

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

Front-loaded with the core guarantee (price, read-only, free) and then mode-by-mode detail; no filler. The sentences are long and clause-heavy, which slightly slows scanning, but every clause carries 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 carries the return-value burden and does so — balance, coverage sufficiency, canStart/blockedBy, daily cap — and closes the loop on the follow-up creation call. Nothing an agent needs to price and then act 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 already 80%, and the description still adds real meaning: the duration ranges are attributed per mode (4-12 for motion_clip, 8-90 for stills) and the tool parameter is scoped to stills-only with a documented default. The only gap is aspect_ratio, which is unexplained.

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 ('the exact credit price of a video BEFORE it is made') and enumerates both modes with the concrete creating tool each maps to (autoshort_generate_motion_clip, autoshort_generate_chat_video / autoshort_generate_video). An agent can distinguish this from autoshort_estimate_cost or autoshort_get_credit_balance without opening a schema.

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

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

Explicit sequencing: 'Tell the user the price, then call the creating tool' — this is a pre-flight quote, not the creation itself. Each mode names the downstream tool, so the agent knows exactly which sibling to invoke after pricing.

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

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

Annotations only cover the safety profile (not read-only, idempotent, non-destructive, open-world), while the description supplies the consequential details an agent actually needs: credits are charged up front (40 default), refunded on permanent failure, a 402 keeps the draft intact, and repeated calls are retry-safe returning the first submission. This is exactly the value-add the annotations cannot provide.

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

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

The critical constraint (approved-only) is front-loaded and every sentence carries operational information. It is dense but not padded, though parentheticals such as "(any mismatch was in the draft's warnings)" and "with the default voice" add length that could be tightened without losing meaning.

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 the description covers cost, refund policy, idempotency, billing failures, the async lifecycle, the polling cadence, and the terminal/blocked states. That is everything needed to call this mutation safely and 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 50%: idempotencyKey is documented in the schema itself, and the description reinforces its effect by explaining retry-safety. However, draftId's type and meaning get no elaboration beyond 'approved draft', and the description does not tie its cost/refund behavior back to draft fields like estimatedCredits in a way that clarifies the parameter.

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

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

The description opens with a specific verb and resource ("Render an approved draft") and immediately constrains it to approved drafts, which cleanly separates it from the sibling autoshort_draft_video that creates the draft in the first place. An agent can identify the tool's role 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 states an explicit precondition ("Call ONLY after the user has seen the draft and said yes") and gives a full follow-up protocol: poll autoshort_get_video every 20-30 seconds until COMPLETED or FAILED, then act on blockedReason. The when-to-call and what-to-do-next guidance is unusually complete.

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

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

The description adds substantial behavior beyond the annotations: scheduling cadence (one video per scheduleIntervalDays, first within ~30 min), billing at render rather than on schedule, skip-not-fail behavior on insufficient balance, no overdraft guarantee, and the daily agent spending cap interaction. For a non-readonly mutation tool this is exactly the operational context needed.

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 action in the first sentence, then the economic consequences. The billing explanation is dense and uses several em-dash clauses, but every sentence carries functional information; slightly more compact phrasing would help.

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 prerequisites, cost model, failure semantics, and cap interaction for a one-parameter mutation tool with annotations. The only missing element is what the call returns (no output schema exists, so the description could have said), which is a minor gap.

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

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

The schema has 0% description coverage for its single parameter, and the description never mentions seriesId — not where to obtain it (e.g., autoshort_list_series) or its format. The parameter name is self-explanatory, so the gap is modest but real.

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?

"Resume a paused series" gives a specific verb (resume) and resource (series), making the inverse relationship to autoshort_pause_series unambiguous. It never names the sibling or explicitly states the state transition requirement, but an agent can identify the tool's job immediately.

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

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

Usage is only implied: the series must be paused and the agent is told to consult autoshort_get_limits for the spending cap. There is no explicit guidance on when to resume vs. create a new series, or on re-pausing with autoshort_pause_series.

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 annotations: the original video is untouched, unchanged scenes keep their existing images, and the revise step charges nothing while the subsequent render does (narration re-voiced, video re-assembled). This cost/side-effect disclosure is exactly what annotations (readOnly=false, destructive=false) cannot 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 action and the key behavioral fact (new draft, original untouched), then the cost model, then the follow-up tool. No wasted sentences despite packing in several distinct facts.

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 4-param mutation tool with no output schema, the description covers the full lifecycle: what is created, what is preserved, what it costs, what to do next, and what is not supported. Nothing essential is missing.

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

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

Schema coverage is 75% — scene, visual, and narration are documented in the schema, but videoId has no description in either place. The description adds no parameter-level detail, so the schema is doing the work; baseline 3 is appropriate with a minor gap on videoId.

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 ('change one scene of a video that was already rendered') and immediately clarifies the mechanism (creates a NEW draft copying all scenes). This clearly separates it from autoshort_update_draft and autoshort_render_draft 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?

Explicitly names the follow-up step (show to user, then autoshort_render_draft renders it) and names the unavailable alternative ('single-scene re-render inside the existing file is not available yet'), so an agent knows both what to do next and what not to attempt.

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: the tool is free (no credits), every edit invalidates the review and confirmation, the review is deterministic plus an advisory AI review that degrades gracefully if it cannot run, and confirmation is hash-gated. The annotations only say this is a non-destructive, idempotent, open-world write; the description explains the state machine that governs it.

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

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

Purpose and cost are front-loaded, and the numbered three-step structure makes a complex workflow scannable. It is a dense single block and a few clauses (founder rules, the checklist enumeration) could be tightened, but nearly 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 6-parameter nested-payload workflow tool with no output schema, the description covers everything an agent needs: prerequisites, step ordering, what the review returns (checklist, up to 8 issues, season price, planHash), fallback behavior, and the next tools to call. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description goes further by explaining the interplay between parameters — plan then review then confirm, planHash comes from the review, and `plan` must not be sent alongside `confirm`. It also enumerates the required plan payload fields, though the nested schema already documents most field-level meaning.

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

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

States a specific verb chain and resource: design, review and confirm the whole season plan before episodes are made. It also names downstream siblings (autoshort_create_character_sheet, autoshort_quote_character_episode, autoshort_create_character_episode). It does not, however, distinguish itself from the similarly-named autoshort_plan_drama_season or autoshort_get_season_plan, which an agent could easily confuse with this one.

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 three-step sequencing with conditions: pass `plan` to save, `review: true` to run the checklist, and `confirm: true` with planHash only after the owner says yes. Prerequisites are spelled out (a READY sheet per character whose id is in the plan) and the follow-on tools are named, so the agent knows both when and when-not to call.

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

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

The annotations already establish that this is a non-destructive, idempotent mutation; the description adds useful operational context by stating the READY/ownership constraint and that the call is free. It does not describe error cases or return behavior, but it adds meaningful context beyond the annotations.

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

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

The description is short and front-loaded: purpose first, downstream relevance second, eligibility and cost last. Every sentence carries useful information without repetition.

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

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

For a simple selection/mutation tool, the description covers purpose, prerequisites, downstream effect, and cost, while the schema documents the optional assetId behavior. The main remaining gap is the lack of explicit seriesId explanation and any return-value expectation, but the definition is otherwise sufficient to call 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?

The description clarifies the relationship between series and sheet and notes that sheetId corresponds to character_id for motion-clip generation. However, with only 67% schema description coverage, the required seriesId parameter remains undocumented in both schema and description, so the compensation is partial.

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: choose which character sheet a series uses and which image is its main one. It also ties the operation to autoshort_generate_motion_clip, so the agent can distinguish this selection tool from generation and sheet-fetching 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 gives clear usage context: the chosen main image is what generate_motion_clip starts from when character_id is passed, and only the caller's own READY sheets/images can be selected. It does not name a direct alternative tool, but the prerequisites and downstream dependency are 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 well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing the asymmetric effect: decreases take effect immediately while increases return an approvalUrl that the signed-in account owner must approve. That is exactly the kind of non-obvious behavioral trait an agent must know before calling, and it also flags the call as free.

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

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

Three short sentences with the mutation effect front-loaded, the approval branch second, and the cost note trailing. Every sentence adds information; nothing is restated from the schema or annotations.

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

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

For a single-parameter mutation with no output schema, the description supplies the missing return shape (approvalUrl on raises), the human-approval dependency, and the immediate-apply semantics for decreases. Nothing an agent needs in order to call this correctly is absent.

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

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

Schema coverage is 0%, so the description must carry the parameter burden; it does by naming the unit (credits) and the cadence (daily) that the schema's bare 'dailyCreditCap' integer does not. It still omits any discussion of the 0–100000 bounds or what a cap of 0 means, so it is good but not exhaustive.

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

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

States a specific verb and resource ('Set this key's daily agent spending cap in credits'), with the unit and the scope ('this key') made explicit. It is clearly the write counterpart to the sibling autoshort_get_limits, so an agent can distinguish them 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 concrete operating context: lowering applies immediately, raising requires owner approval, and an agent cannot raise its own cap. It does not explicitly name autoshort_get_limits or autoshort_buy_credits as alternatives, so guidance is strong but not a full when/when-not routing statement.

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 explaining that nothing is charged at this step, that the owner must sign in and confirm exactly the pack and cap, and that a card is saved on Whop. It also discloses the cap range and that the tool is free. Remaining gaps: whether the approvalUrl expires, and how to check whether the owner completed the 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?

Dense and front-loaded, with the outcome (approvalUrl) stated early and no filler. The clause 'Nothing is charged then' and 'Until they finish, nothing changes' overlap slightly, and the cap/free line trails awkwardly.

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 two-parameter mutation with no output schema, the description covers the full flow, the safety profile, and the return value's role. It falls short on operational follow-through: how the agent learns the pack prices it is told to relay, and what to do if the owner abandons or the link expires.

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

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

Schema coverage is 0%, so the description carries the burden, and it does explain both parameters at a high level (a pack, a monthly USD cap bounded at $500). However, the four enum values (MICRO, STARTER, VALUE, MEGA) are never mapped to prices or sizes even though the tool requires telling the user the pack price, and 'Cap: pack price to $500/month' is ambiguous against the schema's minimum of 1.

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 — propose auto-recharge with a pack and monthly USD cap — and implicitly distinguishes itself from the one-off purchase siblings by noting that later purchases 'need no link'. It never names autoshort_buy_credits or autoshort_disable_auto_recharge explicitly, so the sibling differentiation is inferred 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 clear context for use (when the user should not have to re-link for later purchases) and a concrete pre-call instruction: tell the user the pack price and cap before sending the link. No explicit exclusions or named alternatives, 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?

Beyond the annotations (which cover readOnly/destructive/idempotent/openWorld), the description discloses that generating a character costs 1 credit charged *before* the image is made, that the rest is free, that content is server-side rejected if not a fictional, non-sexual adult, and that videos carry an AI-generated label/metadata. These are cost and refusal behaviors 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?

Front-loaded with purpose, then format spec, then flow, then parameter rules — a sensible order. It is long and repeats the silence/character-consistency constraints, but almost every sentence carries operational content rather than filler.

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

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

For an 11-parameter creation tool with no output schema, the description covers what is produced, media constraints (MP4/MOV, 3-60 s, 50 MB), cost, content policy, and the downstream steps needed to get finished videos. An agent has enough to start correctly and knows where to poll.

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 45%, so the description must carry weight, and it does add meaning for characterId, characterDescription, characterStyle, recordingAssetId, appName and appDescription. However goal (installs/trial/awareness), appUrl and characterName receive no explanation anywhere, leaving a real gap for 3 of 11 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?

Opens with a specific verb and resource ("Create a Silent UGC campaign") and immediately defines the artifact: 9-12 s silent promo shorts with a two-scene structure. This is clearly distinguished from sibling ad/video generators like autoshort_generate_product_ad or autoshort_generate_video.

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

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

Gives an explicit numbered flow from upload_recording through get_campaign polling, naming the exact sibling tools at each step and the precondition that recordingAssetId comes from autoshort_ugc_upload_recording. It also states the branch (pass characterId to reuse vs. characterDescription to generate), which is exactly the decision an agent must make.

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 bar is lower; the description still adds real value by disclosing the returned inventory (variants, status, preview, finished videoUrl) and the cost trait ("Free" = no credits consumed). It stops short of saying what happens on an unknown campaignId or whether variants can be mid-render.

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

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

One dense, front-loaded sentence with no filler; the resource comes first and the return contents follow. Minor awkwardness in the parenthetical "(download)" and the unexplained "Silent UGC" framing.

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 with no output schema, the description usefully enumerates the return payload and cost, which is the main thing an agent needs. The remaining gap is the identifier's provenance/format, which neither schema nor description covers.

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

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

The single parameter campaignId has 0% schema description coverage, and the description supplies nothing: no format, no note that the ID comes from ugc_create_campaign, no error semantics. The description does not compensate for the schema gap.

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

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

Specific verb+resource ("Read a Silent UGC campaign") with an enumeration of what the reading returns: character, recording, hooks, variants, status, preview, videoUrl. An agent can distinguish it from ugc_create_campaign or ugc_render_batch by the verb alone, though the description never explicitly names an alternative.

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

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

No when-to-use / when-not-to-use guidance and no pointer to the sibling that creates the campaign being read (ugc_create_campaign) or how it relates to ugc_preview. The only usage-adjacent signal is the trailing "Free."

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, and the description adds genuinely new context: nothing is rendered at this step, the variantId is only a draft, and credit consumption is conditional on start-frame generation. That is exactly the behavioral detail the annotations do not carry.

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

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

Front-loaded with the core action, then cost, then workflow guidance, in roughly 50 words with no filler. Every clause adds 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?

With no output schema, the description does the work of naming the return shape ('Returns previewUrl and a variantId (a draft)') and explains cost and next-step workflow. The main residual gap is campaignId and the practical effect of idempotencyKey, which are left unaddressed in the description.

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

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

Schema coverage is only 20%, so the description needs to carry more weight; it usefully clarifies that 'expression' means body language and that 'hook' is rendered as it will appear, and setting/expression enums are self-explanatory. However campaignId is never explained and hook's 90-char limit is left to the schema, so the gap is only partially closed.

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: 'Preview ONE variant's scene 1 before rendering anything,' and immediately clarifies the scope (character + setting + gesture, hook laid out as the video will show). An agent can distinguish this from autoshort_ugc_render_batch 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 an explicit workflow gate: 'Show the still to the user; render only after they approve,' which implies the alternative (batch/full render) and the condition that selects it. It also gives a cost rule ('1 credit only when a new start frame has to be generated; otherwise free'). It stops short of naming the sibling render tool outright, 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: per-item credit pricing, all-or-nothing batch reservation before generation, 402 with zero charge on insufficient balance, fallback from failed clip to still frame with refunded clip credits. This is exactly the cost/risk disclosure an agent needs before a paid write.

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 action and the precondition, then pricing, then parameter semantics, then next step. Dense but nearly every clause carries operational value; the pricing sentence is long but non-redundant.

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

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

For a paid, mutating batch tool with no output schema, the description covers cost, atomicity, failure behavior, idempotency implications, and the polling path. It does not say what the immediate response contains (batch id / immediate vs queued status), which is the only real 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?

With only 25% schema coverage, the description carries most of the load and does it well: it explains variantIds vs variants, that setting/expression default to the latest previewed variant making them cheap re-captions, and that fromVariantId re-captions a rendered clip. Only the idempotencyKey is left to the schema, which already documents 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?

States a concrete verb+resource+limit: 'Approve and render up to 20 variants'. It clearly separates this from autoshort_ugc_preview (drafts) and autoshort_ugc_get_campaign (polling) by naming both 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?

Explicit precondition ('Call ONLY after the user approved the preview'), an explicit choice rule between variantIds (approve drafts) and variants (new hooks / re-captions), and a follow-up instruction to poll get_campaign every 30 seconds. When-to-use and what-to-do-next are both 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?

With readOnlyHint=false and openWorldHint=true already declared, the description still adds real substance: cost ('Free'), a credit-balance prerequisite, a hard rate limit ('max 20 per hour'), and the internal honesty filter that suppresses unbackable income/results/testimonial/speed claims. Missing only whether results are persisted or repeatable, which matters given idempotentHint=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?

Four tight sentences, no filler, front-loaded with the verb and output. The enumeration of hook families is long but functional since it forecasts the return shape; the credit/cost sentence could be trimmed without loss.

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 the description forecasts the return content (10-20 strings in named families) and filters, and covers cost, limits, and the human-review step. Only the shape of the response envelope and persistence semantics are left open.

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 parameter burden. It implicitly maps '10-20 hooks' onto the count bounds and 'for a campaign' onto campaignId, but never names either parameter, never says count is optional, and gives no hint about default count. Partial compensation only.

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 ('Propose 10-20 hooks for a campaign') plus the input source ('from its app description') and even enumerates the hook families produced. An agent can immediately tell this is a UGC hook-generation tool rather than a video, campaign-creation, or preview 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?

Gives clear context for invocation and an explicit post-call workflow ('Show the hooks to the user and let them pick'), plus prerequisites (positive credit balance). It does not name alternatives such as autoshort_ugc_preview or autoshort_ugc_create_campaign, so the boundary with siblings is left implicit 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?

Adds context beyond the annotations: the URL is fetched server-side by AutoShort rather than by the agent, formats are validated from the file itself, and the call is free — none of which the annotations convey. One wrinkle is the mention of a local recordingPath that does not appear in the schema, which could mislead an agent in the HTTP transport.

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

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

Four dense sentences, front-loaded with the purpose and return value, then constraints, then cost. Every clause carries actionable detail (size caps, formats, duration, who fetches the URL) with no filler.

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

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

With no output schema, the description names the returned recordingAssetId, and it covers formats, duration and size limits so an agent can call it correctly on the first try. It does not address what happens on re-upload or what errors look like, though idempotentHint=false already signals that repeat uploads create new assets.

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 67%; the description compensates well on the two important parameters by explaining the fetch behavior of recordingUrl and the 10 MB ceiling that forces the URL path. The fileName parameter is never mentioned and the either/or relationship is only implied by 'or', leaving a small gap.

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

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

Specific verb+resource: uploads an app screen recording for Silent UGC and returns a recordingAssetId. It also names the downstream consumer (autoshort_ugc_create_campaign), which no sibling tool name alone would reveal. An agent can distinguish this from autoshort_ugc_create_campaign or autoshort_ugc_preview immediately.

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

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

Gives a clear decision rule between the two input modes (use recordingUrl for files over 10 MB) and states this is a prerequisite step for campaign creation. It lacks any explicit 'when not to use this' or prerequisite ordering beyond the implied pipeline, so it stops short of a 5.

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

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

Goes meaningfully beyond the annotations by disclosing cost ("Free"), the deterministic operation ordering, the null-clears-visual fallback, and the return contract ("Returns the updated draft — show it to the user again"). What it omits is reversibility: whether dropped scenes or overwritten narration can be recovered, which matters for a non-idempotent mutation.

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 the ordering rule, then per-operation semantics, then the return instruction — a logical sequence with no filler. The telegraphic style ("Free.", "remove: scene numbers to drop.") is dense but occasionally clipped enough to slow parsing.

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

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

For a 10-parameter, non-idempotent mutation with no output schema, the description covers purpose, cost, ordering, indexing, and what comes back. Gaps are secondary: no mention of warnings[] semantics (left to schema), no failure modes, and no note on whether removing scenes is recoverable.

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 40% schema coverage the description must compensate, and it does for the core five: it defines edits (narration verbatim, visual null → auto image, seconds), insert with "after N (0 = at the start)", remove, and reorder requiring every current scene number. The crucial 1-based / as-it-is-now indexing rule is stated here and nowhere in the schema. The remaining params (title, artStyle, language, aspectRatio, targetDuration) are left 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?

"Change a draft before render" gives a specific verb (change) and resource (draft), and the following sentences enumerate exactly which facets can change. It implicitly separates itself from autoshort_render_draft and autoshort_get_draft via "before render", but never names a sibling, so differentiation is inferred 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?

"Change a draft before render" plus "Free" gives a usable context cue, and the stated application order (edits → reorder → remove → insert) tells the agent how to combine operations. However, there is no explicit routing guidance against close siblings like autoshort_revise_scene or autoshort_get_draft, and no when-not conditions.

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

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

With annotations only declaring the safety profile (non-read-only, idempotent, non-destructive), the description supplies the economics the annotations cannot: editing is free, each scheduled render is charged at render time, an underfunded balance skips the run rather than failing or overdrawing, and the daily agent cap applies. That is exactly the non-obvious mutation behavior an agent needs before triggering a recurring spend.

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 partial-update rule are front-loaded in two short sentences, which is the right ordering. The billing/scheduling tail is one long semicolon-chained run-on that takes two passes to parse, so it is dense 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?

For an 11-parameter mutation with no output schema, the description covers optionality, cost, scheduling cadence and the daily cap, which is most of what's needed. Gaps remain on side conditions — e.g. whether setting autoPost flags requires connected accounts, or a minimum on scheduleIntervalDays beyond the schema.

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

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

Schema coverage is only 45%, so the description carries real weight — it names 9 of the 11 parameters, including the terse autoPostTikTok/autoPostYouTube/scheduleIntervalDays fields the schema leaves bare, and clarifies optional-field semantics via "only the fields you pass change." It adds no format hints for scheduleIntervalDays or brief length, which keeps it off 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?

"Change a series" plus an explicit enumeration of the mutable fields (name, brief, schedule, auto-post flags, madeForKids, motionMixLevel) makes the verb+resource unambiguous and separable from create/pause/resume siblings. It stops short of naming those siblings as alternatives, but the resource scope is unmistakable.

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

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

"Only the fields you pass change" is a genuinely useful partial-update rule, and it points at autoshort_get_limits for the spending cap. However, nothing says when to reach for this versus autoshort_create_series, autoshort_pause_series or autoshort_resume_series, so the choice among siblings is left to inference.

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