Fattly

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

The annotation set is minimal (readOnlyHint false, destructiveHint false), and the description adds useful behavioral context: it "Takes a few minutes," signaling an asynchronous or long-running operation, and it states the consent requirement for using the video and actor likeness. This goes beyond the annotations without contradicting them.

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

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

The description is compact and front-loaded with the main function. Each sentence serves a purpose: the first states the operation, the second sets time expectations, and the third covers the consent requirement. There is no fluff or repetition beyond the consent point that also appears in 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 ivo tool with no output schema, the description does not explain what the caller should expect as a result or how to retrieve the completed swapped-actor video. It covers the input and consent side well, but leaves the output/status behavior implicit, which is a meaningful gap given 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 description coverage is 100%, so the schema already documents all four parameters including consent semantics and source URL origins. The description does not add new parameter-level meaning, which is acceptable given the high schema coverage.

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

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

The description clearly states the verb and resource: "Replaces the creator in an existing video with another actor." This is specific and understandable, though it does not explicitly differentiate itself from the closely related fattly_face_swap sibling.

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

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

The description gives no guidance on when to choose this tool over alternatives such as fattly_face_swap or fattly_edit_video. There are no explicit conditions, exclusions, or mentions of alternative tools, so an agent must infer usage solely from the name and general purpose.

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 establish it is non-read-only, non-idempotent, non-destructive, and closed-world. The description adds genuine context beyond that: the multi-minute latency and the legal/consent obligation, both relevant behavioral traits for a costly generation 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?

Three short sentences, front-loaded with the core transformation, then latency, then the consent caveat. No wasted wording, though it is terse relative to the operation'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?

No output schema exists, and the description does not explain what is returned or that this is an async job requiring polling via fattly_video_status – a notable omission for a minutes-long video generation. Latency and consent are covered, but the return/lifecycle pattern 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 all four parameters are already documented, including consent and the modelId/upload references. The description adds no format or syntax detail beyond the schema, so 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 concrete verb and transformation: 'brings a still photo to life as a video (adds motion)', which is specific and distinguishable from generic video generation. It does not explicitly name a sibling (e.g. fattly_generate_video) to draw the boundary, but the input+transformation is clear.

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 – animate a still photo – and it warns the process takes minutes plus requires rights confirmation. However, it gives no explicit when-to-use vs alternatives such as fattly_generate_video or fattly_trend_video, leaving the routing decision 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 disclose the write/non-idempotent/non-destructive profile. The description adds the rights/consent obligation and the cost trade-off between paths, which is useful. However it says nothing about credit consumption, latency, or what happens to a saved voice (overwrite, retention), so it adds only moderate context 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?

Two compact clauses, front-loaded with the resource and both modes, with the constraint appended last. No filler and no duplicated schema text.

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 generative tool with no output schema, the description covers the modes, the consent gate, and the cost differential; the return value (audio) is implied by 'speak text.' It could be more complete on cost/credits, but nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so all five parameters (including consent and sampleUrl requirements) are already documented. The description's only added semantic value is the clone-vs-reuse framing, which the schema itself already conveys via voiceId and saveName. 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+resource (clone or reuse a voice) and clarifies it also synthesizes speech from text, covering both operating modes in one line. No sibling tool touches voice cloning, so this is unambiguous within the tool set.

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 frames the two paths — clone a NEW voice from a sample vs REUSE a saved voice (cheaper) — giving the agent a selection criterion via the cost hint. It also states a rights/consent precondition. It stops short of naming exact parameter combinations or when cloning is strictly required, so it is clear context but not a full when/when-not matrix.

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 indicate that the operation is non-readOnly, non-idempotent, and non-destructive. The description adds meaningful behavior: it costs 20 credits, returns an actorId, enforces adults-only server-side, and guarantees the same creator is reused. This goes well beyond the annotations and the 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?

Three short sentences pack the core function, cost, output, downstream usage, and content policy without repetition. The purpose is front-loaded and every sentence contributes information an agent needs.

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

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

