UGC Fans

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

Annotations declare a non-read, non-idempotent, non-destructive but closed-world operation; the description adds behavior beyond that by disclosing the result shape (the film plus its first revision) and the cost profile (free of credits). It does not explain reversibility or the failure mode when preconditions fail, but the added cost and return details are meaningful.

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, front-loaded with the transformation and its payoff before the constraint list. Every clause carries an actionable fact (output, preconditions, size limit, cost).

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

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

With no output schema, the description correctly covers the return value (the film and its first revision), the input preconditions, and cost. What is missing for a job-oriented sibling set is whether the call is synchronous or job-backed and how to follow up if the film needs further editing.

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

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

There is a single parameter with 100% schema description coverage, so the schema already explains that 'ad' is an ad id from a finished ugcfans_make_ad job. The description restates the 'must be finished' constraint but adds no format or syntax detail beyond the schema, making 3 the correct baseline.

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: converts a finished video ad into an editable film, and names the downstream benefit (captions and end card become editable). It implicitly separates itself from ugcfans_make_launch_film and ugcfans_make_site_sting by naming the source artifact (a finished ad), but never routes the agent between those alternatives explicitly.

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

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

Gives concrete preconditions for use: the ad must be finished, must not already be a film, must be video, and at most 96 MiB. That is real context for when the call will succeed, though it stops short of naming an alternative tool or describing the case where the ad does not meet these conditions.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=true. The description adds genuinely new behavioral facts: no charge for a successful cancellation and an explicit failure signal when the job is already with a provider. It does not contradict the destructive/idempotent hints.

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

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

Three short sentences, the mutation semantics front-loaded, followed by the precondition and cost note. Zero filler.

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

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

For a one-parameter mutation with no output schema, the description covers cost, precondition and failure reporting. It stops short of saying what a successful call returns or how to verify the job's new state, which is a minor gap.

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

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

Single parameter with 100% schema description coverage ('The job id a tool returned, job_...'), so the schema already carries the format detail. The description adds nothing about the job id, which is acceptable at this coverage level but earns no bonus.

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 ('Stops') and resource ('a job') plus a scope constraint ('has not yet reached a provider'). It is clearly distinguishable from get_job/wait_job by implication, but it never names a sibling to route the agent explicitly.

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

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

Gives both when-to-use and when-not: cancellable only before the job reaches a provider, and already-dispatched jobs cannot be stopped. No alternative tool is named for those cases, so it falls short of the top mark.

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 substantive behavior beyond the annotations: it returns a job whose result is a capture id (the async job pattern tied to wait_job/get_job), it is free of credits, and it asserts a legal/rights confirmation. The annotations (openWorldHint, non-idempotent, non-destructive) cover the safety profile, but the description usefully adds the cost and legal-attestation context those annotations cannot express.

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

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

Five compact sentences, each carrying distinct information (behavior, downstream use, cost, legal attestation, domain limits), with the core action front-loaded. No filler or redundancy.

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

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

With no output schema, the description correctly explains the return value (a job resolving to a capture id) and the async workflow. It stops short of explicitly warning that repeated calls create new captures (non-idempotent), which would matter for an agent retrying, but it is otherwise complete for a capture tool.

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

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

Schema description coverage is 100%, so both url and viewport (including the enum and default) are already fully documented in the schema. The description contributes only the port restriction (80/443) on the URL, which is a meaningful constraint but does not go beyond baseline for the parameters themselves.

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

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

The description gives a specific verb and resource ('Opens a public web page in a sandboxed browser, records its text, pictures and layout') and names the two sibling tools that consume its output (ugcfans_make_launch_film, ugcfans_make_site_sting). An agent can distinguish this capture tool from the get_capture/get_job siblings without opening any schema.

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

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

It clearly positions the tool as the upstream step for make_launch_film and make_site_sting and states eligibility constraints (only http/https on ports 80 and 443). However, it never explicitly states when NOT to capture or how it relates to non-consumer siblings like get_capture, leaving that routing 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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description adds genuinely new behavior beyond that: zero cost, a ~10 minute quote lifetime, and invalidation when any field changes. It stops short of noting rate limits or whether warnings are advisory vs. blocking, 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?

