WowReveal

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

With annotations already covering safety hints, the description adds meaningful behavior: it costs 8 credits, returns a project id immediately, and requires following up with wait_for_project. It also discloses the prerequisite that source projects must be finished and the valid 2–30 project range.

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 key purpose, cost, and async behavior are front-loaded and easy to scan. The parenthetical about Facebook ads is slightly tangential, keeping it from being maximally concise.

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 async mutation with no output schema, the description provides the critical workflow details: what it creates, the credit cost, the immediate return value, and the required follow-up call. All parameter details are also fully covered by 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 description coverage is 100%, so the schema already documents all parameters in detail. The description adds only a little extra meaning, notably the status-complete requirement for source projects, so the 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?

The description states a specific verb and resource: combine 2–30 finished projects into one numbered long video. It also distinguishes the output as a long-format compilation, which helps separate it from sibling tools like create_short.

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

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

It clearly frames when to use the tool: to combine finished projects with status complete into a compilation. It also tells the agent what to do next by naming wait_for_project, though it does not explicitly compare this tool against alternatives.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false), and the description adds substantial context beyond them: synchronous/instant execution, a flat cost of 2 credits regardless of format count, and that returned signed JPEG links expire after 24 h. These are exactly the facts an agent needs before committing a paid write call.

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

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

Front-loaded with the verb and resource, then layers source options, formats, cost and return value in a dense but readable block; nothing is wasted. It reads as a run-on sentence with fragment clauses, which costs a little clarity.

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

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

For a tool with no output schema, the description covers everything an agent needs: the input alternatives, the output form (signed JPEG links), their lifetime, the cost, and that execution is instant. Nothing material is left 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 100%, so the enum values, defaults and size mapping are already fully documented in the schema. The description largely restates format dimensions and source-id meaning rather than adding new semantics, so it sits at the baseline for a fully-documented 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 (make) and resource (cover/thumbnail JPEG) and immediately scopes it: a frame from a finished project (project_id) or an uploaded image/video (upload_id) with a headline. This distinguishes it from siblings like create_short, create_post_kit and create_compilation without the agent 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?

Explains the two ingestion paths (project_id vs upload_id) and the available output formats, so usage is clearly implied. However, it never names an alternative tool or a when-not condition, and gives no guidance on which source to prefer or what to do when neither id is available.

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 the safety profile (not read-only, not destructive, not idempotent). The description adds important operational context beyond annotations: it is instant and costs 1 credit, which is directly relevant to invocation decisions.

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 a single tightly packed sentence that front-loads the core action and output, with no filler. Every clause contributes useful selection or cost 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 naming the kit contents (3–5 titles, description, hashtags, first comment, hook, tips), the input modes, platform/language scope, speed, and credit cost. That is enough for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description reinforces that project_id and topic are alternative inputs and that platform/language are required, but adds no syntax or constraints 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?

The description states a specific verb and resource ('Write a ready-to-post kit') and enumerates the deliverables (titles, description, hashtags, first comment, hook, tips), making it readily distinguishable from siblings like write_script or create_short.

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

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

It clearly explains the two input modes: an existing project via project_id or a described video via topic, and specifies platform/language scoping. It does not explicitly name alternatives or when not to use it, so it falls short of full routing guidance.

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

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

Goes well beyond the annotations: it discloses that the call is asynchronous, returns project ids immediately, takes ~2–10 minutes to render, and must be polled via wait_for_project/get_project. It also states the billing model (credits charged now, auto-refunded on failure) and the batch-limit constraint, which are exactly the traits an agent needs before committing to 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 correctly: the first sentence covers purpose and async behavior, then the mode/cost block follows. The mode paragraphs are dense but each carries decision-relevant information; the structure would be cleaner as bullets, and a few clauses (e.g. 'same price') are near-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 24-parameter, zero-required, no-output-schema tool, the description covers the essentials: what comes back (project ids), how to resolve to a finished asset, cost, and failure refund. It does not spell out what a partial failure in a batch returns or how project ids map to input urls, which would matter at this parameter count.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds real value on top by pricing each tool= mode, noting template_id makes tool optional, explaining that edit_mode='whole' is meant for 20–60 s clips, and clarifying the urls batch ceiling. Only minor gaps remain, such as not hinting at how hook/headline/target_seconds interact across modes.

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+format: 'Start making vertical 9:16 short(s) from a video link or an upload', which tells an agent exactly what is produced and from what input. It names follow-up siblings (wait_for_project, get_project) but never distinguishes itself from generation siblings like start_clipper, generate_clips, or create_compilation, so the boundary is left to inference.

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

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