For a one-parameter generation tool with no output schema, the description covers the essential return value (actorId), how to consume it, the credit cost, and the content restriction. It is slightly thin on operational details like processing delays or failure modes, but nothing required to call it correctly is missing.

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

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

Schema description coverage is 100% and the parameter description already explains what to write plus an example and server-side translation. The tool-level description only reiterates that the avatar is 'from a description', so it adds no substantial meaning beyond the schema.

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

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

The description uses a specific verb ('generates'), names the exact resource ('your own creator avatar'), and states the input source ('from a description') and output ('actorId'). It also differentiates this from the many sibling generation tools by tying the outcome to a reusable creator that can be passed into fattly_generate_ad / fattly_generate_ad_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?

It gives clear context for when to use the tool: when you want a persistent creator avatar for ad generation, with the actorId to reuse across ad types. It does not explicitly state when NOT to use it or name an alternative, but no sibling offers the same avatar-creation capability, so the usage 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is well covered. The description adds only the 'current' snapshot semantics and does not describe response format or edge cases, but this is less critical for a zero-parameter read-only tool.

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

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

A single, short sentence with no filler. The key information is front-loaded, and every word contributes to understanding the tool's 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?

For a no-parameter, read-only, idempotent balance query with an empty input schema, the description fully equips an agent to select and invoke the tool correctly. The phrase 'Shows ... balance' sufficiently frames the expected result even 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?

With zero parameters and 100% schema coverage, the input schema carries no parameter burden. The baseline for a zero-parameter tool is 4, and the description appropriately does not need to compensate for parameter documentation.

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

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

The description uses a specific verb ('Shows') and a precise resource ('current credit balance on the FATTLY account'). This clearly differentiates the tool from the numerous media-generation and manipulation siblings.

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

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

The intended usage is implied: an agent needing the account's credit balance should call this tool. However, the description does not explicitly state when to use it or mention any exclusions or alternatives, though no sibling appears to compete for this function.

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

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

Annotations already declare non-read-only/non-idempotent/non-destructive, and the description adds real behavioral value on top: the operation takes a few minutes, returns an mp4 link or an async generation id, and the unmasked area is preserved. It omits failure modes and any credit/cost implications.

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?

Short and front-loaded: it identifies the tool, then the mask semantics, then prerequisites, then runtime/return behavior. Every sentence carries information an agent needs.

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

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

With no output schema present, the description compensates by describing the return value (mp4 link or generation id) and the polling path. Combined with a fully documented 6-parameter schema, an agent has everything needed to call and follow up on this 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%, so the baseline is 3. The description still adds meaning by restating the WHITE-edits/BLACK-keeps mask convention in operational terms and giving example prompts that show what a usable 'prompt' value looks like.

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

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

Names the tool's distinctive mechanism (mask + text instruction regeneration of a REGION) with three concrete prompt examples, so an agent can tell it apart from sibling image-editing tools like fattly_inpaint and from whole-video 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?

Gives clear operating context: inputs must be fal URLs obtainable via fattly_upload_image, and results come back directly or as a generation id checked with fattly_video_status. It does not explicitly contrast when to pick this over region-adjacent siblings such as fattly_inpaint, so it stops short of a 5.

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

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

Annotations declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds genuinely new behavior: the output is scanned and the request is policed for SFW/rights compliance. Disclosing that results are moderated is real behavioral context not present in the structured fields, though the response format itself remains unspecified.

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

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

Two sentences, no filler; the core operation comes first and the policy constraints follow. Every clause carries weight.

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 mutation with fully documented schema and no output schema, the description covers the operation and its compliance guardrails adequately. Minor gap: nothing about output/result delivery or typical latency for a scanned generation.

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 three parameters (including the consent boolean) are already well documented in the schema. The description adds no syntax, format, or URL-handling detail beyond it, making the baseline 3 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+resource ('Swaps the face from one image onto another') that is immediately understandable. It does not, however, differentiate itself from a close sibling like fattly_actor_swap, leaving the agent to infer the distinction from names alone.

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

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

The description supplies meaningful constraints — SFW-only, rights/consent required, no misleading or explicit imagery — which function as 'when not to use' guidance. It stops short of telling the agent when to prefer this over fattly_actor_swap or other swap/animate siblings, so usage routing is only implied.

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

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

