CartViral

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

With annotations declaring readOnlyHint=false, openWorldHint=true and idempotentHint=false, the description still adds real signal: the operation is free, it is asynchronous, and the result must be retrieved by polling list_creations, where it arrives as data. That polling instruction is exactly the kind of context annotations cannot express. It omits processing time and what happens on failure/duplicate submission, which idempotentHint=false makes relevant.

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 payoff (what the breakdown contains), then the alternative route, then the retrieval mechanics — a sensible priority order for an agent. It is dense but each clause carries information; the fragments ('Free.') are terse rather than wasteful, though the punctuation style makes it slightly harder to parse than prose.

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, so the description must convey what comes back — and it does, both by listing the analysis components and by explaining that the result is data retrieved via list_creations. The main residual gap is the mechanics of the async handoff (does the call return a job or creation id? how long does processing take?), which is only gestured at with 'Poll list_creations'.

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 description for 'video' already spells out the accepted link forms (CartViral /u/ link or direct public https file link, downloaded once). The description adds nothing further about the two parameters and never mentions 'language', so this is the baseline case where the schema does all the work.

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 enumerates concrete deliverables — hook mechanism, beat timings, spoken/shown content, on-screen text style, measured cuts — so an agent knows this is a structural analysis of a video rather than a creation tool. The verb is implicit (the title carries 'Break down'), and the opening phrase 'Why a video works' is a bit indirect, but the resource and scope are unmistakable and clearly separated from remake_from_reference.

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 names the sibling alternative explicitly ('To make the same structure with your product or without one, use remake_from_reference'), which is a genuine routing rule. It also flags 'Free' as a selection factor. It stops short of stating exclusions (e.g., don't use for videos you don't have a direct file link for), so it is clear context rather than a full when/when-not matrix.

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

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

Annotations only declare this is a non-readOnly, non-idempotent, open-world write; the description goes well beyond them by disclosing credit cost, daily rate limit, that a public page is published externally, and that the account's referral code is embedded. These are exactly the traits an agent needs before invoking a costly, externally visible operation.

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?

Everything is packed into one dense but front-loaded sentence: action, cost, output, incentive, limit, and targeting each appear once with no repetition. It is slightly run-on and could be split for scannability, but no sentence 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 tool that spends credits and publishes an external page, the description covers cost, rate limit, returned artifact, monetization, and ideal target brand type. With one simple parameter and no output schema, an agent has everything required 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?

Only one parameter and schema coverage is 100%, so the schema already documents it. The description restates it as 'brand's store or product link' but adds no format or validation guidance beyond the schema wording — the expected baseline of 3.

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

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

