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

No annotations are provided, so the description must fully disclose behavior. It mentions a cost range of 10-1000 tokens but does not cover other important traits like statelessness, rate limits, error handling, or authentication requirements.

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

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

The description is three sentences front-loaded with the core function. No filler: each sentence serves a purpose (main action, usage context, cost hint).

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 chat API tool, the description covers purpose, usage guidance, and cost. It lacks explicit response format details, but given no output schema, the default text response is reasonably inferred. Sibling tools are non-overlapping.

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 descriptions for both parameters. The tool description adds context by specifying the default model and providing model ID examples, enhancing understanding beyond 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?

The description clearly states the verb 'Send a prompt' and the resource 'ANY chat model on avots.ai', listing multiple model families. It distinguishes from sibling tools by framing it as delegation to other models, e.g., 'have GPT-5.5 Pro double-check this reasoning'.

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 explicitly says when to use: 'when you... want to delegate a sub-task to a different model' and gives concrete examples. However, it does not explicitly state when not to use or list alternative tools for similar tasks.

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?

No annotations provided, so description carries full burden. It discloses that the tool is free ('Free (no tokens consumed)') and returns checkout URLs. No contradictions or omissions.

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?

Description is front-loaded with main purpose, but includes specific pricing details that lengthen it. Still every sentence adds value, though could be slightly more streamlined.

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?

Completely covers return values (balance, plans, prices, checkout URLs) and usage context. With no output schema, description provides all necessary information for an agent to invoke 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?

Tool has zero parameters; baseline is 4. Description adds meaning by detailing what is returned (balance + plans with prices and checkout URLs), but no parameter info 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?

The description clearly states the tool returns both token balance and the full pricing catalog with checkout URLs. It specifies verb 'Get' and resource 'avots.ai token balance AND the FULL pricing catalog', distinguishing it from sibling tools.

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

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

Explicitly lists when to use: when user asks about balance/plans or runs out of balance. Also includes a negative constraint: 'Do NOT search the web for our pricing—this tool is the single source of truth.'

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?

No annotations provided, but description fully discloses behavior: free tokens, status meanings, response content, audio metadata absence, and provider queue realities.

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?

Description is slightly verbose but every sentence serves a purpose. Could be tightened (e.g., merge polling cadence statements), but overall efficient.

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, description covers all critical aspects: polling behavior, status interpretation, error handling, and caveats about audio. Complete for a polling 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 100% for the single parameter; description adds minimal extra context beyond schema (mentions UUID source). 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?

Clearly states the tool polls async generation jobs, specifies source tools (generate_video, avots web/Telegram), and distinguishes from sibling tools by function.

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 explicit polling cadence, timeout advice, and crucial instructions on handling statuses (e.g., not reporting failure on 'queued', not claiming audio presence).

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 no annotations provided, the description carries full burden for behavioral disclosure. It details free vs paid modes, the two-step generation workflow with confirmed flick, face-checking, constraints (single person, facing camera, head-and-shoulders), and the return format. It does not mention idempotency or error behavior, but for a creation tool these are acceptable gaps.

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 purpose, then details usage modes, constraints, and return value. It is somewhat lengthy but every sentence adds necessary context. Minor improvement could split into shorter paragraphs.

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

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

Given 6 parameters (1 required), no output schema, the description covers the creation workflow, parameter choices, cost implications, constraints, and integration with sibling tools (generate_talking_avatar, face_swap_video, list_avatars). It is fully self-contained and actionable for an AI agent.

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 significant value: explains the two-step process for portrait_prompt, typical token cost, that image_url accepts avots file UUIDs, and that voice is used automatically by downstream tools. This goes beyond schema explanations.

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 clearly states the tool saves an 'AVATAR (face identity)' for reuse in talking-avatar and face-swap videos, and distinguishes it from sibling tools like list_avatars (listing created avatars) and generate_talking_avatar (using an avatar). The verb 'save' and specific resource 'avatar' are precise.

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

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

The description explains when to use image_url (ready photo, free) vs portrait_prompt (generate, costs tokens, two-step) and mentions the 20-avatar account limit. It does not explicitly exclude cases where the tool should not be used, but provides sufficient context for proper selection among 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?

No annotations are provided, so the description carries full burden. It discloses cost (~5⚡ for LLM extraction), backend behavior (linked Apple Calendar, Google Calendar, or ics file), timezone fallback chain, and return format. No contradictions.

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 detailed and structured, but slightly verbose. It could be more concise while retaining key information, but overall it is well-organized with clear sections.

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

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