Annotations already declare this is a non-idempotent, non-destructive write. The description adds the elements annotations can't: the 20-credit cost and the required upstream sequence (upload image, list presets). It does not explain what the generated artifact looks like or how it is returned, so it is not a full 5.

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

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

Front-loaded with the core purpose and cost, then modes, then prerequisites — dense and mostly free of padding. The mode-list sentence is somewhat redundant with the enum, costing it the top score.

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

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

For an 11-parameter generative tool with no output schema, it covers cost, mode semantics, prerequisites, and where to get templateId, which is what an agent needs to invoke it correctly. Return-value details are the only meaningful gap, and the description never overreaches into what it can't guarantee.

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 every parameter, including the mode enum and its dependencies. The description's mode gloss largely restates the enum definition, adding no syntax or format detail beyond it — the baseline 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?

States a concrete verb and resource ('turns a product photo into a finished ad') under a named product area ('Ad Studio'), and immediately distinguishes the three modes. An agent can tell this apart from fattly_generate_image or fattly_generate_ad_video from the description alone.

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

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

Gives explicit workflow ordering — pick templateId with fattly_list_ad_presets and upload the product photo with fattly_upload_image first — plus the mode-selection rule (graphic/product/service). It stops short of naming when to prefer the video sibling, so it is clear context rather than full when/when-not coverage.

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

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

Annotations only cover the safety profile (non-read-only, non-idempotent, non-destructive, closed-world). The description adds genuinely non-obvious behavior: credit cost, multi-minute runtime, a hard ~2 minute wait ceiling, and the asynchronous id + fattly_video_status polling handoff. That is exactly the context an agent needs and cannot get 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?

Two dense sentences: the first front-loads what the tool produces and its cost, the second front-loads the latency and the follow-up call. Nothing is wasted and no parameter detail is redundantly restated.

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 14-parameter, no-output-schema generation tool, the description supplies the cost, the runtime, the wait/poll contract, and the next tool to call, while the fully-covered schema handles parameter semantics. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% and the schema itself carries rich per-parameter guidance (mode semantics, consent requirements, voice/locale behavior, cross-tool references). The description adds no parameter-level meaning beyond that, 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?

The description names a specific verb and resource (generate a VIDEO ad with a real-looking creator presenting the product on camera with a real voice) and pairs it with a price/latency signal. It implicitly separates this from the image-ad sibling fattly_generate_ad via 'VIDEO', but never names that sibling or fattly_generate_video explicitly, so the differentiation is left partly 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?

It gives clear operating context: a premium (~150 credits) tool that takes a few minutes, waits ~2 min, then returns an id to poll with fattly_video_status. That is real workflow guidance. However, it never states when to choose this over fattly_generate_ad, fattly_generate_video, or fattly_trend_video, and gives no exclusions.

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

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

The description discloses the output behavior by stating it returns a link to the mp3 file, which is useful beyond the annotations. It also clarifies that generation is conditional on mode, though it does not discuss processing time, costs, or 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 two concise sentences with no filler. It front-loads the core purpose and includes the important output detail without wasting words.

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 a complete input schema and annotations, the description is sufficient for an agent to understand the main generation modes and output format. It lacks only optional behavioral context like async behavior or credit usage, which are not essential 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 the parameters are already well documented. The description mostly restates the schema's mode and text semantics without adding extra meaning, earning the baseline score.

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 identifies the tool as generating AI audio, either a voiceover from text or music from a description, and states the return value is an mp3 link. It is specific enough to distinguish from image/video generation siblings, though it does not explicitly name a sibling alternative.

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

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

The mode parameter and phrasing 'from text' and 'from a description' imply when to use the tool for speech or music generation. However, there is no explicit guidance about when not to use it or how it compares to siblings such as fattly_clone_voice.

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 useful behavioral information beyond the annotations: credits are deducted from the user's account and the tool returns a link to the finished image. However, it does not disclose whether generation is synchronous or asynchronous, or how long the operation may take.

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

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

