Fattly

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

Annotations cover the safety profile (non-read-only, non-destructive, non-idempotent), and the description adds two things annotations cannot: an expected latency ('a few minutes') and a legal/consent obligation. It stops short of saying whether credits are consumed or how to poll for the result.

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, each earning its place: what it does, how long it takes, and the consent condition. The core action is front-loaded with zero waste.

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

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

The tool is a long-running job, but the description never says how the result is retrieved, for example through fattly_video_status. With no output schema, that retrieval path is a real gap, though the latency hint and consent note cover the rest.

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, including the required consent flag, are already documented in the schema. The description only restates the consent condition and adds no syntax or format detail beyond it.

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

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

States a specific verb and resource: 'Replaces the creator in an existing video with another actor.' An agent can grasp the operation immediately, though it does not disambiguate from the sibling fattly_face_swap, which sounds closely related.

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 conveys the cost of the operation ('takes a few minutes') and a legal precondition (likeness rights), but gives no explicit guidance on when to pick this over fattly_face_swap or fattly_edit_video.

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

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

Annotations 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 declare that this is not read-only, not idempotent, not destructive, and closed-world. The description adds useful context about consent/rights and the cheaper reuse path, but does not explain credit usage, failure behavior, or what happens when saveName is used.

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 with no wasted language; the core clone/reuse choice is front-loaded and the legal constraint is concise.

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

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

For a five-parameter tool with full schema coverage and annotations, the description is nearly complete: it explains the two operating modes and consent requirement. It could say more about the expected result, but with no output schema this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents text, consent, voiceId, saveName, and sampleUrl. The description reinforces the sample-vs-saved-voice distinction but adds no syntax or format details beyond the schema.

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

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

The description states a specific action and resource: cloning a new voice from a sample or reusing a saved voice to speak text. It distinguishes the two internal modes, but does not explicitly differentiate this from sibling audio tools such as fattly_generate_audio.

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 mode-selection guidance: clone a NEW voice from a sample, or REUSE a saved voice because it is cheaper. It also adds a legal-use condition, though it does not state when to prefer this tool over sibling 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 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 only carry hint flags (readOnly=false, destructive=false, idempotent=false), so the description does real work: it discloses the minutes-long latency, the async return shape (mp4 link or generation id), and that unmasked areas are preserved. It omits cost/credit implications and what happens on failure, keeping it just short of a 5.

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

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

Three tight sentences, front-loaded with the mask-and-prompt mechanic, then prerequisites, then latency and return value. No filler and no repeated schema content beyond what aids comprehension.

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

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

With no output schema, the description compensates by explaining exactly what is returned (mp4 link or generation id) and how to poll it. Upload constraints and the consent requirement are covered, leaving nothing an agent needs missing before calling.

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%, including the WHITE/BLACK mask convention and the consent statement. The description reinforces the mask semantics and gives prompt examples, but says nothing about resolution or durationSeconds, so it adds little beyond the schema. Baseline 3 applies.

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

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

Specific verb+resource with scope ('a REGION of a video'), distinguished 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 states the prerequisite that the source video must come from fattly_upload_media and the mask from fattly_upload_image, and warns that other links are rejected. It also names the follow-up path (fattly_video_status) for the async case.

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 declare it as a non-readonly, non-idempotent, non-destructive mutation. The description adds genuinely useful context the annotations lack: a ~150 credit cost, a multi-minute runtime, a ~2 minute internal wait, and an async id returned for polling via fattly_video_status.

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, cost and runtime front-loaded, ending with the actionable next step. The phrase 'the full site flow' is vague filler that doesn't earn its place, keeping it from a 5.

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

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

For a 14-parameter tool with full schema coverage and no output schema, the description supplies exactly the missing operational layer: cost, latency, the async id return, and the status-check sibling. Nothing needed to invoke or follow up is absent.

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

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

Schema description coverage is 100% and the per-parameter docs are unusually rich (mode semantics, script length limits, consent rules). The description prose adds no parameter-level meaning, so the schema does all the work — 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?