States a concrete verb chain (import link → generate 3 clips → return public pitch page) with a named resource and output. It is unmistakably different from siblings like list_pitches or import_products, and even discloses the cost (18 credits) and the referral mechanics that define the action.

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 triggering input ('paste a brand's store or product link') and a qualifying condition ('Offers track sales in Shopify, so pitch Shopify brands'), plus a hard cap of 10 a day. It stops short of explicitly naming alternatives (e.g., list_pitches to review existing pitches), so it falls just under full when-to-use guidance.

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

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

Annotations already declare non-readonly, open-world, non-idempotent behavior, and the description adds genuinely non-structural facts: priced by length, premium-mode requirement, a 15 s duration cap, and async polling via list_creations. It stops short of describing failure modes (e.g., what happens when consent is false or premium is off).

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 compact paragraph: what it does first, then cost/gating, then the consent prerequisite, then the polling instruction. Every clause carries operational information; nothing is padding.

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 4-parameter async generation tool with no output schema, the description covers purpose, cost, availability gate, required consent, duration limit, and how to retrieve results. An agent can call and follow up without further instructions.

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 the 15 s video-length constraint that the schema does not encode, and reinforces that the image is a real person's photo when consent applies. Reasonable lift over the schema's own text.

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 precise transformation: the person from a photo repeats the movement of a reference video, with concrete examples (dance, gesture, walk). This is clearly distinguishable from siblings like make_talking_photo or remake_from_reference 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?

'Only when premium video is switched on' is an explicit gating condition, and 'Needs consent=true for a real person' plus 'Poll list_creations' qualifies usage. It never names a competing sibling tool, so routing versus remake_from_reference is left implicit.

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

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

Annotations already declare a non-read-only, open-world, non-idempotent, non-destructive call, and the description adds real behavioral facts on top: a 2-credit cost, that the output is exactly two portraits, that a photo is downloaded once, and that real-person photos require consent. It does not cover failure modes or what happens if consent is missing despite a photo being supplied.

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

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

Two dense sentences that front-load what the agent gets (two portraits) and then the follow-up action. The phrasing is slightly telegraphic ('who, age, look, or from a real person's photo with consent'), but nothing is padding.

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-value burden and does state that two portraits come back plus the credit cost and the consent precondition. The lifecycle is adequately covered; only the edge cases around an unsaved character and consent rejection are 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 60%, and the description echoes the field intents (look, age, photo with consent), so it adds a little framing but no syntax or format detail beyond the schema. The 'who' mapping to the gender parameter is left implicit, and gender is never named in prose.

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 says the tool produces 'two portraits of a recurring person for the brand' and enumerates the dimensions it controls (who, age, look, or a consenting real person's photo), which is a concrete verb+resource. It partially distinguishes itself from image-generation siblings by naming save_character, generate_clips and remake_from_reference, though it never explicitly contrasts with create_image or generate_photos.

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 lays out the downstream workflow explicitly ('Then save_character with the portrait you like') and explains why a character_id matters for generate_clips and remake_from_reference. It stops short of stating when NOT to use this versus create_image/generate_photos, so it is clear context rather than full when/when-not 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?

Adds value beyond annotations (which only declare openWorld, non-idempotent, non-destructive) by disclosing cost ('1 credit per image'), allowed output counts (1, 2 or 4), the reference-photo cap, and that results are asynchronous and must be retrieved via list_creations. Missing only latency expectations and failure/retry 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 purpose, then progressively adds constraints, cost and next step with no filler. The sentence fragments are dense to the point of being slightly clipped, 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 an async generation tool with no output schema, the description supplies what matters: credit cost, batch size options, reference limits, and the exact follow-up call to retrieve results. A note on how long generation takes, or what the initial call returns, would close the 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 coverage is 75%, and the description still adds meaning: reference photos are characterized by role (a face, a product, a style, a layout) and the 16:9 aspect is tied to the 'covers and YouTube thumbnails' use case. It does not retread the prompt-format guidance already in 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 ('Images from your own prompt'), and crucially distinguishes itself from sibling generators via 'Not tied to the catalog' — separating it from generate_photos, generate_static_ads and remake_from_reference. The listed output types (covers, thumbnails, banners, posters) pin down the scope further.

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 usage contexts (covers and YouTube thumbnails → use 16:9, banners, product scenes, posters) and an exclusion ('Not tied to the catalog'), plus the follow-up step 'Poll list_creations'. It stops short of naming the alternative tool an agent should pick when the image IS catalog-tied, so the routing is implied rather than explicit.

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

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

Annotations already declare the write/open-world/non-idempotent profile, and the description adds the cost model (2 credits, premium more) and the asynchronous polling workflow, which are genuinely useful beyond the structured fields. It stops short of saying what identifier is returned 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?

Two compact sentences, front-loaded with the capability statement followed by cost and polling guidance. Enumeration of camera moves is slightly redundant with the schema but not wasteful.

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 duration, input limits, cost, model selection pointer and how to retrieve results — enough for a 7-parameter creation tool with no output schema. Minor gaps remain around error cases and whether the reference image becomes a start frame in practice.

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 71% schema coverage, the schema already documents model, aspect, prompt and reference_images. The description restates the camera enum values and the 3-photo cap without adding syntax or interaction rules, so it adds marginal value over 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+resource ('A short video (4-10 s) from your own prompt') plus its distinctive capabilities: reference photos, camera moves, sound. It clearly separates itself from create_image, generate_clips and make_cinematic by scoping duration and inputs.

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 actionable routing: check get_create_options for premium models and poll list_creations for results. It does not explicitly say when to prefer this over create_image or generate_clips, so the sibling differentiation is implied rather than spelled out.

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

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

Annotations only declare the generic mutation/safety profile; the description adds the traits that actually matter: 3 credits per set charged from the account, a few minutes to render, automatic refund on failure, and server-side rotation when format/style are omitted. That async-plus-cost-plus-refund picture is exactly the behavioral 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?

Four tight sentences, front-loaded with what gets produced and for whom, then cost/latency, then parameter behavior, then the required next step. No filler and no repetition of enum values already in the schema.

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

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

No output schema exists, and the description covers queuing, cost, timing, failure refund, and how to retrieve results via list_carousels. The one gap is what the call itself hands back (a job or carousel id) needed to correlate the later poll.

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

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

Schema coverage is 100%, so baseline is 3, and the description earns above it by explaining what 'format' actually controls (the content idea, with examples) versus 'style' (the visual look), plus the non-obvious semantics of omitting either — rotation into a combo not recently tried. product_id is left to 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 — 'Queue a multi-slide carousel (Instagram and TikTok slides) for one catalog product' — and immediately scopes it to real product facts. It is clearly distinct from list_carousels, which is named as the polling companion, and from the other generate_* siblings by naming the output medium.

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

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

Gives clear operating context: one catalog product per call, optional format/style with rotation on omission, and an explicit follow-up step ('Poll list_carousels for download links'). It does not, however, say when to choose this over adjacent generators like generate_static_ads or generate_clips, so the alternative-selection guidance is incomplete.

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

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

Adds substantial context beyond the annotations: per-type credit costs charged from the account, automatic refund on failed render, 10-15 minute render latency, and the async queue-then-poll workflow. These are exactly the facts an agent needs that readOnlyHint/destructiveHint cannot convey.

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 scoped well, but the clip_type inventory is a dense run-on of nested parentheses that takes effort to parse. Every sentence carries information, so nothing is wasted, but formatting as a list would improve 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?

Covers the full lifecycle: cost, latency, refund behavior, format constraints, and next step (polling list_clips), which compensates for the absence of an output schema. Only missing piece is any guidance on the count parameter and whether repeated calls are deduplicated (idempotentHint=false is not addressed).

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

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

Schema coverage is 67%, and the description adds real meaning where it matters most: the format family must match clip_type (story for ai_story/ad, ugc for avatar, none for montage), which is a constraint the schema text only partly implies. It also explains clip_type values with costs. The count parameter is never mentioned, leaving its 1-5 range purely to 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?

Opens with a specific verb and resource plus the output format: queue vertical 9:16 clips (TikTok, Reels, Shorts) of one catalog product. The four clip_type variants are each described concretely, so an agent knows exactly what artifact it gets and can separate this from siblings like create_video or create_image.

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

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

Gives explicit selection criteria per clip_type with credit costs (montage 1, ai_story 6, avatar 12, ad 6), states that ad is legacy and equivalent to ai_story, and names the follow-up step (poll list_clips for download links). Small gap: it doesn't say when to prefer this over create_video/make_talking_photo, but the internal routing guidance is unusually strong.

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 it discloses credit costs, a refund-on-failure policy, expected render time, and the exact output artifacts (square 2000x2000, portrait 1080x1350, plus a zip of the set) — substantial context the annotations do not carry. The one gap for a non-idempotent, credit-charging queue operation is that it never warns against retrying or re-queuing a set that may already be in flight, which is the main way an agent would burn credits.

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

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

The action and the format/credit breakdown are front-loaded, and the operational facts (render time, artifact sizes, refunds, polling) are packed tightly with little waste. The single long sentence holding all three format descriptions is dense but still readable.

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 what comes back (two sizes plus a zip) and where to find download links, so an agent knows the full call-and-fetch cycle. The missing definition of the photo_tryon format is the remaining hole; everything else needed to call it correctly is present.

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

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

The description does the heavy lifting the schema omits by explaining what three formats produce and what each costs, which is real added meaning. However, the schema enum contains four values and only three are covered: photo_tryon is listed in the enum but never explained or priced, leaving the agent guessing on a valid input. With 50% schema coverage and one enum value undocumented in both places, this lands at minimum-viable-plus.

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?

"Queue a set of AI photos for one catalog product" gives a specific verb (queue), resource (AI photo set), and scope (one catalog product), which cleanly separates it from create_image, generate_static_ads, make_angles and the other visual siblings. An agent can route to it without opening the schema.

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

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

It supplies a prerequisite (photo_infographic "needs enough facts on the product page") and an explicit next step ("Poll list_photo_sets for download links"), which is the practical workflow guidance an agent needs. It stops short of naming when to prefer a sibling such as create_image or make_angles instead, so there is no explicit exclusion rule.

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 safety hints, but the description adds substantial cost and lifecycle context they cannot express: 4 credits per set regardless of template count, credits charged from the account, automatic refund on a failed set, and 3 render sizes per template. It also states the queuing/async nature and points to the polling tool, so the agent knows the result is not immediate.

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?

Purpose and cost are front-loaded and every sentence carries operational information; nothing is padding. The inline parenthetical catalogue of six templates is dense and slightly harder to scan than a list, but the information is not redundant.

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

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

There is no output schema, but the description tells the agent results arrive asynchronously and must be fetched via list_static_ads, and covers cost, refund behavior, render sizes, and template defaults. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the description goes further by defining what each of the six template ids actually produces (e.g. 'us_vs_them — a side-by-side comparison, never names a competitor'), which the enum alone does not convey. product_id is only glossed as 'one catalog product' — the schema's 'from list_products' carries that weight.

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 — 'Queue a set of static ad images (Meta, TikTok) for one catalog product' — with the key qualifier that it builds from the product's own photos. An agent can distinguish it from create_image, generate_photos, and generate_carousel from the first clause alone.

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

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

Gives clear operating context: one catalog product, optional template subset, 'Leave templates out to get all 6 of them', and the follow-up step 'Poll list_static_ads for download links'. It stops short of naming an alternative tool (e.g. generate_carousel or generate_photos) and when that would be preferred.

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=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds context beyond that: results are scoped to the calling API key, the Earn profile may be absent ("if any"), and credit-pack output reflects a live promotion such as Black Friday x2, warning the agent that pricing content is time-sensitive.

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 dense sentence, front-loaded with the resource identity before the content list, and every clause describes a distinct returned field rather than padding. It would read better split into a purpose sentence plus a returns list, but no wording 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?

There is no output schema, so the description carries the full burden of explaining return values, and it does so item by item, including volatile and conditional elements (promotions, optional Earn profile). For a zero-parameter read tool with annotations covering the safety profile, nothing an agent needs is missing.

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

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

The tool takes zero parameters, so there is nothing to document and the baseline of 4 applies. The description correctly implies a no-argument call by framing the account as implicitly derived from the API key.

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

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

The description names the exact resource ("The CartViral account behind this API key") and enumerates its contents: plan, billing interval, credit balance, per-clip credit prices, plan prices on both intervals, credit packs, and the Earn profile. No sibling tool touches account or pricing data, so an agent can distinguish it from every generate_*/list_* tool 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?

The closing "Call this first." is an explicit ordering directive that tells the agent when to reach for this tool relative to the generation toolset. It does not name exclusions or a case where this tool should be skipped, so it falls short of full alternatives 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 cover the safety profile (non-destructive, idempotent, closed-world), so the description's main contribution is the credit and caching model: first write costs 1 credit, repeat calls for an unchanged product are free, cached per product per tool. That is genuinely useful cost/side-effect information an agent cannot get from annotations. It doesn't say what happens on a missing or changed product beyond invalidation, nor any error 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?

Dense and front-loaded with a consistent per-enum pattern that scans quickly; nearly every clause carries information. The opening phrase 'One of Text & SEO's 4 more tools' is filler that delays the actual purpose by a 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 well by describing the shape of each artifact and the caching/credit model. The remaining gap is return structure — an agent cannot tell whether output is structured JSON, markdown, or free text, which matters for a text-generation tool.

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

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

Schema coverage is already 100%, but the description goes well beyond the schema's terse 'Which Text & SEO tool to generate' by specifying the exact output of each enum value (counts of texts, headlines, hashtag sets, brief sections, calendar formats). It also ties product_id to meaning by explaining that caching is per product and invalidated when the product changes.

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

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

The description names the resource (ad copy, social captions, creator brief, content plan) and enumerates exactly what each of the four enum values produces, so an agent can tell what it will get. The verb itself is implied rather than stated outright — the opening 'One of Text & SEO's 4 more tools' is awkward framing before the actual purpose appears. It does not differentiate from the sibling get_listing_copy, which also generates copy.

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 enum-by-enum breakdown effectively tells the agent which tool value to pick for which need, and the fact-grounding rule ('never invented specs, claims, discounts or reviews') sets an explicit constraint on use. What's missing is guidance on when to choose this over sibling copy-generation tools, which the description never addresses.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the call is 'Free' (no credits consumed), which matters for a pricing tool, and it enumerates what the payload contains. It stops short of describing the response shape or size.

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

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

A single front-loaded sentence with no filler; the cost/credit angle appears first and the 'Free' tag lands as a useful closer. The embedded list is dense and slightly crammed, but every item corresponds to real returned content.

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 burden of explaining return values, and it does so by enumerating models, credits per length, frames, camera moves, moods and per-tool prices. For a zero-parameter reference tool this is nearly sufficient; only the response structure (e.g. per-tool vs. flat listing) is left unclear.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly implies no input is required by framing it as a lookup of what tools accept.

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 the resource clearly: a catalog of what the Create tools accept (video models, frames, camera moves, moods) and what they cost in credits. The verb is implicit ('what ... accept and cost') rather than an explicit 'returns', but an agent can tell this is a static reference/discovery lookup rather than an action tool. It is distinguishable from the create_* siblings, though it never names 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?

Usage is only implied: an agent must infer it should call this before invoking create_video or create_image to learn pricing and options. There is no explicit 'use this when...' statement, no mention of alternatives, and no note that it takes no arguments and is safe to call freely.

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 well beyond the annotations: it discloses that a first write costs 1 credit while repeat calls on an unchanged product are free (consistent with readOnlyHint=false and idempotentHint=true, not contradicting them), and that copy is cached per product until it changes. It also states a hard content constraint (only real product facts; no invented specs, claims or reviews), which is behavioral context an agent cannot get from the schema.

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

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

Front-loaded with the purpose, then the deliverables, then the caching/credit model — a logical order with no filler sentences. The long comma-separated deliverable list is dense but each item carries real selection value.

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

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

There is no output schema, so the description must describe the return, and it does so exhaustively by naming every artifact produced per channel including JSON-LD types. Combined with the cost/caching behavior and the source-of-truth constraint, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% and the single product_id is already documented as coming from list_products. The description reinforces the one-product scope ('for one catalog product'), but adds no new 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 concrete verb+resource ('marketplace-ready copy for one catalog product') and enumerates the exact deliverables across Amazon, Shopify, Etsy and GEO outputs, so an agent knows precisely what it gets. It does not differentiate itself from the sibling get_copy, which is the only thing keeping it from a 5.

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: call this when you need channel-specific listing/SEO copy for a product already in the catalog, and the 'same claims as its clips' line hints at a consistent-content workflow. But there is no explicit when-not guidance and no named alternative (e.g. get_copy) to route between, leaving the choice 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 openWorld, non-read-only, idempotent, non-destructive; the description adds real value on top by disclosing the 750-product cap for full-catalog imports and that repeat imports update existing products in place. It leaves out what happens on partial failures or whether a 750-product import is synchronous, which keeps it below 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?

Front-loaded with the verb and resource, and every clause carries distinct information (source types, catalog cap, in-place update). It is dense with enumerated examples but none are padding; a slight trim of the site list would improve 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 two-parameter import with full schema coverage and no output schema, the description covers sources, limits, and idempotency well. The remaining gap is what the call returns or whether a large catalog import is long-running — information an agent would want before invoking it on a 750-product store.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond the schema's generic 'Public store or product page URL' by mapping specific link categories to specific import behaviors. The optional `html` parameter is left entirely to the schema, which is acceptable given full coverage.

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

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

States a specific verb and resource (import products into the account's catalog) and then enumerates the distinct source types that can be imported — Shopify storefront, WooCommerce store, or a single product page — so an agent can tell exactly what this does versus list_products. The scope distinction (whole catalog vs. single product) is explicit.

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 usage context: give it a public link and the behavior depends on the link type, plus re-importing the same link updates in place rather than duplicating. It does not name an alternative tool or state when NOT to use it (e.g., private/authenticated store URLs), so it falls short of explicit alternative routing.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the call yields a personal tracking link and is free, but says nothing about what happens on repeat joins, auth requirements, or failure modes for non-live offers.

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 with the audience and outcome front-loaded and no wasted clauses. The trailing 'Free.' is terse but carries real decision-relevant information, so it earns its place.

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

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

For a one-parameter, non-destructive, idempotent action with full schema coverage and annotations, the description covers the essential outcome (a tracking link). It is nearly complete, with only edge-case behavior for non-live or already-joined offers left unstated.

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

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

There is a single parameter with 100% schema description coverage, and the schema already tells the agent to take offer_id from list_offers. The description adds no further meaning 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 ('join') and resource ('brand offer') plus the outcome ('get your personal tracking link'), which clearly separates it from list_offers and the generation siblings. It stops short of naming an alternative tool explicitly, so it is clear but not maximally differentiated.

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?

'For creators' and 'live brand offer' imply the audience and a prerequisite (the offer must be live), and the schema points to list_offers as the source of offer_id. However, there is no explicit when-to-use/when-not-to-use guidance or named alternative, so usage is only implied.

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

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

The annotations already mark this as read-only. The description adds newest-first ordering, a scope of recent items, and the fact that download links appear only once rendering is done. It also describes the returned fields, which matters because there is no output schema.

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

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

A single dense sentence that packs in ordering, status and output contents. It is efficient but somewhat run-on, and it opens with a noun phrase rather than a verb.

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

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

For a simple one-parameter read tool with no output schema, it explains the return contents well. Minor gaps are the undocumented limit parameter and the lack of any note on pagination or what counts as 'recent'.

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 0%. The one parameter, 'limit', is never mentioned in the description, though 'recent' and the schema bounds (1-50, default 12) make its meaning inferable.

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?

It clearly lists recent carousels for the account's catalog and says what each entry contains: render status, hook, caption, zip link and per-slide image links. It does not set itself apart from list_creations, a sibling that could overlap.

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?

Mentioning render status and download links implies its use after generate_carousel to check progress and get assets. It never says so outright, and it gives no when-not-to-use guidance or comparison with list_creations.

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=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is fully covered. The description's only additions are the 'Free' cost signal and the promise of returned fields; it says nothing about pagination, result caps, or what an empty list means.

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

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

A single front-loaded sentence with the resource first and the cost note last — very little waste. It is arguably too terse rather than verbose, but every clause (returns, fields, cost) carries information.

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

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

With no parameters, no output schema, and full annotation coverage, the description needs only to say what comes back, and it does by naming the three key fields. Missing pagination or ordering detail is minor for a zero-argument list tool.

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

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

The tool takes zero parameters and the schema is fully closed (additionalProperties: false), so there is nothing for the description to explain. Baseline 4 applies; nothing in the text misrepresents the argument surface.

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 identifies the resource precisely (the brand's saved characters) and enumerates the returned fields (character_id, look, portrait), which is specific enough to separate it from write-side siblings like create_character and save_character. It stops short of an explicit verb ('list all...') and never names a sibling, so it is clear but not sharply differentiated.

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?

There is no statement of when to call this rather than create_character, save_character, or list_creations. The only usage-adjacent signal is the trailing 'Free.', which hints at a cost consideration but does not frame any selection criteria.

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 meaningful behavior beyond the readOnly/destructive annotations: results are newest first, include render status, and expose download and stream links that expire after 24 hours. It does not cover pagination or rate limiting, but with annotations carrying the safety profile this is solid additional context.

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

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

The description is a single well-formed sentence with zero waste, and the core resource plus important return attributes are front-loaded.

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

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

For a simple two-parameter list tool with annotations and no output schema, the description gives a good sense of what is returned. However, because parameter descriptions are absent from the schema and the description does not explain `limit` or `status`, the definition is not fully complete for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented parameters. It mentions render status conceptually but does not explain the `status` filter values or what `limit` controls, leaving both parameters largely unclarified.

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

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

The description clearly states a specific verb and resource: listing recent clips from the account's catalog. It adds useful scope and return details (newest first, render status, download/stream links), but does not explicitly differentiate itself from siblings such as generate_clips or list_creations.

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 by 'Recent clips of the account's catalog,' which tells an agent this is for listing clips. However, there is no explicit when-to-use guidance, exclusions, or direction to alternatives like generate_clips or list_creations.

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=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful non-annotation behavior: a failed job refunds its credits, and the call is free. It does not describe pagination behavior (limit caps at 50) or the shape of the returned result links.

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 plus a parenthetical, front-loaded with the purpose and status life cycle. The long job-type parenthesis is dense but each item disambiguates scope, so little is wasted; only the trailing "Free." feels 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 should explain return shape but only says "status and result links", leaving the agent unsure what fields come back. Missing limit semantics and any polling recommendation leaves gaps for a 3-param listing tool, though annotations cover safety adequately.

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 only 33%, so the description must compensate. It does explain job_id (single-job lookup) and enumerates the job kinds that map onto the `tool` enum, but it never mentions the `limit` parameter or its 1-50 range/default of 10, leaving one of three parameters undocumented in both places.

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

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

The description opens with a specific verb+resource (status and result links of Create jobs) and enumerates the job types covered (images, videos, angles, talking photos, brand films, etc.). It is clearly a read/listing tool for generation jobs, distinguishable from creation siblings, though the parenthetical type list blurs the line against list_clips/list_characters rather than explicitly ruling them out.

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?

"Pass job_id for one job" gives one concrete usage cue, and the status enumeration hints at polling use. However, it never states when to use this versus list_clips, list_characters, list_photo_sets or list_carousels, nor when to poll versus wait, so routing relies on 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?

The annotations already establish that this is a read-only, non-destructive, closed-world tool. The description adds useful behavioral context beyond that: the required Earn profile and the specific data fields returned, including personal links for joined offers. It does not disclose pagination or ordering behavior, 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?

The description is a single front-loaded sentence that immediately states the audience and resource, then lists the key returned fields and the prerequisite. Every clause adds useful information with no waste.

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

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

With no parameters, no output schema, and strong annotations, the description covers the essential context: who it is for, what it returns, and the Earn profile prerequisite. It could be slightly more complete by mentioning pagination or ordering, but it is adequate for this low-complexity list tool.

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

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

The tool takes zero parameters, so the baseline is 4. There are no parameter semantics for the description to clarify.

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

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

The description clearly identifies the resource as live brand offers in the CartViral Earn marketplace and lists the fields returned. It implies a listing operation for creators but does not explicitly contrast itself with sibling actions like join_offer, so it falls short of full sibling differentiation.

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

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

It gives clear context that the tool is for creators and states a prerequisite: an Earn profile created at a specific URL. It does not name alternatives or when-not-to-use conditions, but the usage context is sufficiently 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely non-obvious behavior: results are ordered newest first, render status is included, and download links only appear once a set is 'done' — this state-dependency is the key behavioral fact an agent needs. It stops short of explaining pagination or what an incomplete render returns.

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 that leads with the resource and then layers on payload detail with no filler. The trailing parenthetical with both resolutions is dense but carries real information an agent would otherwise lack.

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

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

With no output schema, the description carries the full burden of describing returns and does so well — ordering, status field, and both link types. Since there are no required parameters the tool is callable as-is, but the omission of limit/pagination behavior leaves a real gap for an agent trying to enumerate the full catalog.

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 0% for the single 'limit' parameter (integer, default 12, max 50), so the schema supplies no meaning and the description must compensate. It never mentions the limit, the default of 12, the 50 cap, or whether the tool paginates; the word 'Recent' is the only weak hint that the result set is bounded.

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

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

The description names a specific verb and resource (list recent AI photo sets of the account's catalog) and specifies the returned payload in detail: render status, zip link, per-image view/download links with both resolutions. It does not explicitly distinguish itself from the many sibling list_* tools (list_creations, list_static_ads, list_carousels), so an agent must infer the boundary from the resource noun, but the resource itself is unambiguous.

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

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

No explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The only guidance is implicit — the mention of 'render status and, when done, ... download links' hints at a poll-then-fetch workflow, but nothing states whether this should be called instead of list_creations or after generate_photos.

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 read-only, non-destructive, closed-world behavior. The description adds the returned fields (page link, render progress, open/click counts), which is valuable because there is no output schema. It omits ordering/pagination, but with annotations covering safety this is strong.

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?

Single sentence, front-loaded with the resource and then the returned stats; 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 zero-parameter read-only list tool with no output schema, the description gives the key return fields. It could mention whether all pitches are returned or how they are ordered, but it is largely complete.

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

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

Zero parameters, so the baseline is 4. The description adds no parameter information, but there are no parameters to document.

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

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

Names the resource (pitches) and ties it to bring_a_brand, then enumerates the stats returned. It does not use an explicit verb like 'list' or state scope (all vs recent), so it falls short of a 5.

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

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

No when-to-use or when-not guidance is given. The only hint is that these are pitches made with bring_a_brand, which implies checking results after creation, but no alternatives or prerequisites are named.

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=true, destructiveHint=false and a closed world, so the safety profile is covered. The description goes beyond them by disclosing the returned fields and explaining the 0-100 CartViral score and what 'push' products mean, which is real added context. Pagination behavior and total counts are still unmentioned, keeping it short of a 5.

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

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

Two compact sentences that front-load the resource and return fields, then close with the actionable next step. No filler or repetition of the tool name.

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 takes on the burden of explaining what comes back, and it does so field by field including the score semantics. The only shortfall is the absence of any paging or result-count framing for a list endpoint with a limit parameter.

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 only 50% — the 'search' parameter is documented but 'limit' carries no prose in the schema, and the description says nothing about either. No filtering, paging, or cap (max 100) guidance appears in the text, so it does not compensate for the coverage gap.

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 the specific resource (the account's catalog products) and enumerates exactly what each entry carries: id, price, photo count, and CartViral score. An agent can distinguish this from import_products or generate_clips 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?

The description implies the browse-then-generate workflow by saying 'Use the id with generate_clips,' which is a useful downstream pointer. However it never says when to prefer this over import_products (adding products) or what to do when the catalog is empty, so alternative selection is only half addressed.

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 readOnly/no-destructive/no-open-world, so the description's added value is in disclosing ordering ('newest first') and, critically, what the response contains in each state (render status, written copy, zip link only when complete). It omits any note on how many records come back by default or whether results are paginated.

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 sentence, front-loaded with the resource and ordering, then the returned fields. Every clause carries information 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?

With no output schema, the description carries the return-value burden and does it well by naming each field and its conditional presence. The remaining gap is caller control over result size and pagination, which matters for a listing tool.

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

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

The single parameter 'limit' has 0% schema description coverage and is never mentioned in the description. 'Recent' and 'newest first' gesture at a bounded result set but give no indication that callers control the count, its default of 12, or its maximum of 50.

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

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

The description names a specific resource — recent static ad sets of the account's catalog — and enumerates the payload (render status, ad copy, zip and image links), so an agent knows exactly what it returns. It does not differentiate itself from nearest siblings like list_creations or list_photo_sets, which keeps it from a 5.

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?

There is no statement of when to call this versus alternatives, nor any prerequisite or exclusion. The 'when done' clause hints that render status is polled, but that is incidental phrasing rather than guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the description's job is to add context it does and does well: credit cost scales with count (4/6/8 credits) and the call is asynchronous, requiring polling via list_creations. It does not say what a failed/partial generation looks like or whether credits are refunded.

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

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

Two dense sentences: the capability and its angle vocabulary first, then the pricing mapping, then the polling instruction. Every clause is actionable and nothing is padded.

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

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

For a 3-parameter, no-output-schema, credit-consuming generation tool it covers input pointer, cost, and the required polling step. It omits how to locate the resulting set in list_creations output and what leads to a partial or failed run, which matters for an asynchronous paid operation.

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 67% and count has only an enum with no description; the description supplies the missing meaning by mapping each count to its credit price, which the schema does not convey. The angle vocabulary (three-quarter, side, top, macro, low, front, wide, detail) also enriches the count parameter since those angles are what the returned set contains.

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: producing new camera angles (three-quarter, side, top, macro, etc.) of the same shoot from a single photo. This clearly separates it from generic siblings like create_image or generate_photos, 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?

"Poll list_creations" gives the required follow-up step after invocation, which is genuinely useful workflow guidance. However, there is no statement of when to prefer this over remake_from_reference, create_image, or generate_photos, and no prerequisites are given beyond the image link hint in the schema.

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 non-read-only, non-idempotent nature. The description adds credit costs (12 for 15 s, 18 for 30 s), notes that premium models cost more, and signals async behavior by saying to poll list_creations. It does not mention failure modes or generation time.

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 dense and front-loaded, and nearly every clause carries information (purpose, inputs, cost, polling). The opening sentence is slightly awkward and redundant ('banner... ads and banners').

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

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

For an async, credit-consuming generation tool with no output schema, it covers cost, input alternatives and how to retrieve results. It omits what the immediate response contains, such as a creation id.

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 60%. The description explains the product_id-or-images input choice and ties seconds to cost, and it hints that model options come from get_create_options. Mood and language are left undocumented beyond their enums.

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?

It states clearly that the tool produces a 15 or 30 s image film of a product with a pro model, with frames usable as banners. It does not say how this differs from siblings like create_video or generate_clips, though the brand-film/banner framing hints at the distinction.

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

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

Use cases are given (site, ads, banners), and it points to get_create_options for premium models and list_creations for polling. There is no when-not-to-use guidance and no contrast with create_video or generate_clips.

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 mark this as a non-readonly, open-world, non-idempotent write; the description goes well beyond them by disclosing pricing (2 credits per up-to-10s take, ~26 words), a 700-character input ceiling, an avatar tier that costs more and may be unavailable, and the asynchronous poll-list_creations pattern. It also flags the consent gate, which is the key safety behavior for this operation.

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

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

Three dense sentences, front-loaded with the capability, then cost, then the consent prerequisite and the follow-up action. No filler and nothing repeated from the schema verbatim.

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 6-parameter async generation tool with no output schema, it covers the essentials an agent needs — input limit, cost, consent, polling. It leaves open what the creation call immediately returns (an id/job handle) before polling, a minor gap given list_creations is named.

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 83%, so the baseline is already satisfied, and the description still adds real value: the 700-character cap on text and the 'any language' behavior are not in the schema, and the avatar model's higher cost/availity nuance sharpens the model enum. The voice parameter (only for the avatar model) is left unmentioned, which keeps this from a 5.

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

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

The description opens with a concrete verb-plus-resource statement — a person's photo speaking the supplied text on camera — that is unmistakable and functionally distinct from siblings like create_video, copy_motion, or create_character. An agent can tell instantly which capability this tool provides.

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

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

It gives clear operating context: consent=true is required for a real person, the avatar model costs more and is availability-dependent, and the agent should poll list_creations after submitting. It never explicitly routes the agent away from an alternative tool (e.g., create_video for non-talking footage), so it stops short of a 5.

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

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

Annotations already declare the mutating, open-world, non-idempotent, non-destructive profile, so the description doesn't need to repeat safety. It adds genuinely new behavior: a 2-minute input cap, a 1-credit charge, and the asynchronous pattern (poll list_creations), plus the schema notes the remote file is "downloaded once." Failure/error handling and whether a new creation is produced are not stated.

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, front-loaded with the core action and options, then the cost and the polling instruction. 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 3-param async mutation with no output schema, the description covers input limits, cost, which result list to poll, and the fit/aspect semantics. It lacks any note on what happens on failure or whether the original video is preserved, which are the remaining ambiguities for an agent planning a call.

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 67% and the one undocumented parameter is `fit`; the description covers exactly that gap by explaining the two modes as "filling the frame or on a blurred background." The `video` and `aspect` params are already well documented in the schema, so the description adds value where it was missing rather than duplicating.

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 ("Re-cut a video ... to another frame") plus the exact supported frame ratios and the two background treatments. This makes it unmistakable against siblings like create_video or generate_clips, which produce new footage rather than re-framing existing footage.

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 operating context: max 2 minutes of source video, cost of 1 credit, and the follow-up step "Poll list_creations" to retrieve the result. It does not name an alternative tool or state when-not to use it (e.g. for videos over 2 minutes or for generating rather than reframing), so it stops short of full routing guidance.

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

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

Annotations only flag it as a non-read-only, open-world, non-idempotent, non-destructive operation; the description goes well past that by disclosing a 10-15 minute generation time, price and refund-on-failure semantics, and the fact that an unreadable social URL is refused before anything is charged. Those are the failure and cost behaviors an agent needs before spending money, none of which appear in annotations.

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

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

It is a single dense block with the core purpose front-loaded and no filler or marketing padding — every clause carries operational information (structure preservation, product branch, URL constraint, price, duration, polling). It loses a point only for being a long run-on paragraph whose within-sentence ordering could be tightened.

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 six-parameter, cost-incurring, asynchronous generation tool with no output schema, the description covers everything an agent needs: input validation rules, cost and refund behavior, expected latency, and how to retrieve results via list_clips. Nothing material about calling it correctly is left unstated.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the description genuinely adds decision-level meaning: it explains that topic is only meaningful without product_id, what happens if topic is omitted, and that reference_url must be a direct file or /u/... link rather than a social post page. It leaves captions, character_id and note entirely to the schema, which is acceptable given their self-explanatory descriptions.

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

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

The first sentence names a specific verb and resource (turn a proven video into a new clip) and describes the mechanism precisely: the engine watches the reference, extracts hook/story beats/timings, and writes new lines on that structure without reusing the reference's people or brand. That mechanism is what distinguishes it from siblings like generate_clips, create_video or copy_motion, so an agent can pick it without opening the schema.

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

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

It spells out both branches of use: with product_id the clip stars a catalog product, without it the clip sells nothing and topic either supplies a subject or falls back to the reference's own topic. It also names prerequisites (product id from list_products), an explicit exclusion (TikTok/Instagram/YouTube post pages are refused), the pricing analogue (generate_clips), and the follow-up action (poll list_clips for download links).

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

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

Annotations already flag this as a non-read-only, open-world, non-idempotent operation, so the safety bar is partly covered. The description adds real value beyond that: a concrete cost (1 credit), the async polling requirement via list_creations, and the exact output artifacts produced. What's missing is what happens on repeat calls (non-idempotent per annotations but unmentioned) or whether credits are spent on failure.

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 fragments, each carrying distinct information (outputs, cost, follow-up step), with zero filler. It is slightly mis-front-loaded: leading with the return artifacts rather than the operation makes the first read less immediately actionable.

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

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

With no output schema and a fully documented single parameter, the description correctly covers returns, cost, and the polling step — the pieces structured fields don't supply. The one gap is that it never states the operation itself, so an agent skimming the description alone would not know a photo is being modified.

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 'image' parameter is documented in detail (CartViral /u/ link or public HTTPS URL, downloaded once). The description contributes nothing about the parameter, so the schema does the work — baseline 3 applies.

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

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

The description never states the action — it opens with the deliverables ('A cut-out PNG with a transparent background plus a white-background JPG'), leaving the verb to the title. An agent can infer background removal from the artifacts, but there is no explicit statement of what the tool does or how it differs from siblings like generate_photos or remake_from_reference.

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?

'Poll list_creations' gives the one piece of workflow guidance that matters — this is an async job whose result must be fetched elsewhere — which is genuinely useful routing. However, there is no when-to-use/when-not guidance and no mention of which sibling tools handle adjacent tasks (e.g., reframing or re-rendering an existing photo).

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

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

Annotations already declare this is a non-readOnly, open-world, non-idempotent mutation, so the safety profile is covered. The description adds two genuinely useful behavioral facts not in the annotations: the call is free and it returns a character_id (important since there is no output schema). It does not disclose what happens to any previously saved character or why the call is non-idempotent.

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 clauses, front-loaded with the action and the source, then the return value and cost. Nothing is wasted and nothing important is buried.

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 non-idempotent mutation with no output schema, the description answers source, return value and cost, but leaves a real gap: whether re-saving replaces the current brand character or creates an additional one, and how the optional metadata fields are used. Those are the questions an agent calling this tool will actually have.

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 only 40%, and the description only enriches portrait_url, clarifying it can be a create_character output or any public https link. The other four parameters (name, age, gender, description) get no mention in the description and their influence on the saved character is undocumented.

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: persists a portrait as the brand's character, and explicitly ties it to the create_character sibling's output. It also pre-answers the two things an agent will wonder about (return value, cost) in the same breath.

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 parenthetical '(or any portrait link)' clarifies the accepted input paths and implicitly positions this as the step after create_character. It stops short of an explicit when-not-to-use, e.g. whether to call this at all versus generating a fresh portrait or using an existing saved character.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, open-world behavior, so the bar is lower; the description still adds real constraints not in the schema — per-format size limits (8 MB images, 60 MB video) and the fact that it is free. It doesn't say what happens on an oversized or invalid file, or that the resulting /u/ link is durable, which keeps it short of a 5.

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

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

Three short sentences, front-loaded with the capability and limits, then the 'you rarely need this' routing signal, then cost. Every clause carries information; even 'Free.' earns its place as a cost signal for a billable-looking upload.

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-optional-parameter, non-destructive upload with no output schema, the description covers formats, limits, inputs, the returned /u/ link, and when to skip it. The main omission is failure behavior — what an agent should do if the file exceeds the size cap or the URL isn't public — which matters given both parameters are optional and mutually substitutable.

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 baseline is 3. The description restates both modes ('public https file link or the file as base64') and reinforces that the link must be public https, but adds no format examples, data-URL syntax, or precedence rule when both are supplied 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 ('Store an image ... or a video ... in CartViral') plus the concrete outcome ('get its /u/ link for the Create tools'). It also implicitly distinguishes itself from the Create tools by noting those accept a public link directly, so an agent can tell which path to take 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?

Explicitly says when NOT to use it ('You rarely need this: every Create tool also takes a public link directly') and names the alternative path. The two input modes (public https link vs. base64) are laid out as the two conditions under which the tool is appropriate.

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