The description is two short sentences that front-load the core purpose. Every sentence earns its place: what it does, what it returns, and the cost implication.

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?

The description covers the primary output and cost, but with six parameters, no output schema, and many related sibling tools, it leaves gaps around when to select it over alternatives and what to expect during execution.

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 six parameters are already documented in the schema. The description only adds the phrase 'from a prompt', which aligns with the required prompt parameter but adds no meaningful semantic detail 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?

Description states a clear verb and resource: it generates an AI image from a prompt and returns a link to the finished image. It is clear, but it does not explicitly distinguish itself from specialized image siblings like fattly_generate_ad or fattly_create_avatar.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of when it should be preferred over sibling tools, no exclusions, and no comparison to specialized image-generation tools.

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

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

Annotations confirm it is a non-readonly, non-idempotent, closed-world generator, and the description adds concrete behavior annotations don't carry: multi-minute latency, a ~2-minute wait window, and the two possible return shapes (mp4 link vs generation id). Consent and rights obligations are covered in the schema rather than the description, so this is good but not 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?

Two tightly packed sentences with no filler. The async/timeout behavior and the fallback status tool are front-loaded so the agent learns the critical invocation consequence immediately.

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 both return paths (mp4 link or generation id) and the polling follow-up, which is what an agent needs to handle the response. Only minor gaps remain, such as credit cost and where model names come from (fattly_list_models).

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 parameters like model, aspectRatio, consent, and the image URL fields are already well documented in the schema. The description only restates the prompt-or-image duality, adding little beyond what the schema already conveys, which fits the baseline 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?

States a specific verb+resource ('Generates an AI video') and clarifies the two input modes (prompt or image), which is meaningful against siblings like fattly_generate_ad_video and fattly_trend_video. It does not explicitly differentiate itself from fattly_animate_photo, the closest neighbor for image-to-video, so it stops short of full sibling routing.

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

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

It gives clear follow-up guidance — poll with fattly_video_status if a generation id is returned — which is useful operational routing. However, it never states when to pick this tool over alternatives such as fattly_animate_photo or the ad-video generators, leaving the primary selection decision 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?

The description goes beyond the sparse annotations by explaining that the operation edits only the masked area and returns a link to the result. This is meaningful behavioral context, though it does not address processing time, credit costs, or whether the original image is left unchanged.

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 carry a precise purpose, a behavioral detail, and the return type. Nothing is wasted, and the main action 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?

For a simple 3-parameter tool, the description plus schema covers inputs and output adequately: image, mask, prompt, and result link are all specified. It lacks only minor operational context such as costs or asynchronous behavior, which are not critical for invoking the tool.

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

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

The schema covers 100% of parameters with clear descriptions (including mask color semantics and fal URL requirements), so the base score is 3. The tool description itself adds no parameter-level meaning beyond what the schema already provides.

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

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

The description uses a specific verb-resource pair ('Edits part of an image') and precisely defines the operation: 'repaints the masked area to match a prompt.' This clearly distinguishes inpainting from sibling tools like remove_background, upscale, and generate_image.

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

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

The description implies the tool should be used for repainting masked image regions, but it does not state when to prefer it over alternatives or when not to use it. No exclusions or sibling comparisons are provided, so usage guidance is only implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: server-side validation of preset ids and the mode-matching constraint, which affect how the agent should use the results.

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

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

Two sentences with no filler. The primary purpose is front-loaded, and the critical ordering/validation note is delivered immediately after, making the description easy to scan and 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?

For a simple, read-only list tool with one optional parameter, the description covers purpose, resources returned (presets, scenes, avatars), and the essential prerequisite relationship with fattly_generate_ad. Annotations and schema cover safety and parameter semantics, so nothing necessary for correct invocation 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%, and the mode parameter has a detailed enum description with concrete meanings for graphic, product, and service. The tool description does not need to repeat this; it only reinforces that presets work in matching modes, which is consistent with 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 uses a specific verb ('Lists') with a clear resource scope: Ad Studio ad presets (templateId), scenes, and creator avatars. It also distinguishes itself from the generation sibling by explicitly naming fattly_generate_ad, so an agent can immediately tell this is the discovery/list tool.

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

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