Names a specific verb+resource: generates a 'VIDEO ad' where 'a real-looking creator presents your product on camera with a real voice'. It implies a contrast with the sibling fattly_generate_ad but never names it, leaving the sibling differentiation implicit rather than stated.

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

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

Usage is only implied — the agent can infer this is the premium video path versus cheaper alternatives, and the description explicitly routes follow-up to fattly_video_status. But it gives no explicit when-to-use/when-not guidance versus fattly_generate_ad or fattly_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?

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 already flag it as a non-read-only, non-idempotent write with no destruction, but the description adds behavior the annotations cannot express: the ~2 minute server-side wait, the possibility of an incomplete render, and the two possible return shapes. It stops short of mentioning credit cost or failure modes.

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

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

Three tight clauses, front-loaded with the core action, followed by timing and the fallback path. No filler sentences.

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 carries the return-value burden by explaining the mp4 link vs. generation id outcomes. Combined with the fully documented input schema, an agent has nearly everything needed, though cost and failure behavior are unstated.

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

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

Schema description coverage is 100%, so the model, consent, duration, aspect ratio and image parameters are already well documented in structured data. The description only restates the prompt/image duality and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ("Generates an AI video") and broadens the input mode to prompt-or-image. It is clear against generic siblings, but it does not differentiate from close video-producing siblings such as fattly_animate_photo, fattly_generate_ad_video or fattly_trend_video.

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

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

Gives concrete operational context: the call takes a few minutes and the tool waits ~2 minutes before handing back a generation id. It names the follow-up tool (fattly_video_status) and the polling condition, which is genuine usage guidance, though no explicit when-to-prefer-this-over-sibling rules.

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?

Annotations declare this is a non-read-only, non-idempotent, non-destructive call, so the agent knows it is a mutating/consuming operation. The description adds almost nothing beyond that: it doesn't mention credit consumption, processing time, length limits, or language auto-detect behavior — all relevant for a paid transcription 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?

Two short sentences, front-loaded with the action, no filler. Every clause carries information.

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

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

There is no output schema, and 'returns the transcript as JSON' does not describe the shape (segment fields, timestamps, text). Given no output schema exists, some return-value detail would have been valuable; coverage is adequate but incomplete for an agent that needs to consume the result.

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

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

Schema description coverage is 100%, so all three parameters (task enum, audioUrl, language) are already documented in the schema, including the translate-vs-transcribe choice and auto-detect fallback. The description adds no parameter-level detail, so baseline 3 applies.

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

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

States a specific verb and resource ('Transcribes an audio file to text') plus an output characteristic ('with timed segments'). It distinguishes itself reasonably from generation siblings like generate_audio or clone_voice, but does not explicitly position itself against any 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?

No guidance on when to use this versus other tools, no mention of prerequisites (an uploaded audio asset), and no note on cost or async behavior. The only hint about upstream usage lives in the schema's audioUrl description, not the tool description.

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?

Adds substantial context beyond annotations: size limits (50 MB video / 20 MB audio), supported formats, a safety check on video, and no credit charge. Annotations only cover non-readonly, non-destructive, non-idempotent, open-world — the description fills in the operational constraints.

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

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

Front-loaded with the core action and return value, then constraints. Dense but each sentence carries information. The sibling-tool enumeration is long but necessary because the rejection rule is a hard prerequisite.

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

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

For a 3-parameter upload tool with no output schema, the description covers what it returns, formats, limits, side effects (none — no credits), and the dependency contract for downstream tools. Nothing an agent needs is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real value: it clarifies that `url` should be preferred for larger files and that base64 is an alternative for smaller payloads, plus `kind` semantics via the format lists. Slight redundancy with the schema's own descriptions.

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

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

States a specific verb+resource (uploads video/audio file to FATTLY) and its output (returns a fal URL). Clearly distinguished from the sibling fattly_upload_image and from the generate_* 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 says every videoUrl/audioUrl/sampleUrl passed to fattly_edit_video, fattly_actor_swap, fattly_transcribe, fattly_clone_voice must come from this upload, and that other links (even other fal.media links) are rejected. Also advises preferring `url` for larger files.

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.