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 already declare readOnly, openWorld, idempotent and non-destructive, so the safety profile is covered. The description adds genuine context beyond that: the web-search-and-rank process, the 'ask' disambiguation flag, and the 'Free of credits' cost note, which an agent cannot infer from structured fields.

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

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

Four sentences, front-loaded with the core action before the workflow and return details. Information-dense with little waste, though the final 'Free of credits' fragment is slightly tacked-on and the mid-sentence clause about the rank/ask logic is a touch convoluted.

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

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

With no output schema, the description carries the return-shape burden and does so reasonably: each candidate's address, name, a sentence and the supporting evidence. Combined with the process and cost notes, an agent has what it needs, though the 'ask' flag's contract could be stated more crisply.

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 are already documented. The description reinforces that the query is a name or address and that country disambiguates same-named sites, but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: "Finds the website of a business from its name, or reads an address." The dual mode (name lookup vs address read) is explicit. It does not, however, differentiate itself from sibling business tools like ugcfans_get_business or ugcfans_read_business, leaving an agent to infer the boundary.

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 one conditional behavior — when two sites carry the name about equally, the 'ask' flag is true and the user should choose — which implies a follow-up path. But it never states when to prefer this tool over the related business siblings (get/read/save_business), leaving usage largely 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 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 cover safety (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely non-structured context: this is a cost-free call and it returns credit state, expiry timing, plan, and admission status. It stops short of describing refresh timing or what happens when credits are exhausted.

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 naming the resource first, then enumerating returned fields. Dense but every clause maps to a distinct return value; the trailing 'Free.' is terse but earns its place as a cost signal.

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

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

With no input parameters and no output schema, the description carries the return-value burden and does enumerate the key fields (credits left/granted/spent, expiry, plan, admission). It is nearly complete for a zero-arg status tool, lacking only format details such as units or expiry date style.

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

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

Zero parameters, so the baseline of 4 applies; there is no argument surface for the description to explain. The implicit subject ('the signed-in account') correctly tells the agent no identifier needs to be supplied.

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') and a specific resource (the signed-in account's credits, expiry, plan, and UGCFans admission status). Among a sibling set dominated by generation tools (make_video, make_image, estimate), this is unambiguously the account-status read 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?

Usage is implied rather than stated — the trailing 'Free.' signals this costs no credits, which is a mild routing hint against paid siblings like estimate or make_video. However, no explicit when-to-use condition or named alternative is given.

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, so the safety bar is low. The description adds real value beyond that: the returned content (progress, profile, facts with provenance and verification status) and the cost signal ('Free'), which is not in the annotations. No output schema exists, so this return-shape disclosure is doing useful work.

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?

It is a single sentence plus a one-word fragment, so it is not bloated, but the structure is awkward and the dense run-on clause about facts/provenance is hard to parse. The trailing 'Free.' is abrupt.

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 tool with no output schema, the description does roughly sketch the return payload and states cost. But the garbled wording and the absence of any pointer to ugcfans_read_business as the prerequisite step leave an agent to infer too much of the lifecycle.

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 both 'business' and 'search'. The description restates the optional search ('searches the pages for words') without adding format or syntax, 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 verb+resource are present ('Reads a business') and it gestures at returning profile, facts, and reading progress. But the phrasing is garbled ('how far the reading is', 'whether it stands or waits for a yes') and it never distinguishes this from siblings like ugcfans_read_business or ugcfans_find_business, which likely share the same noun.

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

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

The phrase 'a business that was read' implies a prerequisite that a read job must have run first, and the schema confirms the id comes from ugcfans_read_business. However, no alternatives are named and there is no explicit when-to-use vs when-not guidance; usage is only inferred.

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

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

Annotations already declare 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 cover read-only, idempotent, non-destructive. The description adds genuinely useful behavior beyond that: it is free, needs no sign-in, and crucially that the response differs by auth state (full price list when signed out vs. account-specific offering when signed in). This auth-dependent branching is exactly the kind of context annotations can't 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?