A single front-loaded passage that leads with the definition and cost, then the quote mechanics. Mostly dense, though the mid-sentence list of return values is slightly crowded and could be trimmed.

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 compensates by describing the return payload (max credits, dollar figures, warnings, expiring quote). It also explains how the nested 'body' object relates to the make tools, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the schema already documents both 'kind' (enum) and 'body' (fields of the make tool for this kind, without quote). The description largely restates that mapping rather than adding new syntax or constraints, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('prices a request without making it') and immediately enumerates what the price consists of (credit cost, dollar figures, warnings, quote). It explicitly differentiates itself from the make siblings by name, so an agent can distinguish it without opening any schema.

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

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

Gives explicit when-to-use guidance: call this before making, it is free, the quote lasts ~10 minutes, and the corresponding make tool accepts the quote back and rejects it if a field changed. It names the three alternative tools by name and describes the round-trip workflow between estimate and make.

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

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

Goes beyond the annotations by disclosing the asynchronous job contract ('returns a job; when it is done the result carries a link to the file') and the cost profile ('Free of credits'). That is real added context, though it stops short of saying whether repeated invocations spawn duplicate jobs (relevant given idempotentHint=false) or how the job is polled.

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 with no filler: the action and output first, then the async/result contract, then the cost and the blocking condition. Every sentence earns its place.

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

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

With no output schema, the description correctly carries the return-value burden by describing the job and its eventual file link. The main remaining gap is operational: no pointer to a job-status sibling (get_job/wait_job) for retrieving the finished render.

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

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

Schema coverage is 100% and both parameters are documented there, so the baseline is 3. The description only obliquely reinforces that a single revision is rendered and adds no format, ID-source, or constraint 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?

States a concrete verb+resource+output ('Renders one revision of a film to an MP4') and scopes it to a single revision, which clearly separates it from the many creation-oriented siblings like ugcfans_make_launch_film and ugcfans_ad_to_film. An agent can tell this is the terminal export step for an existing film without opening any schema.

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

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

Gives a clear precondition/exclusion ('A film with an unresolved rendering requirement cannot be exported') and notes the operation is free of credits, which is useful selection context. It does not, however, name any alternative path or explain what to do when the precondition fails (e.g. which sibling resolves the requirement).

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, destructiveHint=false, idempotentHint=false), so the description adds genuinely useful context beyond them: operations chain each on the previous file's output, a run past 4 minutes returns the in-progress job plus remaining operations, and the call is free of credits. Omits details like retry/failure semantics, but the timeout and pipelining disclosures are substantive.

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

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

Front-loads the core mechanism (up to 6 chained operations) before secondary details like timeout behavior and prerequisites. Dense but nearly every sentence carries required information; the music-rights clause is slightly awkwardly appended.

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 the return value (the last job, whose result links the finished file) and the partial-run case. Combined with prerequisites and the 4-minute boundary, an agent has enough to invoke it correctly, though failure/error behavior is not covered.

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

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

Schema coverage is 100%, so per-operation parameters (trim start/end, captions cues/transcript, reformat mode/aspect_ratio, overlay/end_card brand, mix music) are fully documented in the schema. The description adds the meaningful ordering rule (operations run in sequence) but does not extend individual parameter semantics, 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 ('runs up to 6 finishing operations... on a clip') and enumerates the six operations, so the agent knows exactly what the tool produces. It names sibling tools (ugcfans_list_files, ugcfans_transcribe, upload URL) and distinguishes itself from them.

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

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

Gives clear prerequisites and routing: the clip must already be in the library, upload at the given URL, resolve its address with ugcfans_list_files, and use ugcfans_transcribe for transcripts. It doesn't state when NOT to use the tool, but the sequencing and dependency guidance is explicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds a genuine behavioral fact not in structured data: the call is free, meaning it does not consume the credits it reports on — a meaningful signal in a toolset that otherwise bills credits.

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

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

A single sentence, front-loaded with what is shown and closed with the cost note. The enumeration of returned fields is long but every item earns its place since there is no output schema to carry them.

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

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

With no output schema, the description carries the full burden of describing the return payload and does so precisely, listing all six pieces of information. Annotations cover the safety profile and no parameters need explaining, so nothing an agent needs to invoke and interpret this tool is missing.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and nothing misleading about the empty schema.

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

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