The description gives explicit workflow guidance: 'Call this BEFORE fattly_generate_ad'. It also explains why ordering matters by noting preset ids are validated server-side and presets only work in their matching mode, which tells the agent when this tool is a prerequisite.

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, so the safety profile is covered. The description usefully adds that the return contains models and credit costs, but it does not describe the response format or any data freshness details.

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

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

Two short sentences deliver the core purpose first and then add a practical usage cue. There is no filler or redundant information.

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

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

For a simple, read-only listing tool with one optional parameter and no output schema, the description adequately covers what is returned and when to call it. The exact response shape is not described, but the low complexity makes that a minor gap.

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

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

The schema already provides 100% coverage for the single optional category parameter, including its enum values. The description only repeats the category names in parentheses without adding additional parameter semantics.

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 available models and their credit costs, covering image, video, and audio categories. This makes it easily distinguishable from the many generation-focused 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?

The description explicitly says to use the tool before generating to pick the right model, which gives clear usage timing. However, it does not mention when not to use it or contrast it with other listing tools like fattly_list_ad_presets.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, which aligns with the description's claim of producing a new cutout. The description adds the return-link detail, but does not disclose potential side effects like cost, rate limits, or whether the original image is preserved. Adequate given annotations.

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

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

Two concise sentences with the primary action front-loaded and the output mentioned shortly after. No redundant words; it is efficient and easy to scan.

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

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

For a single-parameter tool with no output schema, the description is nearly complete. It states the operation, the result, and the return format. The only missing detail is the prerequisite that the image must be uploaded first, but that is already listed in the parameter description, so the description itself is 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?

The parameter description in the schema already explains that imageUrl is a fal URL from fattly_upload_image (100% coverage), so baseline is 3. The parameter description adds the constraint of using a previously uploaded image, improving clarity beyond the schema's basic type definition.

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 action (removes background) and the outcome (clean cutout, returns a link). It distinguishes this tool from siblings like fattly_upscale or fattly_inpaint by being specific to background removal.

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

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

No guidance on when to use this tool versus alternatives or when not to use it. There is no mention of complementary tools or conditions that would select this over others, leaving an agent to infer based solely on name and purpose.

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 that the output includes timed segments and is returned as JSON, which is useful beyond the bare 'transcribe' statement. Annotations already indicate non-read-only behavior, and the description does not contradict this. However, it does not disclose potential side effects like credit consumption or whether the operation is synchronous—both relevant given the fattly suite includes a credits tool and many async generation tools.

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 concise sentences, front-loaded with the core action, and no filler. The first sentence captures the main purpose and output; the second clarifies the return format. Every word contributes.

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?

The tool has three parameters, all documented in the schema, but no output schema. The description mentions 'Returns the transcript as JSON' but does not outline the exact JSON structure, which could be ambiguous. It also relies on the schema to convey that audioUrl must come from fattly_upload_image, which is acceptable since that is in the schema. Given these factors, the description is adequate but not fully complete.

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

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

Schema description coverage is 100% with detailed descriptions for all three parameters (audioUrl, task, language). The description itself adds no parameter-specific information, so it provides no extra meaning beyond what the schema already documents. Baseline of 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 ('Transcribes') and resource ('audio file') with output details ('text with timed segments') and format ('JSON'). This clearly differentiates it from sibling tools like fattly_generate_audio, which generates audio, and fattly_video_status, which tracks video status.

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 usage for transcription but does not explicitly mention alternatives or when not to use it. There is no guidance on selection among siblings, such as preferring this over other audio-related tools. The purpose is clear enough that an agent could infer, but explicit 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?

The description adds useful behavioral context beyond the neutral annotations: 'Takes a few minutes' signals latency, and the consent statement adds a legal precondition. However, it does not disclose whether the call returns a completed video or a job id requiring polling, and the annotations do not cover result handling.

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

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

Two front-loaded sentences with no filler. The core action comes first, the latency/consent details each earn their place, and the whole description is compact and easy to scan.

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

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