Given the complexity of the tool (multiple backends, timezone handling, cost), the description covers all necessary aspects comprehensively. It explains the return value in detail, compensating for the absence of 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%, and the description adds significant value beyond the schema: it explains the timezone parameter's usage ('ALWAYS pass timezone=IANA when you know it') and provides examples and limitations (recurring not supported) for the description 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 clearly states the tool's purpose: 'Schedule a calendar event from a natural-language description'. The verb 'schedule' and resource 'calendar event' are specific, and the description distinguishes it from sibling tools (e.g., create_avatar, generate_image) by focusing on calendar scheduling.

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

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

The description provides explicit guidance on when to use: when the user provides a natural-language description to schedule an event. It explains timezone handling and when to pass timezone. However, it does not explicitly state when not to use the tool or mention 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?

No annotations are provided, so the description must disclose behavior. It covers the rendering process (Ken Burns, crossfade), energy cost (~200), async nature with polling instructions, and output format. It lacks mention of potential failure modes or error handling, but otherwise transparent.

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, well-structured paragraph. It front-loads the main purpose, then details effects, async behavior, and usage guidance. Every sentence serves a purpose with no redundancy.

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

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

Given no output schema, the description adequately covers return value (hosted MP4 URL) and polling flow. It fully explains the 3 parameters and async workflow. The complexity is moderate and all key aspects are addressed.

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%, but description adds context: image_urls order matters, external URLs are fetched and stored, music presets are listed with default, aspect ratios have use-case hints (vertical for Reels). This goes beyond raw schema definitions.

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 clearly states it assembles a slideshow video from photos with specific effects (Ken Burns, crossfade). It distinguishes from sibling tools like generate_video (AI video) and create_travel_poster (static image) by specifying the photo montage use 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?

The description explicitly says 'Use when the user wants a photo montage / slideshow / turn these pictures into a video / reel.' It provides clear usage context but does not mention when *not* to use or compare with alternatives, though sibling tools exist.

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 no annotations, the description fully discloses synchronous behavior ('returns a hosted image URL directly, NO check_job needed'), token cost (~200-500), and that a face-only photo gets a full body drawn. It also explains rendering quality variations for curated vs. non-curated countries.

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 detailed yet relatively concise, packing significant information into a few sentences. It front-loads the core purpose and key differentiators, though some details (curated list) could be streamlined.

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 3 parameters, no output schema, and no annotations, the description covers all necessary aspects: purpose, parameters, behavioral traits, cost, limitations, and integration with a sibling tool. It leaves no major gaps.

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%, providing baseline 3. The description adds value by explaining each parameter's role: country can be any but best for curated set, aspect defaults with two options, image_url accepts external or hosted and supports face-only crops. This goes beyond the minimal schema descriptions.

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

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

The description specifies a very distinctive use case ('turn a face photo into a vintage TRAVEL POSTER') with concrete visual elements (map, landmarks, passport, stamps, compass, serif caps). It clearly distinguishes from sibling tools like generate_image or create_montage by describing a unique, branded style.

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

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

Explicitly states when to use (create a travel poster) and provides a pointer to an alternative: pass the returned URL to generate_video for animation. It also notes that 24 curated countries render best but any country works, helping the agent decide. Missing a clear 'when not to use' 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?

With no annotations, the description fully discloses async polling, two-step flow, cost range, and the critical limitation of transferring the whole person. Instructions like 'Tell the user this if their source looks full-body' show high transparency.

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

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

Well-structured with clear sections (purpose, async, cost, two-step, important, use cases). Every sentence is informative; no fluff. Front-loads the core purpose.

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 all necessary aspects: async behavior, polling, cost estimation, confirmation flow, input requirements, and use cases. No output schema is compensated by detailed explanation of return behavior (job_id, preview card, cost).

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%, but the description adds significant context: explains the confirmed parameter's role in the two-step flow, specifies 'head-and-shoulders portrait' for face_image_url, and mentions avatar reuse. Exceeds baseline of 3.

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 clearly states the tool's function: 'Swap a face in a target VIDEO with a source face from a photo, keeping the original motion + scene'. It distinguishes from siblings like generate_video and lipsync_video by specifying the face-swap operation.

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

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

Provides explicit use cases ('put my face in this video') and important prerequisites (head-and-shoulders portrait). Mentions the two-step confirmation flow, but lacks explicit 'when not to use' or alternative tools beyond referencing generate_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?

No annotations are provided, so the description carries full burden. It fully discloses async behavior (returns job_id, must poll check_job), expected cost range (50-800 tokens), return format (hosted MP3/WAV URLs), and model-specific behaviors (e.g., TTS auto-detects language, voice clones). No contradictions.

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 relatively long but every sentence adds value. It is front-loaded with the core purpose and async note, then organized into music vs TTS sections. A slight improvement would be using bullet points for the model lists, but it is still effective.

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

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