It's a single dense sentence that is front-loaded with the core purpose, which is good, but the latter half is a run-on clause stacking auth-state behavior and model-id usage. It earns its content but readability suffers from over-packing.

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, so the description carries return-value burden, and it does explain what comes back (qualities, per-unit credit costs, plan-lock status, model ids). Missing details like pagination or the shape of the plan-lock field, but largely complete for a zero-parameter catalog list.

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 kind parameter with an enum is fully documented in the schema. The description doesn't elaborate on the parameter semantics, but baseline 3 is appropriate given 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 (lists) and resource (what UGCFans makes at each quality, with credit prices), and distinguishes it from siblings by naming that it feeds estimate and the make tools with model ids. An agent can tell this is the catalog/discovery tool, not a make or estimate 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?

Conveys when to use it – free, no sign-in needed, and it's the source of model ids for ugcfans_estimate and make tools. It doesn't explicitly name exclusions or contrast against siblings that also return model info, but the routing role 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 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 cover safety flags (non-read-only, non-idempotent, non-destructive), and the description goes well beyond them: the quote-then-spend credit model, the cost being tied to the avatar model (pointing at ugcfans_list_models), the consent/portrait prerequisite, and the rights_confirmed gate with its provenance. These are material operational facts an agent would otherwise have to guess.

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

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

One dense paragraph, front-loaded with the mode enumeration and the quote/spend rule before the prerequisites. Nearly every clause carries information, though the sentence packing the four modes is long and could be broken for scanability.

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 17-parameter mutation tool with no output schema, the description supplies the prerequisites, the pricing/no-op branch, and the fact that a job is returned. It does not say how to follow up on the returned job (siblings ugcfans_wait_job/get_job exist) or what the failure modes are, which is the main remaining 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 baseline is 3, but the description adds cross-parameter meaning the schema cannot: quote is the held quote that authorises spend for that exact request, and rights_confirmed is only valid after the person confirms use of the source clip. It also disambiguates text/script/speech as three ways to drive a talking clip.

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 ("Puts a saved person on screen and returns a job") and then enumerates the four modes (talking, motion, swap, product) with a one-line definition of each. That makes the tool's scope unmistakable, though it never names or contrasts a sibling (e.g. ugcfans_make_video, ugcfans_finish_clip) to anchor it in the toolset.

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

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

Explicit routing rules: without a quote it returns cost and makes nothing, with a held quote it spends credits, and motion/swap require rights_confirmed: true which is only granted after the person confirms rights to the source clip. It also states the prerequisite that the person must be saved with a portrait and recorded consent. An agent knows exactly when it may and may not call this.

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?

Beyond annotations (which only cover readOnly/idempotent/destructive/openWorld), it discloses credit expenditure, the two-step estimate-then-confirm flow, and the cloned-voice consent requirement — exactly the operational context 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?

Front-loaded with purpose, then the cost/quote flow, then the consent caveat. Dense but every sentence carries information; the phrasing 'a voice that cannot be priced ahead cannot be made here' is slightly convoluted but 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?