There is no output schema, and the description never explains how the agent will receive the finished video or whether it must poll fattly_video_status. Given the 'takes a few minutes' hint and related sibling tool, this is a meaningful operational gap: an agent can invoke the tool but cannot confidently handle 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% — all three parameters are already described in the schema. The prose description adds little beyond restating the consent requirement (already in the schema) and does not enrich parameter semantics further.

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: 'Turns a photo into a trend-style video from a preset.' It is clear enough to understand the tool's core function, but it does not explicitly differentiate it from siblings like fattly_animate_photo or fattly_generate_video, relying on the phrase 'trend-style' and 'preset' to carry the distinction.

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

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

The description implies a use case (photo + preset + trend video) but gives no guidance on when to choose this tool over alternatives, and it never states when not to use it. No exclusions or sibling comparisons are provided, leaving the agent to infer selection.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, covering the mutation and non-idempotent nature. The description adds a useful behavioral detail: 'No credits are charged for the upload.' It does not discuss error handling or side effects, but given the annotation coverage, this is adequate.

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 no fluff. The core purpose is front-loaded, and the downstream usage is explained concisely. The extra note about credits is a minor but valuable addition. It is efficiently structured.

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 upload tool with only 2 well-documented parameters and no output schema, the description covers the return value (fal URL) and how to use it downstream. It lacks explicit error scenarios, but that is not critical for this tool type. Overall it is complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 100% – both parameters (imageUrl and imageBase64) already have detailed descriptions including format and size limits. The description reinforces the 'alternative' relationship between the two but adds no new semantic information beyond that.

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 action: uploading an image (URL or base64) to FATTLY and returning a fal URL. It explicitly explains the purpose: to obtain an inputImageUrl for downstream generation tools, and names the specific siblings it feeds into, distinguishing it from those 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?

It explicitly tells when to use it: to turn a picture into an inputImageUrl for editing/face-swap/image-to-video models, and specifies that the returned URL should be passed as inputImageUrl to fattly_generate_image or fattly_generate_video. This effectively routes the agent to the correct workflow and alternatives.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds the return behavior ('Returns a link to the upscaled image'). However, it does not mention any processing time, credit cost, or side effects of upscaling, so the behavioral context beyond annotations is thin.

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, no redundancy, and the core action is front-loaded before the output statement. Every word earns its place.

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

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

For a simple two-parameter tool, the description plus schema is nearly sufficient: inputs are explained, factor defaults are in schema, and the output link is stated. It only lacks a brief note about scope/limits (e.g. maximum source image size or credit consumption), so it is complete enough but not exhaustive.

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%: both imageUrl and factor are documented, including the default factor and the required fal-upload-source. The description itself adds no parameter-level meaning, matching the baseline 3 when the schema already carries the burden.

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

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

The description opens with 'Upscales an image to higher resolution', a specific verb and resource, and it is distinct from every sibling (no other tool upscales). 'Returns a link to the upscaled image' also clarifies what the output is, so an agent can identify it without opening the schema.

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

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

The description implies usage when an image needs higher resolution, but it gives no explicit when-to-use/when-not-to-use guidance and names no alternatives. Prerequisite like the URL coming from fattly_upload_image is only in the schema, not in the description, so there is little help in choosing this over related generation/edit tools.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context by specifying the conditional outcome: an mp4 link when ready, otherwise the current status. It does not enumerate possible status values, but this is a minor gap given the annotations.

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

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

A single front-loaded sentence with no filler: the action, the relationship to the parent generation call, and the conditional return are all included. Every word earns its place.

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

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

For a one-parameter, read-only status tool with rich annotations and no output schema, the description covers invocation and the expected return shape. It could be more complete by listing possible statuses or error behavior, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter is documented as the generation id returned by fattly_generate_video. The description restates this dependency but adds no new parameter 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 ('Checks') and a clear resource (a video generation started by fattly_generate_video), and distinguishes the tool from generation by describing a polling/status role. The mention of the sibling makes its 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 clearly implies the tool is used after fattly_generate_video to poll for completion, but it does not explicitly state exclusions or alternative tools. Context is sufficient for an agent to select it, though a brief 'use after generation' note would make it explicit.

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