Given the tool's complexity (async, multiple models, different usage patterns) and the absence of an output schema, the description covers all necessary aspects: purpose, usage, parameters, behavioral expectations, and limitations. It is 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%, but the description adds substantial meaning: it explains the default model, lists available music models, details TTS voice presets and cloned voice usage, clarifies that lyrics are optional for music, and sets duration constraints. This goes well beyond the schema's minimal descriptions.

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

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

The description clearly states 'Generate music OR spoken voice / narration (fal:* models only)', which is a specific verb-resource combination. It distinguishes from sibling tools like generate_image or generate_video by focusing on audio generation and detailing two distinct use cases.

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

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

The description provides explicit when-to-use guidance: music models vs TTS model, with model IDs listed. It advises against using non-fal models (OpenAI/Google) and warns about brand terms causing 422 errors. It also gives prompt construction tips for TTS (read verbatim) and music (genre, mood, etc.).

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?

No annotations were provided, but the description fully compensates by detailing blocking times (5-60s), return format (image content block + hosted URL), cost (200-500 tokens), async handling for Fal models, and UX behavior on Claude.ai. All behavioral traits are transparently disclosed without contradiction.

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 lengthy but every sentence adds unique information. While front-loaded with purpose, it could be more organized (e.g., bullet points for aliases). However, the detail is justified given the tool's complexity and many model options.

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 what is returned (image block + URL) and how to handle it. It covers blocking behavior, cost, model selection, and UX instructions. All essential aspects for correct agent invocation are addressed.

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 100% schema description coverage, baseline is 3, but the description adds significant value: model parameter includes aliases and task-based selection criteria; prompt parameter includes composition advice; num_images and aspect_ratio have defaults and limits reinforced. This enriches the schema considerably.

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 begins with a clear verb+resource: 'Generate one or more images from a text prompt.' The tool's purpose is explicitly stated and easily distinguished from sibling tools (video, audio, avatar generators).

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?

Extensive guidance is provided: explicit use cases (pictures, photos, logos, etc.), model selection criteria by task (e.g., text-in-image, vector, photoreal), user aliases, and even what NOT to do (avoid re-embedding the image). The description leaves no ambiguity about when and how to use this 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?

With no annotations, the description fully discloses behavior: async nature, slow rendering (especially HD/OmniHuman), token reservation process, cost preview, returned job_id and MP4 URL, auto language detection, and that portrait generation varies slightly per call. It also clarifies the mutual exclusivity of 'avatar' and 'portrait_prompt'.

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

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

The description is well-structured with bolded key terms (ASYNC, TWO-STEP FLOW) and clear sections. It is slightly lengthy but every sentence adds necessary context. The front-loading of the main purpose and then detailed steps is effective. Minor redundancy (e.g., 'returns a hosted MP4 URL' is clear from context) prevents a perfect 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 a tool with 7 parameters, async processing, and a two-step flow, the description is comprehensive. It covers cost, token reservation, polling necessity, voice options, avatar reuse, and even provides an example portrait prompt. No output schema exists, but the return values (job_id, MP4 URL) are described sufficiently.

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%, but the description adds significant value beyond schema: explains the two-step flow's role of 'confirmed', provides voice preset names and cloned voice behavior, clarifies default voice inheritance from avatar, and details the mutual exclusivity of 'avatar' and 'portrait_prompt'. This extra context is crucial for proper usage.

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 clearly states it generates a short video of a portrait speaking user text, a distinct function from siblings like 'lipsync_video' (which expects an existing video) and 'generate_video' (generic). The specific verb 'generate_talking_avatar' and the explanation of the two-step flow make the purpose unambiguous.

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

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

The description explicitly details a two-step flow (preview cost, then submit with confirmation) and explains when to use 'avatar' vs 'portrait_prompt' for consistency. It also mentions polling requirements. However, it does not explicitly state when not to use this tool (e.g., if a simple lip-sync on an existing video is needed), leaving a small gap.

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

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

With no annotations, the description fully discloses async behavior, polling requirement, cost implications, two-step confirmation, model aliases, audio flag limitations, and error behavior. It explains the 'confirmed' parameter's role and that preview doesn't reserve tokens. No contradictions.

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 long but well-structured with clear sections (ASYNC, TWO-STEP FLOW, ON SUBMIT ERROR, user aliases, model families). Every sentence serves a purpose. Could be slightly tighter but not wasteful given complexity.

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 async job lifecycle, return values (job_id, preview card, alternatives), cost, error handling, and user aliases. With no output schema, it explains what to expect. Sibling tools list contextualizes it. The description is complete for the tool's complexity.

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 adds significant value: explains audio flag nuance (request vs actual audio), model defaults and aliases, confirmed flag semantics, image_url behavior (auto i2v swap), resolution and aspect ratio defaults. Each parameter gets extra context 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 clearly states the tool submits a video generation job, is async, and returns a job_id. It distinguishes itself from siblings like generate_audio and generate_image by listing video-related use cases (animations, clips, reels). The verb 'Submit' and resource 'video generation job' are specific.

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

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