No output schema exists, and the description covers the key outputs (a job, credits spent, linked audio) plus prerequisites (saved voice, consent). It could mention polling via get_job/wait_job, but the agent has enough to invoke and interpret results 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 baseline would be 3, but the description adds real meaning to the 'quote' parameter (its presence vs absence changes the call's behavior entirely) and clarifies the text vs script alternatives, which the schema does not.

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 + resource ('Speaks a line or a saved script in a saved voice') and states the return ('a job whose result links the audio'), which cleanly separates it from sibling generation tools like make_video or write_script.

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

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

It gives concrete procedural guidance: call without a quote to get cost, then re-issue with the quote after the person confirms, and warns that unpricable voices cannot be made here. It doesn't route to sibling tools, but the when/how guidance is unusually 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 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 declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the description is not burdened with that. It adds real behavioral context beyond them: the 25-page crawl cap, the asynchronous job return model, persistent file writes, and that conflicting or unproven facts are held pending a confirmation. It could still say more about permissions 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?

Effectively one dense sentence, but it is front-loaded with the core action and the follow-up tool reference lands at the end where it belongs. The stacked parentheticals are informative rather than redundant, though they make it heavier than it needs to be.

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 contract: an async job whose result is a business id, plus the tool to read it. The only real gap is the ambiguous 'held for a yes' phrasing, which leaves the human-confirmation workflow underspecified for an agent.

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

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

Schema description coverage is 100% with a single fully documented 'url' parameter, so the baseline is 3. The description adds no URL format, canonicalization, or scheme guidance beyond what the schema already states ('The business's website address.').

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 business's website page by page') and goes further by naming the artifacts produced (business.md profile and canonical facts). This clearly separates it from sibling tools like ugcfans_capture_website, ugcfans_find_business, and ugcfans_get_business.

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 returns a job whose result is a business id, and explicitly routes the agent to ugcfans_get_business to read that result, plus notes it is 'free of credits'. It does not, however, state when to prefer this over lookalikes such as ugcfans_capture_website or ugcfans_find_business, so no exclusion guidance.

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

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

Annotations only cover safety/idempotency flags (readOnlyHint=false is consistent with the credit spend described). The description adds real behavioral context the annotations lack: the two-step cost/quote flow, that credits are consumed, the 3-minute limit, and that only derived analysis is kept and none of the source footage, sound or words. It stops short of explaining how to retrieve the job result (get_job/wait_job).

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 what the tool does and its output before the operational details. The telegraphic style ('makes nothing', 'spends a few of the account's credits') is dense but every clause carries information; no padding 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?

Given an async job-based tool with no output schema, the description covers cost behavior, output contents, limits, the rights prerequisite and the upload step. The one gap is guidance on how to obtain the job's result, which is left to sibling tools.

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 goes beyond the schema by explaining that quote is optional and why: omitting it returns only a cost, while a held quote spends credits, which clarifies the intended two-call flow. source and rights_confirmed semantics are largely restated from 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 (reads), resource (reference video up to 3 minutes in the library) and result (a job that returns a breakdown of hook, structure, shots, pacing and look). The output contents are enumerated, so an agent can distinguish this from siblings like transcribe or make_video without opening a schema.

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

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

Gives clear prerequisites and workflow: upload the video at the library URL first, and the quote gating (without a quote it returns the cost and makes nothing; a held quote spends credits). It does not explicitly name alternate tools or state when-not-to-use, so it falls short of the top band.

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 establish non-destructive, non-read-only, non-idempotent behavior, so the bar is lower; the description adds real context on what is written (brand kit, products with pictures, business.md, facts.json kept "for later makers"), which facts are excluded (unconfirmed ones), and that it is free. It does not address repeat-save/duplicate behavior despite idempotentHint=false.

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

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

It is short and front-loads the verb, but the idiosyncratic phrasing ("the facts that stand," "facts that wait for a yes," "later makers") costs clarity, and the trailing "Free." fragment is awkwardly attached. Not wasteful in length, but not maximally crisp.

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 write tool with full schema coverage, annotations covering the safety profile, and no output schema, the description adequately covers what is produced and which inputs qualify. The main remaining gap is repeat-save/idempotency behavior.

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 a single parameter and 100% schema description coverage, the schema already explains that "business" is the id from a finished ugcfans_read_business job. 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?

The description leads with a specific verb+resource ("Saves ... as a brand kit and products") and names the concrete artifacts produced (business.md, facts.json). It is clearly distinguishable from read-side siblings like ugcfans_read_business or ugcfans_get_business, though it never names an alternative explicitly.

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

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

Usage is implied rather than stated: it depends on "the finished ugcfans_read_business job" and only persists facts that "stand," while "Facts that wait for a yes are not saved" scopes the inputs. There is no explicit when-to-use vs when-not guidance and no mention of prerequisites or alternatives such as ugcfans_save_asset.

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. The description adds value beyond that by stating cost/auth posture (free, no sign-in) and by describing what each returned record contains, which the annotations do not cover.

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

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

Two tight sentences: the first defines the resource and return shape, the second covers cost/auth and downstream slug usage. No filler, and the identifying information 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 single-optional-param, read-only lookup with no output schema, the description supplies everything an agent needs: what comes back, that it's free/no-auth, and how to consume the slugs. Nothing material 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 `query` parameter is fully documented in the schema (with examples and the 'leave out to list everything' behavior). The description adds nothing 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/searches) and resource (ad templates, ad features, creation modes) and even describes the per-item return shape (slug, name, one-sentence description). This clearly distinguishes it from the make_*, get_* and list_* 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 concrete downstream routing: a template slug is passed to ugcfans_make_ad as `template`, a feature slug as `feature`. It also notes the tool is free and needs no sign-in. It lacks explicit when-not-to-use guidance, but no sibling overlaps this lookup role, so the gap is minor.

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

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

Annotations already 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?

With annotations declaring non-readOnly, non-destructive, non-idempotent, the description complements them well by disclosing link lifetimes (6 hours / 30 days), cost ('Free'), and the public-access implication ('anyone with the link can see the file until it expires'). It omits whether links can be revoked or how many can exist concurrently, which would round out the security picture.

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, zero filler, and the core behavior is front-loaded before the mode/lifetime detail. Every sentence contributes something an agent would otherwise have to guess.

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 tool with no output schema, the description covers purpose, modes, lifetimes, cost, and access scope. The one gap is that it never says what comes back (presumably the generated URL or link object), which the missing output schema would otherwise need to cover.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the enum's 'link opens the file itself; showcase is a page' by attaching distinct expiry windows to each mode. That adds decision-relevant meaning the schema does not carry.

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 (makes a link) and a precisely scoped resource (one file of the library), plus the access condition (anyone with the link, no sign-in). No sibling tool competes for this behavior, so no differentiation is needed. An agent immediately knows this is a share-link generator, not a file lister or content creator.

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 effectively routes the choice between the two modes by giving the durability of each ('a link lasts 6 hours; a showcase page ... lasts 30 days'), which is exactly the tradeoff an agent needs to pick 'link' vs 'showcase'. It stops short of an explicit 'use this when...' clause or prerequisites for calling it.

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 only declare readOnly=false/destructive=false/idempotent=false, but the description goes well beyond them: it discloses credit consumption, the quote-hold confirmation flow ('without one, returns the cost and makes nothing'), and that the call is asynchronous, returning a job whose result holds the script. This is exactly the billing and async behavior an agent needs before invoking.

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 sentences, front-loaded with the core action and mode enumeration, then billing behavior, then parameter routing. Dense but every sentence earns its place; no filler or restatement of the title.

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

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

For a 13-parameter, zero-required, no-output-schema tool, the description covers the modes, the credit/quote gate, and the job-return shape. It omits guidance on polling the returned job (ugcfans_get_job/ugcfans_wait_job) and on which parameter combinations are invalid, but nothing essential to invoking 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 coverage is 100%, so the baseline is 3, but the description adds genuine cross-parameter semantics the schema cannot express — that product/page_url select the 'new script' mode while script+hooks or script+translate_to select the 'work on existing script' mode. It does not cover defaults for seconds/language beyond what the schema states.

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 ('Writes an ad script') and enumerates all three operating modes (new script from product/page_url, alternative hooks from a saved script, translation). An agent can distinguish this from siblings like ugcfans_make_ad or ugcfans_estimate without opening the schema.

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

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

Gives explicit routing rules: '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.' It also states the when-not condition for the quote parameter — without a held quote nothing is made and only a cost is returned.

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