States a specific verb (shows) tied to a specific resource (the signed-in account) and enumerates exactly what is surfaced: credits left, granted, spent, expiry, plan, and admission status. None of the sibling tools touch account state, so it is trivially distinguishable from the film/file/job operations around it.

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

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

Usage is implied rather than stated: an agent can infer this is the tool for checking remaining credits or plan before or after consuming a paid operation. There is no explicit when-to-use or when-not-to-use guidance, nor any mention of prerequisites, though the absence of alternatives for account state limits the practical gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context about the returned content and a "Free" cost signal, but discloses no rate limits or authorization requirements beyond what annotations provide.

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

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

A single well-formed sentence that front-loads the core action and enumerates return content compactly. No filler, though the parenthetical list is dense.

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 read-only, single-parameter tool with no output schema, the description adequately covers what is returned (address, node_id/role/first words, film feasibility) and the cost. Minor omission is the lack of explicit prerequisite routing to the capture job.

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

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

Schema coverage is 100% and the schema already ties the capture id to "the finished ugcfans_capture_website job." The description's "finished capture" phrasing reinforces but does not extend that meaning, so the baseline 3 applies.

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

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

States a specific verb ("Reads") and resource ("a finished capture"), and further specifies the returned content: final address, page parts usable in a film, and launch-film feasibility. The "finished" qualifier implicitly separates it from ugcfans_capture_website, though it does not name any sibling outright.

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 word "finished" implies the capture job must already be complete, giving only an indirect usage cue. There is no explicit guidance on when to prefer this over siblings like ugcfans_get_job or ugcfans_wait_job, nor any stated exclusions.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so safety is covered. The description adds value beyond them: it discloses that the call is free, that it works for any job the account started (a scope/auth boundary), and what the failure result contains (the reason). It does not mention rate limits or polling guidance, keeping it from 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?

Two short sentences, zero waste, with the core semantics (what the read reports) front-loaded before the cost/scope note. Every clause earns its place.

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

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

With no output schema, the description usefully enumerates the possible terminal/working states, partially compensating for the missing return contract. Combined with annotations covering safety, an agent has enough to call it correctly, though the exact payload shape is still unspecified.

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

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

Only one parameter and schema coverage is 100%, so the schema already defines the job id format (job_..., max length 128). The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

States a specific verb (reads) and resource (a job) and enumerates the possible states it reports — working, done with links, failed with reason, cancelled — so an agent knows exactly what it returns. It does not, however, distinguish itself from siblings like ugcfans_wait_job or ugcfans_cancel_job, which an agent also faces when reasoning about job 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?

"Free. Works for any job the account started" gives useful scope and cost context, implying this is a cheap polling/status check. But it never says when to prefer this over ugcfans_wait_job (blocking wait) or ugcfans_cancel_job, 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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real value beyond that: newest-first ordering, the media-type restriction, that the operation is free, and how the returned paths feed downstream tools. It does not cover pagination or result limits, which keeps it from 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 compact sentences, front-loaded with what the tool does and what it returns, then the scope restriction, then the source-path integration hint. Every sentence earns its place with no filler.

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

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

For a parameterless read-only listing with no output schema, the description supplies the returned fields (path, size, change time), the ordering, the media-type filter, and the downstream usage of the paths — everything an agent needs to call and interpret it.

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

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