Gives substantive decision guidance for the internal modes — which content maps to tool=story vs transformation vs clips, credit cost per mode, and when edit_mode='whole' applies. It also explains the batch path via urls. What it lacks is any explicit when-to-use-this-instead-of statement relative to the sibling generation tools, so exclusions are absent.

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 readOnlyHint=false, but the description adds real substance on top: exactly what data is destroyed, that it cannot be undone, that pending credits on a failed project are refunded first, that it costs nothing, and that user confirmation is required.

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, front-loaded with the destructive scope before the precondition and the cost. The telegraphic fragments ("Free.") still carry information 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?

No output schema exists, and the description covers everything an agent needs: what gets removed, the precondition blocking the call, the refund side effect, the irreversibility, and the zero cost. Nothing material is left unspecified for a single-parameter delete.

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 description coverage is 100% — the schema already documents project_id as a uuid from create_short / list_projects. The description adds no further parameter meaning, 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 (delete) and resource (project) and immediately scopes it: the video, thumbnail and stored source go with it. That scope distinguishes it from sibling mutations like retry_project and reads like get_project, so an agent can route correctly without opening the schema.

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

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

Explicit when-not condition (not possible while the project is being made, JOB_IN_PROGRESS) plus the named alternative to run first (wait_for_project), and an explicit human-confirmation requirement before invoking. Both the blocker and the workaround are stated, not implied.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world), so the description is free to add domain behavior: it states the 2026 RPM basis, discloses the default originality assumption ('unless told the footage is the creator's own ... it assumes reworked third-party footage'), notes that 'flagged earns 0', and warns output is 'rough ranges, not a promise'. It does not describe the shape of the returned estimate, which would have pushed this higher.

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 in the first clause, then assumptions, then the disclaimer. Four sentences, no repetition. The trailing 'Pure math, rough ranges, not a promise. Free.' is terse but slightly fragmented marketing cadence rather than integrated prose.

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

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

For a 5-parameter, nested-object tool with no output schema, the description supplies the platform scope, the assumption defaults, the failure case ('flagged earns 0'), and the output nature (USD monthly ranges). It stops short of describing the estimate's structure or uncertainty band, which an agent previewing the result would find useful.

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 3 is the baseline, but the description explains the reasoning behind a key input: the originality enum's default of 'borderline' comes from Meta's March 2026 originality rule, and 'flagged earns 0'. That adds decision-relevant meaning the enum labels alone do not convey. Tier-mix normalization and niche defaults 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?

States a specific verb and resource ('Estimate monthly creator payouts (USD) for a view count') and enumerates the exact input dimensions (four platforms, audience tier, niche, originality) that define the tool. It is clearly distinct from the sibling estimate_credits, which audits credit spend rather than earnings.

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: you feed it a view count and format and get an earnings estimate. It never names a when-not condition or an alternative (e.g. compare against estimate_credits for cost planning), and 'Free' hints at the economics but is not framed as routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds a genuinely new behavioral fact — the call is 'Free' — and discloses that params must be supplied per action, which the annotations do not 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?

Purpose and cost/balance outcome are front-loaded, followed by a compact parenthetical action→param map. It is dense but wastes no sentences; the single long action enumeration is the only mild readability cost.

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

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

With no output schema, the description usefully signals the return semantics (credit cost plus whether the balance covers it). Combined with annotations covering safety and the schema covering the action enum and params, an agent has enough to call it correctly; only the exact response shape is unspecified.

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, but the description goes further by stating the required parameter combinations per action (clipper_analysis needs source_minutes; tts needs text or chars; studio needs model_key + model_params + count). That conditional requirement logic is absent from the schema, which only marks 'action' as required.

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 ('Estimate how many credits an action will cost') and adds the outcome dimension ('whether the current balance covers it'). An agent can immediately separate this pre-flight estimator from siblings like earnings_estimate or the actual generation tools such as generate_clips and studio_generate.

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 'before running it' establishes the trigger condition — call this prior to an expensive generation. The enumerated action list implicitly maps to the sibling tools that would otherwise be invoked (clips/generate_clips, tts/generate_voiceover, script/write_script, studio/studio_generate). It lacks an explicit 'do not use this to actually generate' exclusion, 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 only tell the agent this is a non-read-only, non-destructive operation. The description adds material behavior beyond that: per-clip credit cost with per-clip refunds on failure, and that it is asynchronous, returning project ids immediately rather than finished clips. These are exactly the economics and timing facts an agent needs before invoking a paid 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?

Two sentences with zero filler; the pipeline position is front-loaded, then cost, then the async hand-off. Every clause carries information an invoking agent needs.

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

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

With no output schema, the description compensates by explaining that the return value is project ids and how to consume them (wait_for_project / get_project for each). Combined with the cost/refund and async disclosure, 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 description coverage is 100%, so every parameter is already documented in the schema itself (including that caption_style overrides the plan style). The description adds no syntax, format, or constraint detail beyond the schema, 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 (render), the resource (chosen candidates of a ready plan), the output format (9:16 clips with captions), and its pipeline position (step 2/2 of AI Clipper). This clearly differentiates it from siblings start_clipper (step 1) and get_clip_plan (candidate source).

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 itself as step 2/2 of a multi-step flow and names the follow-up tools (wait_for_project / get_project) with the 'for each' caveat. It does not state a when-not condition or spell out the prerequisite that start_clipper and get_clip_plan must have run first, but the step numbering implies it strongly.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description goes meaningfully beyond them with cost (1 credit per started 100 characters), latency ("Instant"), and the output artifact with its 24 h signed-link expiry — the latter being essential since there is no output schema. The only gap is that it doesn't explain failure modes (e.g. text over 5,000 characters or an invalid voice_id).

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 plus four short clauses covering speed, price, and return format. Every element earns its place and the capability statement comes first.

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 generation tool with no output schema, the description supplies the details an agent otherwise could not know: cost model, synchronous/immediate nature, and the signed-link return with 24 h validity. Combined with 100% schema coverage and explicit annotations, nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so text, speed, language, voice_id, and idempotency_key are all documented in the schema itself. The description restates the character cap and points at the two lookup tools for voice_id/language, but adds no syntax or format detail beyond that, so the baseline 3 applies. Notably it does not mention the idempotency_key parameter at all, despite that being the mechanism that prevents double charging.

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 (turn text into), the resource (MP3 voiceover with an AI narrator voice), and the hard input ceiling (5,000 characters). No sibling in the list produces audio from text, so an agent can immediately tell this is the text-to-speech path rather than create_short or studio_generate.

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

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

It names the prerequisite lookups (list_voices for voice_id, list_languages for language) which is real routing help, but it never states when to prefer this over adjacent generation tools such as studio_generate or create_short, nor any when-not condition. Usage is implied by the capability statement rather than spelled out.

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, so safety is covered. The description adds genuinely useful context beyond that: the result is scoped to 'this API key', it is 'Free' (no credit cost), and it exposes current credit prices — cost/auth facts the annotations do not 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 verb and resource, then a compact enumeration of returned fields, closing with the usage cue. The parenthetical limits list is dense but every item is a substantive returned field 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?

With no output schema, the description carries the return-value burden and discharges it by enumerating the payload (balance, plan, limits, watermark, prices, billing link). Combined with annotations covering safety, an agent has everything needed to call it correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify beyond the schema; the baseline of 4 applies. No parameter-level claims are made or needed.

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

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

States a specific verb and resource ('Get the WowReveal account behind this API key') and enumerates the exact payload: credit balance, plan, plan limits, watermark, credit prices, billing link. No sibling tool does anything comparable, so an agent can distinguish it 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 clear contextual guidance — 'Call it first and before expensive jobs' — which orients the agent relative to the generation/estimation siblings. It stops short of naming a specific alternative or stating exclusions, but the ordering advice is 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?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds behavior they cannot express: the status lifecycle (queued → analyzing → ready | failed | expired), the 7-day retention window (expiresAt), and that the operation is free. These are meaningful operational traits beyond the 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-loads the purpose, then the return shape, then the workflow hand-off and retention/cost notes. Dense and waste-free with no redundant restatement of the tool name.

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

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

With no output schema, the description fully describes the return payload (candidate id/title/score range/timecodes/reason) and the terminal states, which is exactly the burden the missing output schema places on it. An agent has everything needed to poll and interpret results.

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

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

Schema description coverage is 100% with a single documented plan_id, so the schema carries the parameter burden. The description adds no syntax or format detail about plan_id, 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 ('Get an AI Clipper plan') and immediately enumerates what it returns (status, progress, candidates). It distinguishes itself from workflow neighbors by naming the next step (generate_clips) and by describing the status state machine, so an agent can place it in the pipeline 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?

Clearly establishes the downstream step ('Pass the chosen candidate ids to generate_clips'), and the schema ties plan_id to start_clipper, effectively defining when this tool is used. It lacks an explicit 'do not call before start_clipper' exclusion, but the surrounding context is unambiguous.

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 behavior, so the description's added value is the operational context: signed links expire after 24 h, failed generations are refunded automatically, and the call is free. These are genuine traits an agent needs for retry and cost decisions, though polling cadence or link consumability is not addressed.

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 front-loads the resource and return contents (status, then links), with refund and pricing caveats appended as short clauses. Every clause carries information; nothing is redundant with the name or title.

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

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

With no output schema, the description must describe the return value and it does: status enumeration plus signed 24-hour links. Combined with the refund and free-cost notes for a single-parameter read tool, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100% and the generation_id field is documented as coming from studio_generate, so the schema carries the parameter semantics. The description adds no format, length, or sourcing detail beyond that, making the baseline 3 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?

States a specific verb and resource ('Get an AI Studio generation') and immediately enumerates what is retrieved: status states and signed output links. The 'get' vs 'generate' contrast with the sibling studio_generate is implicit but unambiguous, and the status lifecycle makes the resource concrete.

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 status progression (queued → running → complete | failed) implies this is a polling tool to call after studio_generate, but the description never explicitly says when to call it or when to stop polling. No alternatives are named or excluded, 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 read-only, idempotent and non-destructive, so the safety profile needs no restating. The description adds real behavioral value beyond them: the status state machine (queued → processing → complete | failed), that videoUrl/downloadUrl are signed and expire after 24 h, and that the call is 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?

A single dense sentence, front-loaded with the verb and resource, with the return payload enumerated afterwards. Every clause carries information, though the packed parenthetical list of fields is slightly heavy to parse.

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 correctly carries the return-value burden and enumerates fields, statuses and URL expiry. It leaves minor gaps: whether URLs are null pre-completion (only implied by 'when complete') and whether failed projects expose error detail.

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

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

Schema description coverage is 100%, and the schema already explains that project_id is a uuid returned by create_short / list_projects. The description adds no format, constraint or sourcing detail beyond that, so the baseline of 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 ('Get one project') and names the three entity subtypes (short, clip, compilation), which distinguishes it from list_projects, get_clip_plan and get_generation. The enumerated return fields make the tool's scope unmistakable.

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

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

Usage is only implied: an agent can infer this is the single-project status poll, but the description never says when to use it instead of wait_for_project, list_projects or get_generation. The 'Free' note hints at a cost trade-off against sibling tools but does not spell it out.

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 annotations: URL images are downloaded server-side, private/local addresses are refused, accepted formats and 10 MB limit are given, the return value upload_id is explained, and unused imports are deleted after 48 hours. These are exactly the operational details an agent needs for safe invocation.

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

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

The description is front-loaded with the core action and input options, then covers return value, usage, retention, and cost in a compact flow. Every sentence contributes operational information without repetition or 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 three-parameter import tool with no output schema, the description is complete: it explains accepted inputs, constraints, return value, downstream use, retention behavior, and cost. Annotations already cover safety properties, and the description supplies the remaining context an agent needs.

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 all three parameters. The description still adds useful semantics for url and data_base64, including public HTTPS requirement, accepted formats, size limit, server-side download behavior, and data: address support. It does not add detail for the name parameter, but the schema covers it adequately.

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: importing an image into WowReveal without a file upload. It distinguishes the two accepted input modes, url and data_base64, and explains the resulting upload_id, so an agent can immediately understand what the tool does.

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

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

It clearly explains when to use the tool: when the caller has a public image URL or base64 image data rather than a file upload. It also explains downstream usage of upload_id in studio_generate and other tools that accept upload_id. It does not explicitly name when not to use it versus sibling generation tools, which keeps it below 5.

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

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

Annotations already establish the read-only, idempotent, non-destructive profile, so the bar is lower. The description still adds real context: each item carries a signed preview link valid 24 h, isDefault marks the fallback logo, and the call is free — details not derivable 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-loads the core purpose, then usage, then return specifics, with each sentence contributing distinct information. It is dense and slightly run-on, 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?

With no output schema, the description carries the burden of describing returns and does so reasonably (signed preview link with validity window, isDefault flag). For a one-optional-param list tool this is nearly complete, though it could clarify whether results are paginated or grouped by kind.

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

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

Schema description coverage is 100% and the single 'kind' enum already documents 'Only logos or only music.' The description mentions the two asset categories but adds no filtering syntax or behavior beyond what the schema states, so the baseline of 3 is correct.

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 logos and music tracks this account can put in a video') and names the two sources (own Brand Kit + free platform library), which clearly separates it from the many other list_* siblings. An agent knows exactly what comes back.

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 routes the agent downstream: 'Use a logo id as logo_asset_id... in create_short / start_clipper / create_compilation,' giving clear context for why and when this tool is called relative to the creation tools. It stops short of explicit when-not guidance or naming a competing list tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds a genuinely useful behavioral fact beyond them: the call is 'Free', which matters in an API whose siblings include estimate_credits and earnings_estimate. It doesn't mention caching/staleness of the style 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 short sentences, front-loaded with what is listed and followed by the actionable how-to-use detail. Every clause earns its place, including the return-field list and the cost 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?

With no output schema, the description compensates by naming the returned fields (id, name, animation) and the consuming parameter. For a zero-argument, read-only lookup tool this is fully 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?

Zero parameters, so the baseline is 4 per the rubric; there is no parameter semantics for the description to explain. The description is clear that the tool needs no input and describes what comes back instead.

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 ('List the animated caption styles') and even enumerates the returned fields (id, name, animation). No sibling in the list serves this function, so an agent can immediately distinguish it from list_voices, list_templates, or list_languages.

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

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

It gives concrete downstream usage: the returned id is the value to pass as `caption_style` in create_short / start_clipper. That tells the agent exactly why and when to call this tool. There is no explicit 'when not to use' clause, but for a pure lookup with no alternatives that omission is minor.

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 guarantee readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavioral context: results are newest-first, pagination uses the returned nextCursor, links are signed and expire in 24h, and the call is free (no credit cost). Only the exact page-size default (10) lives in the schema rather than the prose.

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

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

A single dense sentence leads with the verb and resource, then tacks on ordering, payload, pagination, and cost in a tight clause chain 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 carries the return-value burden and does so reasonably: it names status and signed links (with 24h validity) and the pagination cursor. It stops short of enumerating the full item fields, but for a list endpoint it is nearly sufficient.

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

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

Schema description coverage is 100%, so the schema already documents kind, limit, cursor, and status enums. The description only echoes the cursor/nextCursor round-trip and adds no filter syntax or format meaning beyond the schema, making the baseline 3 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?

States a specific verb and resource ('List the account's AI Studio generations') plus the ordering ('newest first'), the payload ('status and signed output links'), and the pagination mechanism. This clearly distinguishes it from the sibling get_generation, which fetches a single generation.

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

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

The description implies listing usage and explains pagination flow via 'nextCursor', but never says when to prefer this over get_generation or list_projects, nor any preconditions. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by declaring "Free" — notable in a tool set that includes estimate_credits and earnings_estimate — and by disclosing the shape of the returned pairs (code + name).

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

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

A single front-loaded sentence: verb, resource, scope, the practical instruction for the code, and the cost note. No filler and no repetition of the title.

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

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

With no input params and no output schema, the description carries the return-shape burden itself and does so ("code + name"), while annotations cover the read-only safety profile. Nothing an agent needs to call and use this tool 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?

There are zero parameters, so the baseline is 4. The description's mention of "code + name" describes the response rather than inputs, but it is still useful framing for a no-arg enumeration tool.

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

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

States a specific verb and resource (list languages) and scopes it precisely: the languages WowReveal can write scripts, voiceovers, captions, titles and post kits in. That scope makes it distinguishable from the other list_* siblings (list_voices, list_caption_styles, list_templates), which cover different resource families.

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 the code as `language`" tells the agent both why it would call this tool and how the returned value feeds downstream calls. It stops short of explicitly naming the alternative tools that consume a language (write_script, generate_voiceover) or stating when not to call it, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds genuinely non-redundant behavior: results are sorted newest first, each row carries status and signed video links, and the call is free (no credit consumption).

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 with zero filler: what is returned first, pagination second, cost last. Front-loaded and every clause carries information an agent can act on.

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 names the returned fields (status, signed video links) and the ordering, plus the cost model. Remaining gaps are minor — no mention of what an empty page or expired links imply, and no explicit pointer to get_project for single-item retrieval.

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 all five parameters are already documented (tool, limit, query, cursor, status with enums). The description only echoes cursor semantics ('nextCursor'), adding no filtering or formatting detail beyond the schema — the baseline 3 for schema-complete tools.

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: 'List the account's projects', plus scope (account-level), ordering (newest first), and payload contents (status, signed video links). It is clearly distinct from the singular get_project sibling by plural/list framing, but never names or contrasts the alternative explicitly.

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

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

Usage is implied rather than stated: pagination mechanics ('Paginate with cursor (nextCursor)') and the 'Free' cost note hint at when this is attractive over credit-spending generation tools. There is no explicit when-to-use/when-not guidance or routing to siblings like get_project for a single record.

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), so the bar is lower. The description adds a genuinely useful behavioral fact not in annotations — 'Free' (no credit cost) — plus a detailed account of what the response contains, which matters since there is no output 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?

A single dense but front-loaded sentence: the action and scope come first, followed by the returned fields, the integration hint, and the cost note. Every clause earns its place, though the field enumeration makes it heavier than strictly necessary.

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

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

With no output schema, the description compensates fully by enumerating the return payload (key, vendor, kind, modes, params with defaults, required inputs, credit price, plan unlock) and by naming the downstream tool that consumes the key. An agent has everything needed to call and use 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 description coverage is 100% for the single optional 'kind' enum filter, so the schema carries parameter meaning. The description uses 'kind' only as a returned field, not to explain the filter parameter, so it adds nothing beyond the schema — 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 ('List') plus the exact resource ('AI Studio image/video generation models available to this account') and enumerates the returned fields, so it is clearly distinguishable from sibling list tools like list_studio_presets or list_voices. An agent knows precisely what this returns 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?

Explicitly routes the agent forward: 'Use the key as model_key in studio_generate,' which is the primary consumer of this tool. It also notes the tool is free, implying no credit cost, but gives no when-not-to-use guidance or prerequisites.

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

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

Annotations already declare read-only, idempotent, closed-world behavior. The description adds genuinely new context beyond them: the operation is free (no credit consumption) and the response includes model, default params and a prompt template with {subject} placeholders.

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

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

Two tight sentences: what is listed first, how to use the output second. No filler, and the most decision-relevant content is front-loaded.

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 adequately characterizes the returned fields and the placeholder convention. Minor gap: nothing is said about result size, ordering or whether the full preset set is returned.

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

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

Schema description coverage is 100% and the category parameter already carries example values (camera, transition, vfx, viral, product, cover). The description's category list largely mirrors that, so it adds little 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?

Specific verb ("List") plus resource ("AI Studio effect presets") with an explicit enumeration of the preset families covered. It also states the payload shape (model, default params, prompt template), which cleanly separates it from siblings like list_studio_models and list_templates.

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 tells the agent the downstream workflow explicitly: take the preset_id and pass it to studio_generate with a subject in prompt. That is actionable guidance, though it never states when to prefer this over list_studio_models or list_templates.

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 adds two pieces of genuinely new context: the returned fields (not covered by an output schema) and the cost signal 'Free,' which no annotation conveys.

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

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

Two tight sentences: the purpose and return contents come first, the create_short handoff second, and the cost note trails. Every clause carries information with no 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 names the fields returned and flags the zero-cost nature, and annotations cover the safety profile, so an agent has what it needs. Remaining minor gaps (pagination, exact return shape) are not critical for a free read-only list 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 description coverage is 100% and both parameters (tool, locale) are documented in the schema with enums, so the schema carries the semantic burden. The description adds nothing about the tool/locale filters, so the 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?

States a specific verb ('List') and resource ('niche templates'), then enumerates concrete categories (talent show auditions, haircut transformations, etc.) and the fields returned (tool, genre, default settings, suggested trend searches). An agent can tell exactly what this returns and, via the create_short cross-reference, where it fits among siblings like list_caption_styles.

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

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

The description tells the agent the downstream workflow: 'Pass a template id as template_id to create_short to apply its defaults,' which clarifies when this tool is useful (as a discovery step before create_short). It does not state exclusions, but no competing template-listing alternative exists among the siblings, so the practical gap is small.

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

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

Annotations already establish the safe-read profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavior beyond that: recommended voices are ordered first, all voices cover all content languages, and the listing is 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?

A single dense sentence with the primary purpose front-loaded and the secondary facts (ordering, language coverage, cost) trailing. 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 carries more burden, and it does specify that entries include voice_id plus ordering and language behavior. It does not describe pagination or the rest of a voice's returned fields, a minor gap for a two-parameter listing tool.

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

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

Schema description coverage is 100%, so both limit and recommended_only are already documented; baseline 3 applies. The mention that 'recommended storytelling voices come first' loosely connects to recommended_only but adds no format or syntax 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?

States a specific verb (list) and resource (AI narrator voices) and explicitly ties the result to its consumers by naming voice_id as the input for create_short and generate_voiceover. This distinguishes it from sibling list tools like list_languages or list_caption_styles.

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

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

The description makes the use case clear: it returns voice_ids consumed by create_short and generate_voiceover, so an agent knows when to call it. It stops short of stating when *not* to use it or naming an explicit alternative.

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 credit refund-on-failure and re-charge-at-current-price behavior, with per-tool prices, plus the async immediate-return semantics. The only minor tension is that idempotentHint=false while the schema exposes an idempotency_key — the description never resolves how those interact, though it does not contradict the annotation outright.

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 its preconditions, and every clause is functional. The parenthetical price enumeration (story 8, transformation 14, clips 3, clip 2, compilation 8) is the densest part and could be deferred, but it is cost information an agent may need before charging a user.

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 async, credit-charging mutation with no output schema, the description covers the prerequisites, the billing model, the failure modes, and the exact next step. Nothing an agent needs in order to call it safely 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 both parameters (project_id and idempotency_key, including the 24 h dedupe window) are already fully documented in the schema. The description adds no additional parameter-level meaning, 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?

Opens with a specific verb+resource ('Run a failed project ... again') and immediately narrows scope with preconditions (status "failed", retryable=true) and the supported project types (story, transformation, clips, clip, compilation). An agent can distinguish it from create_short/generate_clips 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 an explicit pre-call check ('Check errorCode first') and enumerates the exact error codes that make a retry pointless, which is a genuine when-not-to-use rule. It also directs the follow-up flow ('Returns at once — then wait_for_project'), routing the agent to the correct sibling for polling.

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 behavior the annotations cannot express: a 1-credit cost, a 12-hour cache window that makes repeat searches free, and the notable policy that a zero-result search is not charged. This is exactly the billing/rate context an agent needs before spending credits, and it 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-loaded with purpose and scope, and every clause carries information (inputs, ranking, cost model). It is a single dense sentence packing several ideas with dashes, which is efficient but slightly crammed rather than maximally scannable.

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

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

For a 6-parameter, all-optional search with no output schema, the description covers purpose, inputs, ranking, and cost. Return shape is not described, but ranking (views per day) is disclosed and the output schema's absence is only a minor gap given how much is already explained.

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 meaning beyond it: the niche parameter is a template id that triggers its own curated searches (example: talent-show) and is presented as an alternative to the free query. Ranking semantics (views per day) are also stated, which the schema does not convey.

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

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

States a specific verb+resource ('Find recent viral YouTube videos') plus the ranking criterion (views per day) and the scope (for a niche template id or free query). It also names downstream consumers (create_short / start_clipper), which separates it from the listing/generation siblings at a glance.

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?

Explains when to reach for it (sourcing material for create_short / start_clipper) and gives the two input modes: a curated niche template id or a free query. It does not state explicit exclusions, e.g. when to prefer get_clip_plan or list_templates instead, so it falls short of full routing guidance.

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

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

Annotations only say non-read-only, open-world, non-idempotent; the description adds the material facts an agent needs: it is async with a few-minute latency, returns immediately with a plan_id, costs 6 credits per started 30 minutes of source, and credits are refunded on failure. Credit pricing and latency are behaviors nothing else in the structured data conveys.

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?

Roughly three sentences, front-loaded with the step label and the core action, then sequencing, then cost. Parentheticals (source types, credit rate) are dense but each carries distinct information and none is redundant with the schema.

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 async job with no output schema, the description covers the essential unknowns: what it returns (plan_id), how long it takes, what it costs, and the exact next call. There is no output schema to explain return values, and the description accounts for that gap.

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

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

Schema description coverage is 100%, so every parameter (url, upload_id, layout, caption_style, logo_asset_id, idempotency_key, etc.) is already documented in-schema. The description only echoes max_clips and implies the cost scales with source duration; it adds no format or interaction detail beyond the schema, 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 (analyse a long video, propose up to max_clips viral clips) and scopes the accepted source types (podcast, interview, stream, show; link or upload). It also positions itself as step 1/2 of a named pipeline, which distinguishes it from generate_clips and get_clip_plan 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?

Explicitly routes the agent: returns plan_id immediately, poll get_clip_plan until status is "ready", then call generate_clips. That is a clear when-to-use and a named alternative. It stops short of stating when not to use it (e.g. pre-existing plans or short sources that belong to create_short), so it is not fully exhaustive.

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

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

Annotations declare a non-read-only, non-idempotent, non-destructive call, and the description goes well beyond them by disclosing cost semantics (price × count, verifiable via estimate_credits), refunds on failure, and the async contract (returns ids immediately, poll get_generation). The idempotency_key note is stated as an opt-in dedupe mechanism rather than a claim of inherent idempotency, so it does not contradict idempotentHint=false, though the interaction could be spelled out more clearly.

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 core purpose, then branching, then prerequisites, then cost and async behavior. Every sentence carries information, though the preset parenthetical and the start-image enumeration make it heavier than strictly needed for fast 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?

With no output schema, the description correctly explains the return contract (generation ids returned immediately, completion via get_generation polling). Combined with cost, refund, and input-source coverage, an agent has everything needed to call this 12-parameter, zero-required tool correctly on the first attempt.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: that model_key and params default to the preset's values when preset_id is supplied, and that prompt becomes the {subject} filler under a preset. It does not clarify edge cases like the relationship between start_upload_id, start_generation_id, and reference_upload_ids beyond the schema text.

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

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

States a specific verb and resource (generate AI images or videos) plus the async nature in the title. It names the exact sibling tools (list_studio_models, list_studio_presets) that supply inputs, so an agent can distinguish this from create_cover, generate_clips, or create_short 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 between two paths (model vs preset) and states the condition for each. It also specifies when a start image is required (image-to-video, edits, image presets needing needsImage) and enumerates the three acceptable sources, including the alternative tool import_image. Nothing 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.

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds real behavioral context beyond them: the 50 s cap, the two possible return shapes, the timedOut restart loop, and cost ('Free'). It still does not describe failure/error surfaces or credit-consumption edge cases, so it falls short of exhaustive.

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

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

Three sentences, front-loaded with the wait semantics and terminal conditions, then the timeout fallback, then the sibling comparison. Every clause carries information; 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?

There is no output schema, so the description carries the return-value burden — and it does, specifying the completed project with signed video link versus a progress snapshot with timedOut=true. Combined with the annotations and full schema coverage, an agent has everything needed to call and re-call this tool correctly.

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

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

Schema coverage is 100%: both parameters, their ranges (1–50), the default (45), and the project_id provenance are documented in the schema itself. The description repeats the 50 s ceiling but adds no format or semantic detail beyond what the schema already provides, 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 (wait for a project), the terminal conditions (complete or failed), and the return payload (project with signed video link). Sibling get_project is explicitly named as the thing this replaces, 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?

Explicit when-to-use ('instead of polling get_project in a tight loop') and an explicit retry protocol for the timeout case ('returns the current progress with timedOut=true — call it again'). Both the alternative and the exclusion condition are named.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description still adds genuinely useful non-annotation context: it costs 1 credit and takes roughly 1–2 minutes for video input, and it notes the AI actually watches the supplied video. Slight blemish: 'Instant (up to ~1–2 min for videos)' is internally inconsistent about latency.

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 the verb and resource first; the parentheticals about video watching and timing earn their space. Minor waste and awkwardness in 'Costs 1 credit(s)' and the self-contradicting 'Instant (...1–2 min)'.

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 8 params, 17 enum languages, annotations present and no output schema, the description covers inputs, cost, latency and the nature of the result well. The notable gap is that nothing says what comes back — a script string, an object with fields, an id to poll — which is the one thing an agent still has to guess without an output 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 100%, so the baseline is 3 and the schema already carries enum and format detail. The description still adds meaning the schema does not: target_seconds sizes the output rather than merely bounding it, and 'the AI watches it' explains why url/upload_id matter. It stops short of explaining genre's effect on output beyond naming 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 specific verb and resource ('Write a viral voiceover/narration script') and immediately disambiguates the two accepted inputs: a video via url/upload_id, or a text to rewrite/expand. An agent can tell this produces a script, not audio or a finished video, which separates it from generate_voiceover or create_short 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?

It implies when the tool applies ('for a video ... or rewrite/expand a text') and makes the url/upload_id vs text inputs mutually exclusive, which is real usage guidance. However it never names a sibling alternative or states when NOT to reach for this over generate_voiceover, create_short or studio_generate, leaving routing to inference.

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