Provides explicit two-step flow (preview vs submit), when to poll check_job, cost range, model alternatives, error handling (no auto-switch), and duration expectations. It tells when NOT to use (don't give up early, don't claim no audio based on flag). The alternative tools are implied through sibling list and context.

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?

No annotations are provided, so the description carries full burden. It fully discloses async behavior (returns job_id, poll check_job), the cost preview step, duration and resolution constraints, aspect ratio behavior for generated vs uploaded characters, and the two-step flow. This is highly transparent.

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 comprehensive but slightly verbose; some sentences could be tightened. However, it front-loads the core purpose and differentiates from siblings early, and uses clear structure with steps and formatting. Minor redundancy exists (e.g., mentioning resolution twice).

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

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

Given 7 parameters, no output schema, and no annotations, the description thoroughly covers purpose, parameters, behavior, flow, and limitations. Every parameter is explained with examples, and the two-step flow is clearly documented. No gaps remain.

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%, but the description adds substantial meaning beyond the schema: it explains how topic is expanded into a punchy line, the interplay between character and character_url, aspect ratio application differences, and the confirmed parameter's role in the two-step preview/submit flow.

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 explicitly states the tool creates a short vertical talking-head vlog clip for Shorts/TikTok/Reels, with audio and lip-sync. It distinguishes itself from generate_talking_avatar by explaining that generate_vlog writes the script from a topic, while the sibling reads exact text.

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

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

The description provides explicit when-to-use and when-not-to-use guidance by contrasting with generate_talking_avatar. It also details the two-step confirmation flow (preview without confirmed, submit with confirmed=true), which is a crucial usage instruction.

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?

No annotations provided, so description carries full burden. It explains async nature (job_id, polling check_job), hosted MP4 URL, two-step flow with confirmation and cost estimate, token reservation, and that longer clips are rejected. Also details Mode A: ElevenLabs TTS, auto-detect language, voice presets.

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?

Description is fairly long but well-structured: async note, input modes, two-step flow. Each sentence adds value; no fluff. Slightly dense but appropriate for the tool's complexity.

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

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

Given no output schema, the description covers all needed aspects: async behavior, polling, return format, two modes, constraints, costs, and two-step workflow. No gaps for correct usage.

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% (all 5 parameters described), so baseline is 3. Description adds significant context: interaction between text and audio_url (exactly one required), voice only relevant in Mode A, confirmed for two-step flow, video_url constraints (max 20s, front-facing face).

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 clearly states the tool's purpose: 'Re-sync the lips in an existing talking VIDEO to NEW speech' and distinguishes it from sibling tool generate_talking_avatar (which creates a new talking face from a still portrait). The verb 'lipsync' and resource 'existing talking video' are specific.

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

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

Explicitly tells when to use this tool ('make this video say X', 'dub this clip', 're-voice this video'), contrasts with generate_talking_avatar, and details two input modes with conditions (exactly one of text or audio_url). Also provides constraints (max 20 seconds, front-facing face).

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 no annotations, the description carries the full burden. It discloses the return structure, the meaning of the `voice` field, and how avatars are created. It implies a read-only operation with no side effects.

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 detailed but front-loads the core purpose. It could be slightly more concise, but every sentence adds value. The structure is logical.

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

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

Given the absence of an output schema, the description fully explains the return format and the concept of saved avatars. It covers what the tool does, what the output means, and how to use it downstream.

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 no parameters, so the baseline is 4. The description adds value by explaining the output structure and usage, which is sufficient.

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 clearly states the tool lists the user's saved avatars, defines what a saved avatar is, and explains its purpose as a reusable face identity. It distinguishes from siblings by showing how the output is used with generate_talking_avatar and face_swap_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?

The description explains when to use the tool (to retrieve avatars for reuse) and provides explicit guidance on how to use the returned data. It mentions 'Free, no tokens' but does not explicitly state when not to use it; however, the 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?

With no annotations, the description discloses that the tool is free and shows per-call cost. It does not mention rate limits or data freshness, but for a list tool these are less critical.

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 with no redundancy: first sentence states purpose and output, second declares it's free, third provides filtering and usage guidance. Front-loaded and efficient.

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

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

Given the tool's simplicity (one optional enum parameter, no output schema), the description adequately covers purpose, behavior, and usage context. No missing critical information.

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 description merely restates the enum values without adding new meaning. Per guidelines, 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?

Clearly states it lists generation models with per-call cost, and distinguishes itself from siblings like generate_image and generate_video by mentioning it should be used before those to pick a model.

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

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

Explicitly states when to use: when the user asks 'what models can you use' or before generate_image/generate_video. Provides clear context for invocation.

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