Schema coverage is 100%, so both limit and prefix are fully documented in the schema, including defaults and constraints. The description echoes the newest-first ordering but 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 (lists files in the account's library) plus the ordering (newest first) and the media-type scope (pictures, video, audio, fonts only). An agent can immediately tell this is the library enumeration tool and what it will return, with no sibling tool offering an equivalent listing operation.

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

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

Explains where footage comes from and, crucially, that the returned path is the source argument for the clip and transcript tools — telling the agent when this tool is a useful precursor. It does not state when-not-to-use or name a competing alternative, so it stops short of a 5.

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

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

Annotations already declare the safe read profile (readOnlyHint, idempotentHint, non-destructive, non-open-world), so the bar is lower. The description adds genuinely new behavior: no authentication required, and results differ by auth state (signed out = full price list, signed in = entitlement-filtered offer). It does not mention pagination or caching, so not 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?

The purpose is front-loaded in the opening clause and every sentence carries information (payload, cost unit, auth behavior, downstream consumers). The final sentence runs long and packs several ideas together, costing some scannability.

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

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

With no output schema, the description must describe return content, and it does: qualities, per-unit credit costs, plan gating, and the accepted model ids. Combined with the auth-state explanation, an agent has enough to call and use it, though exact field shapes and ordering remain unspecified.

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

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

Schema description coverage is 100% with a single optional enum ('kind'), so the schema already carries the parameter meaning; baseline 3 applies. The description adds adjacent context (plan locks, per-account availability) but never explains the kind filter or the enum values.

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 ('Lists what UGC Fans makes at each quality') plus the payload (stills, clips, talking clips, credit cost per unit, plan locks, model ids). This clearly separates it from siblings like ugcfans_estimate (pricing computation) and the make_* tools (which consume the ids listed here).

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

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

Gives clear context: it is free and needs no sign-in, and it explains that the returned model ids are the ones ugcfans_estimate and the make tools accept, which implicitly routes the agent to call this first. It stops short of explicit when-not-to-use or a named alternative for overlapping lookups.

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

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

Annotations declare a non-read-only, non-idempotent write, and the description adds the crucial cost/destructive-to-credits behavior, the quote gating, and the async job return (job now, files as links when done). This goes well beyond what the annotations provide.

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

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

The output job, credit spend, quote gating and presenter preconditions are front-loaded in a compact block with no filler. Sentences are long and dense, but every clause carries operational information.

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

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

Despite no output schema, the description explains the return behavior (a job, later listing the ad's files as links) and the no-quote estimate path. For a complex, credit-spending, multi-parameter tool, an agent has everything it needs to call correctly.

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

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

Schema coverage is 100%, so the schema documents all 11 parameters, giving a baseline of 3. The description still adds cross-parameter meaning the schema does not, notably the quote-to-estimate relationship, presenter prerequisites, and that testimonial basis relies on reviews.

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 ('Makes') plus resource ('UGC-style ad') with the input basis (product and template or feature) spelled out and example features named. It is clearly distinguishable from siblings like ugcfans_make_video, ugcfans_make_image and ugcfans_make_performance.

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 directs the agent to call ugcfans_estimate first and pass its quote, and states the fallback behavior when no quote is given ('returns the cost and makes nothing'). It also states presenter prerequisites (saved, portrait, recorded consent for a real person).

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 mark this as a non-read-only, non-idempotent action, and the description adds the crucial economics (spends credits per picture), the async contract (returns a job; result links the picture and shows a thumbnail inline), and the quote guard that makes the call a no-op without a quote. This goes well beyond the annotation surface.

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, front-loaded sentences that lead with what the tool produces and end with the prerequisite. No filler, though the second sentence packs pricing, workflow, and fallback behavior in a way that takes a second read.

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

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

Covers prompt, references, cost, the quote prerequisite, and the asynchronous job return with inline preview, which is strong given no output schema. It could name the job-polling siblings (ugcfans_get_job / ugcfans_wait_job) to complete the async loop.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the quote parameter's behavior and mentions the reference option, but adds little syntax or format detail beyond what the schema already documents.

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 ('Makes a picture from a prompt'), plus scope details (optional reference pictures, job-returning). It is clearly distinguishable from siblings like ugcfans_make_video or ugcfans_make_speech, which produce other media types.

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 orders the workflow: call ugcfans_estimate first and pass its quote, otherwise the call returns the cost and makes nothing. It also routes to ugcfans_list_models for pricing, naming concrete alternatives rather than implying them.

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

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

Annotations cover the mutation/cost profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds valuable context beyond them: it returns an async job, is free of credits, and produces an editable film with no text layers. It stops short of describing job polling or failure behavior.

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 outcome, then qualifies editability and cost. Every sentence carries information, though the final clause about text layers is slightly tangential and could be folded in.

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 2-parameter mutation tool with no output schema, the description supplies the key facts an agent needs: async job return, credit cost, editability, prerequisite capture state, and the render hand-off. Job-lifecycle detail is the only notable omission.

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

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

Schema coverage is 100% and the enum for 'aspect' is fully described in the schema, so the baseline is 3. The description adds only that the capture must be 'finished' and that the frame is 'chosen', which is marginal beyond the schema.

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

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

States a specific verb and resource ('Makes a 12-second launch film ... from a finished capture') with concrete scope (headline, button, picture, chosen frame). It also distinguishes itself from siblings by naming ugcfans_export_film as the renderer and clarifying the no-text-layers nature, setting it apart from ugcfans_set_film_words.

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

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

Clear context: requires a 'finished capture', produces an editable film, and routes rendering to ugcfans_export_film. It does not explicitly state when-not to use it versus siblings like ugcfans_ad_to_film or ugcfans_make_site_sting, leaving some inference to the agent.

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

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

Annotations only declare the generic profile (not read-only, not idempotent, not destructive), so the description carries real weight and delivers it: it spends account credits, explains the talking-cost relationship to avatar models, states the consent/rights gate for motion and swap, and says it returns a job (async). It does not cover job lifecycle details such as awaiting, cancelling, or failure behavior, which matters for a job-returning mutation.

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

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

Three dense sentences, front-loaded with purpose, then modes and cost, then prerequisites. Each sentence carries distinct information (mode semantics, credit cost, eligibility/consent), so nothing is filler, though the parenthetical '(a picture)' and the closing consent sentence are slightly compressed for the amount of constraint they encode.

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 signals the async contract ('returns a job') and covers prerequisites, rights gating, and cost for a 16-parameter tool that is fully schema-documented. It leaves the agent to discover job retrieval via siblings (get_job, wait_job), which is a minor gap rather than a blocking one.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine meaning by mapping behavior to mode: talking = speak a line, motion = follow a reference clip, swap = replace the person in a clip, product = hold a product picture. This lets an agent infer which of the 16 parameters apply to the chosen kind, beyond the schema's per-parameter prefixes.

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

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

Opens with a specific verb and resource ('Puts a saved person on screen and returns a job') and immediately enumerates the four modes (talking, motion, swap, product), so an agent knows exactly what class of output this produces. The 'saved person' scope and the per-mode behaviors distinguish it from generic siblings like ugcfans_make_video even without naming them.

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

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

Gives strong preconditions: the person must be saved with a portrait and, if real, recorded consent at ugc.fans/library, and motion/swap additionally require rights_confirmed: true set only after the person confirms use of the source clip. It also names ugcfans_list_models for pricing context. It stops short of routing the agent away from this tool toward specific alternatives, so it is clear context without explicit exclusions.

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

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

Annotations only cover the safety profile (non-read-only, non-destructive, non-idempotent, closed-world). The description adds genuinely new behavior: fixed 12s/8-scene output, text remaining editable, zero credit cost, and synchronous return of the film plus its first revision. That is substantial context beyond structured fields, though permission/auth requirements are not addressed.

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

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

Three dense sentences front-load the core action and output spec, then add the sibling contrast and cost/return facts. Every sentence carries information with no filler.

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

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

With no output schema, the description correctly compensates by stating the return ('the film and its first revision at once'), plus duration, scene count, editability, and cost. It does not cover async/job behavior, though the synchronous return framing largely addresses that for this creation tool.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description only reinforces the node_ids source and the 'chosen frame' notion, and never mentions key_phrase, so it does little beyond the schema baseline.

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 (Makes) and precise resource (a 12-second, 8-scene film from chosen page parts), and ties node_ids to their source (ugcfans_get_capture). It explicitly differentiates itself from the sibling ugcfans_make_launch_film, so an agent can pick between them without opening either schema.

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

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

The contrast 'Unlike a launch film its page text stays as editable text, so ugcfans_set_film_words can change it' gives a real selection criterion against the launch-film sibling and names the downstream editing tool. It stops short of an explicit when-to-use/when-not statement, but the routing context is clear.

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

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

Annotations only say this is non-read-only, non-idempotent, non-destructive. The description adds substantive behavior: it consumes account credits, it may price before making, it fails for unpriceable voices, and cloned voices require owner consent. That is meaningful disclosure beyond the structured hints, though job/polling semantics and failure modes remain 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?

Four dense sentences with the core action front-loaded before the credit, pricing, and consent caveats. No filler, though the pricing sentence is compressed enough to require a second read.

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

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

With no output schema, the description usefully states that a job is returned and that the audio is linked from its result, and it flags the billing and consent requirements. It does not explain how to wait on or retrieve the job, which matters given the async job model shared across siblings.

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 behavior the schema does not: the quote parameter's role in skipping the pricing step and the consequence of omitting it, plus the constraint that an unpriceable voice cannot be rendered. It also implies text and script are alternate inputs rather than required together, which the schema leaves implicit.

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 ("Speaks a line or a saved script in a saved voice") and goes further to describe the return ("returns a job whose result links the audio"). Speech synthesis is clearly distinct from every sibling (make_video, make_ad, write_script, etc.), so an agent can route to it without ambiguity.

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 real conditional guidance: without a quote it prices first, and voices that cannot be priced ahead cannot be made here, plus the consent prerequisite for cloned voices. It stops short of naming an alternative (e.g., ugcfans_estimate for pre-pricing, ugcfans_get_job/ugcfans_wait_job for result retrieval), so usage is implied rather than fully routed.

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

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

Annotations cover the safety profile (non-readOnly, non-idempotent, non-destructive), and the description adds material context: credits are spent per clip, the call returns a job rather than the finished clip, and omitting the quote downgrades the call to a cost estimate. It stops short of stating credit-refund or failure behavior, but the disclosed traits are substantial.

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 what it does, then the credit implication, then the hard prerequisite. No filler and every clause carries operational information.

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

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

With no output schema, the description correctly explains the return value (a job whose completion links the clip) and the cost-only fallback path. For a 7-parameter, non-idempotent generation tool, nothing an agent needs 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 the schema already documents every parameter including the quote's 'exactly this request' semantics. The description reinforces the quote requirement and start_image usage but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('makes a video clip from a prompt, optionally beginning on a still') and describes the async job contract plus the returned clip link. It is clearly distinguishable from sibling generators like ugcfans_make_image or ugcfans_make_ad.

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 prescribes the workflow: call ugcfans_estimate first and pass its quote, otherwise the call only returns cost and makes nothing. It also points to ugcfans_list_models for per-model pricing, giving the agent both prerequisites and the right companion 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 say readOnlyHint=false, idempotent=false, destructive=false. The description goes well beyond that: it discloses credit spend ('Spends a few of the account's credits'), the 3-minute length ceiling, the asynchronous job return shape, and crucially what is NOT returned (no footage, sound or words). That is exactly the extra behavioral context the annotations cannot carry.

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

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

Dense but front-loaded: the core action and its output come first, then cost, then the prerequisite. Some sentences are clause-heavy, but every sentence carries information an agent needs, with no filler.

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

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

With no output schema and only one required parameter, the description has to explain the return value itself, and it does: a job whose result is the breakdown. Combined with cost, length limit, and prerequisite disclosure, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% and the single 'source' parameter is fully documented in the schema, so the description need not re-explain it. The description only hints at the library-location concept via the upload URL. Baseline 3 applies since the schema does the heavy lifting.

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 (reads a reference video from the library) and enumerates the actual deliverable: hook, structure, shots, pacing and look, with still frames. This clearly distinguishes it from siblings like ugcfans_transcribe or ugcfans_make_video, which produce footage, sound or words this tool explicitly does not.

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

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

Provides a concrete prerequisite ('Upload the video at https://ugc.fans/library first') and a consent condition ('confirms the person may study the file'), which is real usage context. However, it never names an alternative tool or a when-not-to-use condition, so it stops short of full routing guidance.

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

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

Annotations already cover the safety profile (write, non-destructive, non-idempotent, closed-world). The description adds genuine context beyond them: no cost ('Free'), an explicit return value ('returns its id'), a consent prerequisite, and a post-condition ('A new presenter has no picture until its portrait is drawn there'). It does not restate the non-idempotent behavior, but the added disclosure is substantive.

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

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

Three sentences, front-loaded with verb, resource and return value, then eligibility and the presenter/portrait caveat. Every sentence carries information, though the final sentence about the missing portrait is a slightly tangential detail that could be trimmed or merged.

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 16-parameter, nested-object write tool with no output schema, the description supplies what the schema cannot: cost, the returned id, eligibility limits, and the consent prerequisite. Combined with 94% schema coverage, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 94% and every parameter, including the nested palette, is already documented in-schema with per-kind applicability. The description only reinforces the presenter case ('described in words, not a real person'), adding little beyond what the schema says, 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?

Opens with a precise verb+resource+outcome: 'Saves a brand kit, a product, a generated presenter or a stock voice to the library for reuse in ads, and returns its id.' The four kinds map exactly to the schema enum, so an agent can identify the tool and its scope without opening the schema, and it is clearly distinct from the make_* 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?

Gives an explicit eligibility rule with the reason: 'Only generated presenters ... and stock voices can be saved here: a real person's face or voice needs the consent the person records at https://ugc.fans/library.' This is a strong when/when-not statement, though it stops short of naming where the excluded case should go or naming any sibling alternative.

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

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

Annotations already cover read-only/idempotent/safe behavior, and the description adds useful context: it is free, needs no sign-in (auth requirement disclosed), and returns slug/name/description per item. It does not mention pagination or result-size limits, which is the only gap.

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 what is listed, then cost/auth, then how to consume the output. No filler.

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

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

With no output schema, the description compensates by describing the return shape (slug, name, sentence on what it makes) and the downstream slug usage. For a single-param, read-only discovery tool this is fully sufficient.

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

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

Schema coverage is 100% and the single 'query' parameter is fully documented in-schema (including 'leave out to list everything'). The description adds nothing further about the parameter, 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 (Lists) and resource (ad templates, ad features, creation modes) and even enumerates the fields of each entry (slug, name, one-sentence summary). No sibling tool overlaps this discovery role, so the agent can identify it immediately.

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

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

Clearly frames the tool as the discovery step whose slugs feed 'ugcfans_make_ad as template' or 'as feature', giving the agent an explicit downstream use. It does not state when NOT to use it or enumerate alternatives, but none of the siblings compete for this job.

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

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

Annotations already declare the write/non-destructive/idempotent profile, and the description adds real context on top: the edit produces a new revision while the earlier revision is left untouched (explaining why destructiveHint is false), matching is substring-based on text layers, and the call is free of credit cost. Cost and revision-persistence behavior are not derivable from 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?

Three short sentences, mutation scope front-loaded before the no-op caveat and the cost note. Every sentence carries information; the only drag is the slightly garbled 'gets replace' and an unexplained 'Free of credits' phrasing that could be stated more plainly.

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-required-param mutation tool with full schema coverage and no output schema, the description covers scope, persistence semantics, cost, and the no-op case. It never says what the call returns (e.g., the new revision identifier), which is the one detail an agent might need since there is no output schema.

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

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

Schema coverage is 100%, so the schema already documents film, revision, and the find/replace pairs and their ordering. The description still adds matching semantics not in the schema — that 'find' matches text layers whose words contain it (substring, not exact) — which materially affects how an agent constructs the replacements array.

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

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

States a specific verb and resource (change text in a film) and then sharpens scope: every text layer whose words contain 'find' gets replaced. It even distinguishes itself from the sibling ugcfans_make_launch_film by noting those films have no text layers, so an agent can tell them apart without opening schemas.

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

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

Provides a clear when-not condition: films produced by ugcfans_make_launch_film are effectively no-ops for this tool. It also implies the operation is a non-in-place edit that yields a new revision. It does not name an alternative tool for other kinds of film edits, so it stops short of a full when/when-not/alternatives treatment.

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

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

Annotations only say this is a non-destructive, non-idempotent mutation. The description goes well beyond that by disclosing the two expiry windows (6 hours vs 30 days), the Made with UGC Fans badge on showcase pages, that it is free, and that anyone holding the link can view the file without signing in. Public-exposure and lifetime details are exactly what an agent needs before sharing a file.

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

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

Four short sentences, front-loaded with the core action before the mode details. Efficient overall, though the final sentence partially restates the opening's 'opens for anyone who holds it' point.

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

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

With no output schema, the description should ideally say it returns a URL, which it does not. Otherwise it fully covers behavior, lifetime, and both parameters for this simple two-parameter 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 earns above baseline by giving the `kind` choice real meaning - link = 6-hour direct file access, showcase = 30-day badged page - which the enum description alone does not convey.

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

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

States a specific verb and resource: 'Makes a link that opens one file of the library'. The purpose is unambiguous and the sharing scope is spelled out. It does not distinguish itself from any sibling tool, but the sibling set is mostly film/render operations so collision risk is low.

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 through the link-vs-showcase durations rather than stated: an agent can infer 'use showcase for a longer-lived page' but there is no explicit when-to-use or when-not-to-use guidance, nor any named alternative. Adequate but leaves the selection rationale 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 the non-read-only, non-idempotent profile, and the description adds genuinely useful context: the operation is asynchronous ('returns a job'), it is priced ('Free of credits'), it is capped at 10 minutes, and it enumerates the result fields (transcript id, text, language, length). It does not mention how to await the job despite siblings ugcfans_get_job and ugcfans_wait_job existing, which is the one notable gap.

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?

Effectively two sentences, front-loaded with the action and constraints, then the cost and workflow hints. Dense but every clause carries information; the only slight awkwardness is a long compound first sentence.

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

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

With no output schema, the description compensates by describing the async job return and the eventual result fields. Combined with the prerequisite upload/discovery steps and the size limit, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and there is only one parameter, whose schema description ('The file's address in the library, out/...') matches the description's phrasing. The description repeats the library-address concept without adding syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Writes out the words of an audio or video file in the library') with concrete scope (max 10 minutes, built-in speech model). It clearly distinguishes itself from adjacent tools by naming ugcfans_list_files as the way to obtain the input and ugcfans_finish_clip as the downstream consumer.

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

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

Gives an explicit prerequisite workflow: upload to https://ugc.fans/library first, then resolve the address with ugcfans_list_files. It also tells the agent what to do with the result (transcript id feeds captions in ugcfans_finish_clip). It stops short of stating when transcription is unnecessary or naming an alternative transcription path, but as the only transcribe tool the routing need is low.

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

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

Annotations already establish read-only, idempotent, non-destructive semantics, so the bar is lower; the description still adds real value by disclosing the 45-second ceiling, the early-return behavior, and that the call costs nothing. It does not describe what a still-running job returns versus a finished one, but the core behavioral traits are covered.

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 with the key constraint (45s) front-loaded and the early-return rule immediately following. Slightly oblique phrasing ("as ugcfans_get_job does") and the trailing "Free." cost it a perfect score but nothing is wasted.

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

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

For a two-parameter polling tool with no output schema and full annotation coverage, the description supplies everything needed to invoke it correctly: the wait bound, the early-return semantics, and the equivalence to get_job's report. The only gap is not spelling out the shape of a still-running result, which is minor given the get_job reference.

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

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

Schema description coverage is 100%, so both parameters (job id and seconds) are already documented with type, range and default. The description echoes the 45-second cap and default but adds no format or edge-case detail beyond the schema, so it sits at the baseline.

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 (wait for a job) and scopes the behavior precisely: waits up to 45 seconds, returns early when the job ends. It explicitly differentiates itself from the sibling it most resembles, ugcfans_get_job, by framing the result as equivalent to that tool's output.

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

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

Clearly conveys the context of use — blocking wait with a 45s cap that returns as soon as the job finishes — which implicitly tells the agent to prefer this over repeated get_job polling. It notes the tool is free, but there is no explicit when-not-to-use or named alternative to wait_job.

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 mark this as a non-read-only, non-idempotent operation, and the description adds two facts annotations cannot convey: it 'spends a few of the account's credits' and it returns a job whose result holds the script (implying the async get_job/wait_job pattern). It does not describe failure modes, rate limits, or what an in-progress job looks like.

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 with no filler; the core action and the credit cost are front-loaded and the parameter-conditioning guidance follows. Is slightly run-on but every clause 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 12-parameter, zero-required, multi-mode tool with no output schema, the description covers what matters: the mode-selecting parameters, the cost, and the fact that the return is a job holding the script. Nothing critical is missing, though a pointer to the job-retrieval sibling would have closed the loop.

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

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

With 100% schema coverage the individual parameters are fully documented, so the baseline would be 3. The description adds real semantic value by explaining that hooks and translate_to are mode selectors that only apply when script is supplied, a conditional relationship the flat schema cannot express.

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 (writes) and resource (ad script), and enumerates the three distinct modes: new script from product/page_url, alternative hooks from a saved script, and translation. It is clear enough that an agent knows what it will get back, though it does not name which sibling to prefer (e.g. ugcfans_make_ad) for overlapping ad-writing needs.

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 conditions the modes: 'Give product or page_url to write a new script; give script with hooks (how many) or with translate_to (a language) to work on one.' This tells the agent exactly which parameter combinations select which behavior. It stops short of saying when NOT to use this tool versus the other ad-making siblings.

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