ai-content-drop

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

Annotations already declare the mutation/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), but the description adds non-obvious behavior: no credit cost and the fact that the frame encloses nothing existing. The OAuth/API-key sign-in requirement with a concrete header format is genuinely useful preconditions context that structured fields do not carry.

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

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

Purpose is front-loaded in the first sentence, followed by behavioral notes then auth requirements, ordered by relevance. The auth block is verbose with a full URL, but it earns its place as a blocking prerequisite; nothing is 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?

With annotations, a fully covered input schema, and an output schema present, the description closes the remaining gaps: cost, placement semantics, and authentication. An agent has everything needed to decide and invoke without further reading.

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

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

Schema description coverage is 100%, so all six parameters are already documented including defaults and the revision semantics. The description adds only marginal meaning beyond that ('placed in free space' echoes the position parameter's 'first free grid cell' description), so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Add a labelled frame') and disambiguates the concept with concrete examples ('a region such as Week 1 or Hooks'). It also clarifies the frame 'encloses no existing card', which separates it from grouping/arrangement siblings like group_cards without needing to open their schemas.

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

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

Usage context is only implied: 'placed in free space like a new card' suggests when auto-placement applies, but there is no explicit when-to-use-this-vs-group_cards or when-to-pass-position guidance. An agent can infer the scenario, but alternatives are never 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 only declare the safety profile (not read-only, not destructive, not idempotent). The description adds real behavioral context beyond that: OAuth/API-key auth requirement with a concrete header format, the fact that duration and resolution must match what the quote is taken with, and how from_card_id links cards and seeds the start frame.

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 core behavior is front-loaded in the first two sentences and every sentence carries information. The trailing auth block is somewhat bulky and could be tightened, but it is not filler.

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

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

With 13 parameters but an output schema present and full schema coverage, the description supplies the missing pieces an agent needs: auth method, cost/render timing, duration-resolution coupling, and the parent-card linkage. Nothing essential for a correct call is absent.

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

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

Schema coverage is 100%, so the schema carries the per-parameter baseline. The description still adds meaning the schema lacks: how model ids are obtained, why duration/resolution are coupled to the quote, and the connection/start-frame semantics of from_card_id.

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 ('Add a draft generation card to a board') and immediately clarifies it is a prompt+model pair that is not rendered until run_generation_card. This separates it cleanly from run_generation_card (rendering) and add_media_card (importing media).

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 adding costs nothing and nothing renders until run with a quote, names run_generation_card as the follow-up and list_models as the source of model ids, and gives the concrete branch condition for from_card_id (building on an earlier card). It covers when to use, what happens next, and the alternative path.

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: discloses zero credit cost, that the response is the whole board plus the new card, and the full auth path (OAuth via host prompt or an acd_live_ Bearer key). One meaningful gap remains for a mutation tool: idempotentHint=false is not surfaced, so nothing warns that a retry will create a duplicate card rather than being a no-op.

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, cost, and return shape are front-loaded in two short sentences, then the auth block. The auth paragraph is long and largely boilerplate, but it is genuinely necessary setup information rather than filler.

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

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

With an output schema present and 90% schema coverage, the description covers the two things structured data can't: authentication and credit cost. For a 10-parameter, nested-object mutation tool, the only missing piece an agent would want is what happens on a stale or missing 'revision'.

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 90%, so the schema already documents url, title, caption, position, revision, and source. The description only adds the constraint that the URL must be public https and where it typically comes from; it adds nothing about the 'kind' enum, the optional 'source' provenance object, or revision conflict behavior.

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 ('Add an image or video card to a board') plus the accepted input form (public https URL), which cleanly separates it from add_text_card, add_generation_card, and add_frame. It even names the upstream producers of that URL (import_asset result, generation's video_url, ad's video_url), so an agent knows exactly which artifact this tool consumes.

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 about the condition for use — a public https URL from one of three named sources — and adds a cost signal ('Costs no credits') that helps an agent pick this over a paid generation route. It never states exclusions, e.g. that non-https or private URLs are rejected or when add_generation_card should be preferred over re-adding a generation's video_url.

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: discloses auto-placement on the grid when position is omitted, that the operation consumes no credits, that the whole board plus the new card are returned, and the full auth requirement (OAuth host prompt or Bearer acd_live_… API key with the settings URL). These are exactly the preconditions an agent needs that readOnlyHint=false/destructiveHint=false do not 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 purpose, then behaviour, then auth, and every sentence is informative. The auth sentence is long (two mechanisms plus a URL) but it is genuinely required information rather than 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 an output schema present the description needn't explain return shape, yet it still summarises it; combined with credit cost, placement defaults, and auth it covers everything needed to invoke an 8-parameter mutation tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including limits (4000 chars, 200-char title) and the revision fallback. The description only restates the position-vs-grid behaviour, adding no new semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('Add a text card') and disambiguates the content type with 'a note, an idea, a script line', which separates it from sibling card-creators (add_media_card, add_generation_card, add_frame). The board-bound scope is explicit, 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?

Usage is implied by the examples of what a text card is and by 'Costs no credits', which helps an agent prefer it over credit-consuming generation tools. However, it never states when-not to use it or names an alternative sibling explicitly (e.g. 'for images use add_media_card').

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, the description adds important behavior: it costs no credits, requires OAuth or an API key, and returns the whole board plus the new card. It does not explain revision conflict behavior or failure modes, which are relevant for a non-idempotent mutation.

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

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

The purpose and result are front-loaded, followed by cost and authentication details. Every sentence provides operational value, including the necessary sign-in instructions, with no wasted 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?

Given an output schema exists, the description is still complete enough for invocation: it identifies required inputs indirectly, explains the card transformation, states credit cost, and covers authentication. No critical calling context is missing.

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

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

Schema description coverage is 100%, so the schema already documents ad_id, canvas_id, and revision fully. The description adds context about the ad-to-card mapping but does not add meaning beyond the schema for individual parameters.

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: placing a saved competitor ad on a board as a media card. It also specifies the field mapping (ad video/image as media, advertiser as title, hook as caption), which clearly distinguishes it from generic card-creation siblings like add_media_card.

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 context is clear: use this when a saved competitor ad should become a board card, and it implicitly requires an existing ad_id and board. However, it does not explicitly name alternatives or exclusion conditions, such as when to use add_media_card instead.

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

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

Annotations declare non-readOnly/non-destructive, and the description adds genuinely new behavioral facts: zero credit cost and the exact OAuth/API-key auth path. It doesn't cover what happens on a stale revision or whether arrangement is reversible, so it stops short of 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 core action leads, cost is stated in three words, and the auth block is isolated and clearly flagged. The auth sentence is long but it is load-bearing setup information rather than filler.

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

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

With an output schema present and 80% parameter coverage, the description needn't explain returns. It covers purpose, cost, and auth, which are the main pre-call unknowns for a 5-parameter mutation tool; only revision/conflict behavior is left to the schema.

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

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

Schema coverage is 80%, so the schema already explains ids, gap, revision and canvas_id. The description only echoes the ids/whole-board distinction ('chosen cards (or the whole board)'), adding no format or default detail beyond the schema — baseline 3.

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

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

Specific verb+resource: 'Lay chosen cards (or the whole board) out as a grid, a row or a column' states both the operation and the three supported layouts. It does not name the adjacent siblings (move_cards, group_cards) that an agent might confuse it with, 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?

'Costs no credits' and 'or the whole board' hint at when this is cheap/appropriate, and the auth block tells the agent how to get access. But there is no explicit when-to-use-versus-move_cards/group_cards guidance and no exclusions.

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

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

Adds substantial context beyond the annotations: no credit cost, three explicit rejection cases (self-connection, frames, duplicate connections), and the key semantic that this link does not create a generation dependency. It also discloses the auth requirement (OAuth or Bearer API key), which the annotations do not cover.

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

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

Front-loads purpose and examples before constraints and auth, and every sentence carries information. The auth block is verbose and repeated boilerplate, but it is materially useful for invocation success.

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 an output schema present and full parameter documentation, the description covers cost, failure modes, auth, and the crucial distinction from generation dependencies. Only minor gaps remain, such as what happens on a revision conflict, which the schema's revision field only hints at.

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 canvas_id, from_card_id, to_card_id, label, and revision are already documented in the schema. The description adds no further parameter-level detail (e.g., ordering semantics of from/to beyond the schema text), so the baseline of 3 applies.

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

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

States a specific verb and resource — connecting two cards on a board with a line — and clarifies it is for flow/visual linkage with concrete examples (script card to render card, idea to variations). It explicitly distinguishes itself from add_generation_card with from_card_id, so an agent can tell the two apart without opening either schema.

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

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

Gives concrete when-to-use examples and points to the alternative (add_generation_card with from_card_id) when the intent is a start-frame dependency rather than a visual link. It does not spell out an explicit 'do not use this when…' clause beyond the refusal list, so it stops just short of the top mark.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds genuinely new facts: the operation costs no credits and the board starts empty. The SIGN-IN REQUIRED block spells out both OAuth and API-key auth with a concrete header format and URL, which is real operational context. It does not address limits such as duplicate names or a per-account board cap.

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 action and cost, followed by the follow-on hint and then auth. The auth sentence is long but every clause is actionable (mechanism, header name, URL), so it earns its space; the only mild redundancy is restating the credential prefix format.

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 an output schema present, the description needn't describe the returned board, and it correctly focuses on cost, auth, and next steps instead. Visibility/sharing semantics of a newly created board are the one gap an agent might still wonder about.

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 optional parameter and the schema already documents it fully, including the 100-character limit and the 'Untitled Canvas' default. The description adds nothing about the name argument, so the baseline of 3 applies when the schema carries the load.

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 plus the key qualifier 'new, empty board and return it', which separates it cleanly from list_canvases, get_canvas, and rename_canvas. An agent can identify the operation without opening the schema.

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

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

Gives clear situational context by naming the follow-on path ('Cards are added to it with the add_* tools'), which tells the agent this is the setup step before add_frame/add_text_card etc. It stops short of explicit when-not guidance or pointing at list_canvases/get_canvas for existing boards.

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: a flat quoted price, credits charged only on success, cached results on repeat calls (consistent with idempotentHint), and full OAuth/API-key auth instructions with a key-creation URL. However, the destructiveHint=true and openWorldHint=true annotations are never addressed — the description doesn't say what, if anything, is mutated or removed, which leaves an agent-facing ambiguity for a tool nominally flagged destructive.

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

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

Front-loads the purpose and output contents, then billing/caching behavior, then the auth block — a sensible priority order. The auth sentence is dense and partially duplicative of what a host OAuth flow would surface, but it earns its place for API-key callers.

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 purpose, required inputs and their provenance, cost model, idempotency/caching, and authentication — all that an agent needs to invoke it correctly. Since an output schema exists, the description needn't detail return shapes, and the brief enumeration of decoded components is a bonus rather than a requirement.

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

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

Schema coverage is 100%, so both parameters are already documented in-schema. The description largely restates the quote_id origin and adds only the 'flat price' characterization, which is marginal added meaning over the structured fields; baseline 3 is appropriate.

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

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

States a specific verb (decode) and resource (a saved competitor ad) plus the concrete artifacts produced: hook, script, scenes, audio, CTA, style, and a generation-ready recreation prompt. This clearly separates it from siblings like get_saved_ad (retrieval), estimate_ad_cost (pricing), and generate_ad (creation).

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

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

Explains the prerequisite flow — a quote_id must come from estimate_ad_cost with kind "decode" — and states that a previously decoded ad returns its stored decode at no charge, which tells the agent when calling is cheap vs. billable. It does not explicitly say when to prefer get_saved_ad or ad_to_canvas_card instead, so it stops short of full 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?

Adds useful context beyond the read-only/idempotent annotations: it discloses the return contents (credit lines, total, quote_id), states no account is needed, and notes that the quote_id is required by generate_ad, generate_ugc_video, generate_avatar and decode_ad. It does not mention quote expiry or precision caveats, but the behavioral picture is solid.

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

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

Three tight sentences, front-loaded with the purpose and kinds, followed by return values and the downstream dependency. Every sentence carries information an agent needs.

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

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

Complete for a read-only estimator: it covers purpose, supported kinds, return shape, quote_id consumers and account requirements, while the output schema and 100% schema coverage carry the field-level detail. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by mapping each kind value to a real use case and by advising "For an ad, quote exactly the fields you will submit," which helps align brief/storyboard inputs. It does not elaborate on the individual brief fields beyond the schema, so it stays just above baseline.

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

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

States a specific verb ("Price") and resource ("studio job") and immediately enumerates the four supported kinds with concrete examples, so an agent can distinguish it from generate_ad and the other generation siblings. The description makes clear this is an estimator, not a generator.

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 positions the tool as a preflight step ("before making it") and names the four downstream siblings that consume the returned quote_id, which is strong routing guidance. It does not explicitly state when not to use it, but the context is clear enough to avoid misuse.

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 the safe, idempotent, closed-world read profile, so the bar is lower; the description adds genuinely non-structured context: the returned quote_id is a hard prerequisite for downstream generation, and no authentication is required. It does not restate the per-second billing nuance beyond a brief mention, and error/refusal behavior is left to 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?

Five short sentences, front-loaded with purpose and the return value before the usage caveats. Each sentence carries distinct information (what it does, what it returns, who needs it, auth, input guidance) with no restatement of the name or 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. For a five-parameter, fully documented pricing tool the description supplies everything an agent needs: when to call it, the downstream dependency on quote_id, and the fact that no account is required.

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

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

Schema description coverage is 100%, so all five parameters including the reference_video_seconds measurement rule are already documented in structured fields. The description only reinforces that duration and resolution should reflect intended use and that some video models bill per second, adding marginal meaning beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

Opens with a specific verb+resource framing ("Price a video or image before making it") and immediately states the return value (exact credit cost plus quote_id). It is clearly distinguishable from list_models and from the generate_* tools it feeds, so an agent knows this is the pre-flight pricing step rather than a generation or catalog call.

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 timing ("before making it") and a concrete precondition (generate_video and generate_image require the quote_id it returns), plus the useful note that no account is needed. It also instructs the caller to pass intended duration and resolution. The one gap is that it never mentions the sibling estimate_ad_cost, leaving ad pricing 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?

Goes well beyond the annotations: discloses that credits are charged only on success and never exceed the quote, that the call is asynchronous returning a job_id, and the OAuth/API-key sign-in requirement. This billing and auth context is exactly what the destructive/open-world annotations leave unexplained.

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

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

Two tight sentences front-load the capability and workflow, followed by a clearly delimited SIGN-IN note. Every element is load-bearing; only the auth URL detail makes it slightly long, 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?

For a 15-parameter async generation tool with an output schema, the description supplies the workflow chain (estimate → generate → get_ad_job), billing guarantees, and auth path. Nothing essential an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description raises it by explaining that quote_id must come from estimate_ad_cost for these exact fields, and by framing brief vs storyboard relationship. Most other parameter meaning still lives in the schema, keeping it below 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?

States a specific verb and a richly-scoped resource: a finished multi-shot video ad with creator, product shots, captions and optional music. It clearly differentiates from siblings by referencing the brief/storyboard inputs and naming the quote/job workflow, so an agent knows this is not generate_video or write_ad_storyboard.

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 prerequisites (quote_id from estimate_ad_cost for exactly these fields) and the follow-up step (poll job_id with get_ad_job), plus the brief-vs-storyboard alternative. It doesn't explicitly state when to prefer generate_video or generate_ugc_video instead, so it stops short of full when/when-not 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?

Adds substantial behavior beyond annotations: synchronous completion ("Finishes within the call"), billing semantics ("credits are charged only when a portrait comes back"), automated defect checking on hands/face/background, and the full auth path with header format. These are exactly the cost, latency and auth facts an agent needs before invoking a credit-consuming generation.

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

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

Front-loads what the tool produces and its consumer before prerequisites and auth. The auth sentence is long and includes a URL and header example, but every clause is actionable; no filler.

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

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

With an output schema present, return values need no explanation, and the description covers the remaining gaps: prerequisite quote, cost timing, synchronous behavior, quality checking and authentication. An agent has everything needed to call this correctly on the first try.

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 prompt, save_as, quote_id and aspect_ratio (with enum) are already fully documented. The description only restates the quote_id provenance that the schema already carries, adding no format or behavioral detail beyond it. Baseline 3 applies.

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

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

States a specific verb and resource ("Generate a creator portrait") plus its downstream consumer (avatar in generate_ad) and the quality check applied. This clearly separates it from generate_image and generate_video in the sibling list.

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 prerequisites: a quote_id from estimate_ad_cost with kind "avatar", and sign-in via OAuth or API key. It doesn't explicitly state when to prefer generate_image instead, but the fixed workflow chain (estimate_ad_cost → generate_avatar → generate_ad) makes usage unambiguous.

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

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

Adds real behavioral context beyond annotations: credits are charged only on success, the call is asynchronous and yields a job id, and OAuth/API-key auth is spelled out with a concrete header format and settings URL. It does not address the destructiveHint=true annotation or whether repeated calls create separate billable jobs, 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?

Front-loads purpose and use cases before the quote/poll workflow, then auth last, which is the right ordering. Dense but every sentence carries operational weight; the parenthetical auth details are slightly bulky but justified for a paid, gated tool.

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 an agent needs: auth setup, required quote, async job id, polling target, and billing timing. Return values are handled by the output schema, so nothing material is missing 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 coverage is 100%, so baseline is 3, but the description adds the constraint that quote_id must come from estimate_credit_cost for this exact model and that model must match the quote. It does not restate image_url's per-model allowlist, which the schema already covers in detail.

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 ("Make an AI image") and enumerates concrete output types (product still, thumbnail, poster, concept art, reference frame). It also distinguishes itself from the async siblings by naming the polling tool get_generation, so an agent knows this starts a job rather than returning an image directly.

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

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

Gives an explicit prerequisite chain: obtain quote_id from estimate_credit_cost first, then poll with get_generation (kind "image"). This is a when-to-use and how-to-sequence statement that routes the agent to the correct sibling tools rather than leaving order 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 flag destructiveHint, idempotentHint and openWorldHint, and the description adds the operationally critical facts they cannot express: credits are charged only on success, the result is an id to poll with get_generation, and OAuth or an 'Authorization: Bearer acd_live_…' header is required. It also spells out the legal/consent condition attached to image_rights_consent, which is exactly the kind of beyond-schema behavior an agent must know before calling.

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 core purpose and the input alternatives come first, followed by prerequisites, return/polling behavior and billing, then auth last — a sensible front-loading. The OAuth/API-key block is somewhat verbose relative to the rest, but it is genuinely actionable rather than 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 destructive, credit-consuming, open-world generation tool with 8 parameters, the description covers the source-of-truth for quote_id, the consent gate, billing semantics, and the follow-up step (poll get_generation). An output schema exists, so the lack of return-field detail is not a 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 already 100%, so the baseline is 3; the description nevertheless adds meaning the schema doesn't convey on its own, such as template being an alternative to image_url, quote_id's provenance (estimate_ad_cost kind "ugc"), and that consent must be given by the person rather than assumed. It stops short of contrasting voice/language/ambience choices, so not 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?

States a specific verb+resource ('Make a UGC-style creator video') and immediately disambiguates the two input modes: catalogue creator via list_ugc_avatars/template, or the person's own photo via image_url, both lip-synced to a script. This distinguishes it from siblings like generate_avatar and generate_video without the agent needing to open any schema.

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

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

Gives the full prerequisite chain: a quote_id from estimate_ad_cost with kind "ugc", and image_rights_consent=true given by the person, plus which sibling supplies the template. It names the alternative inputs but does not explicitly say when to prefer generate_video/generate_avatar over this tool, so it falls just short of a perfect routing statement.

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, destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds valuable behavioral context beyond annotations: credits are charged only on success, sign-in is required via OAuth or API key, and the tool returns an asynchronous job id for polling. This goes well beyond the safety profile in annotations, though it doesn't elaborate on idempotency or rate limits.

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 front-loaded with the core purpose, followed by workflow prerequisites, billing behavior, and authentication requirements. It is structured and every sentence contributes useful information, though it could be slightly more concise by omitting redundant details like the full API key example URL.

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

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

Given that an output schema exists and annotations cover the safety profile, the description is complete enough for an agent to call the tool correctly. It covers the necessary prerequisites (quote_id), async job handling, billing on success, and authentication requirements. Minor gaps like model selection constraints are adequately addressed by the input schema.

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

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

Schema description coverage is 100%, meaning all eight parameters are well-documented in the schema itself. The description mentions quote_id and the polling workflow with get_generation, but does not add syntax or format details beyond what the schema already provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description starts with a specific verb and resource: 'Make an AI video: a product ad, a vertical clip for social, a cinematic shot, or animate a photo into video (image-to-video).' This clearly states what the tool does and covers multiple use cases, distinguishing it from image generation siblings. However, it does not explicitly differentiate from other video generation siblings like generate_ugc_video, 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?

The description provides clear workflow context: 'Requires a quote_id from estimate_credit_cost so the price is agreed first; then returns a job id to poll with get_generation.' This tells the agent exactly when to use this tool (after getting a quote and before polling). It lacks explicit when-not guidance or comparison to alternative sibling tools, which keeps it from 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 readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds valuable behavioral context beyond those annotations, especially the OAuth or API-key authentication requirement, though it does not discuss rate limits 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?

The description is front-loaded with the core purpose and usage context, followed by the authentication requirement. Both sentences earn their place, and the auth details are necessary for successful invocation.

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

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

The definition covers purpose, usage timing, and authentication prerequisites. Because there are no parameters and an output schema exists, return-value details and parameter documentation are not needed in the description.

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 no parameters, so there are no parameter semantics to explain beyond the schema. With zero parameters and full schema coverage, the baseline of 4 is appropriate.

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

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

The description uses a specific verb, 'Check,' and names the exact resources: signed-in account remaining credits and current plan name, plus plan/entitlement information. It is clearly distinct from sibling generation and canvas tools because it is account-status retrieval, not content generation or editing.

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 usage context by saying to use it 'before generating,' and it states the sign-in prerequisite explicitly. It does not name alternatives or when not to use it, which keeps it below 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 only declare readOnly/idempotent/non-destructive; the description goes further by disclosing the asynchronous lifecycle (stage and percent while rendering), the concrete 15-second retry hint, and the exact auth path (OAuth prompt or Bearer acd_live_… key with a settings URL). That is materially more than the structured fields carry.

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

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

Result contents are front-loaded in the first sentence, then the job_id provenance, then the polling hint, then auth — a sensible priority order. The auth block is long and partly generic boilerplate, but it earns its place for a tool that will fail without it.

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?

An output schema exists, so return values need no explanation, yet the description still conveys the intermediate vs. terminal states and the polling cadence an agent needs to drive the loop. Auth, provenance and lifecycle are all covered; nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema already says job_id is 'the job_id returned by generate_ad'. The description repeats that same fact and adds no format, prefix or example guidance, so the baseline 3 applies.

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

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

States a specific verb and resource ('Check an ad job') and immediately enumerates the observable payload: stage, percent, finished video URL, storyboard, duration, size and credits charged. This cleanly positions it as the polling counterpart to generate_ad rather than another generation endpoint.

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?

'Takes the job_id from generate_ad' plus the note that running jobs return retry_after_seconds (15) tells an agent both when to call it and how to loop. It stops short of naming explicit alternatives (e.g. list_generations or get_generation) or saying when not to use it, so it is not a full 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 readOnly, idempotent, non-destructive, and closed-world. The description adds value beyond them by disclosing the return format (markdown) and the scope restriction to published articles. It does not say what happens for a missing, draft, or unpublished slug, which is the main remaining behavioral gap.

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

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

A single front-loaded sentence that names the action, the resource, the output format, and the lookup key with zero filler. Nothing could be removed without losing 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?

An output schema exists, so the description need not explain the response body; stating markdown format is a useful bonus. For a one-parameter read tool with full annotation coverage, the only meaningful omission is error behavior for invalid or unpublished slugs.

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 slug parameter already carries a concrete example, so the schema does the heavy lifting. The description only reinforces that the slug identifies a single published article; baseline 3 is appropriate.

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

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

States a specific verb (fetch), resource (one published article), return format (full text as markdown), and key (slug). It implicitly contrasts with the sibling search_articles by emphasizing "one published article," but never names that alternative, so the differentiation is inferential rather than 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?

Usage is implied: call this when you already have a slug and need the full text. There is no explicit guidance on when not to use it, nor a pointer to search_articles for discovering slugs, which is the obvious complementary tool in the sibling list.

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 readOnly/idempotent annotations by disclosing that generation cards are checked against their jobs on every read, that an on-screen board auto-re-reads every 10 seconds during renders and 5 minutes after changes, that the call costs no credits, and the exact OAuth/API-key auth requirement. That is substantial operational context an agent cannot get from structured fields.

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

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

Front-loaded with the core read behavior and value description, followed by behavioral notes and auth. Dense but mostly earning its place; the auth block is boilerplate-heavy and slightly lengthens the entry.

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?

An output schema exists, so return values needn't be spelled out, yet the description still summarizes the payload. Combined with the auto-refresh and auth notes, 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?

With 100% schema description coverage on the single canvas_id parameter, the schema already carries the meaning ('from list_canvases or create_canvas'). The description adds nothing further about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read one board in full') and enumerates exactly what the read returns: cards with type/position/size/data, edges, and revision. This clearly separates it from list_canvases (which enumerates boards) and from refresh_canvas.

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

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

The description gives a clear context for use: reading a single board in full, with detail on how rendering generation cards are resolved on each read. It doesn't explicitly name alternatives (e.g., list_canvases for summaries, refresh_canvas for forcing a re-read), so the exclusions are left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: zero credit cost plus concrete authentication options (OAuth connect or an API key header, with the exact settings URL). It omits what happens if the board is missing or whether the link is shareable/public, keeping it at a 4.

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, then cost, then prerequisites — a sensible ordering with no filler sentences. The auth sentence is long and the embedded URL makes it wordy, but each element is actionable information rather than 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 one-parameter read tool with a full schema, full description coverage, and an output schema that documents the return value, this is nearly complete: purpose, cost, and auth setup are all present. Minor gaps are error behavior for an invalid canvas_id and whether the link is stable or expires.

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 parameter already documents that canvas_id comes from list_canvases or create_canvas. The description adds nothing about the parameter or its format, so the baseline 3 applies when 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?

States a specific verb and resource — retrieves the link to a board's page — plus the intent (open in a browser or embedded panel), which is far more informative than the title 'Get board link'. What is missing is an explicit contrast with the sibling get_canvas, which returns board data rather than a URL; the agent must infer that 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?

Gives clear situational context ('so the person can open it in a browser or the host's embedded browser panel') and a decision-relevant cost signal ('costs no credits'), which helps when choosing between this and credit-consuming siblings. No explicit exclusions or named alternatives, so it falls 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: OAuth/API-key authentication requirements and the exact reported fields (status, URL, credits charged).

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 front-loads the purpose, then explains the job id, output fields, and auth requirements without excessive detail. The authentication note is somewhat long but earns its place because it is operationally important.

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

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

Given the rich annotations, 100% schema coverage, and an output schema, the description is complete enough for an agent to invoke the tool correctly. It covers purpose, input source, output contents, and sign-in requirements.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description reinforces that id comes from generate_video/generate_image and that kind selects image jobs, but it adds little beyond the schema itself.

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

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

The description states a specific verb and resource: checking whether a video or image generation is finished and retrieving its URL. It also names the sibling generators whose job IDs it consumes, which helps distinguish it from list_generations and the generate_* tools.

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

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

It clearly says to use the job id returned by generate_video or generate_image and to pass kind "image" for image jobs. It does not explicitly contrast with list_generations, but the usage context is otherwise 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 readOnly/idempotent/non-destructive, but the description adds genuinely new operational facts: zero credit cost, no decode execution, and the full auth path (OAuth via host prompt, or Bearer acd_live_… API key header with a creation URL). That is the kind of pre-call context an agent needs and 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 purpose sentence, then the cost/behavior clause, then auth — a logical order with no filler. The auth sentence is long but carries required setup detail, 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?

An output schema exists, so return structure needn't be described. With cost, decode behavior, auth requirements, and id provenance all covered, 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 ad_id parameter is fully documented with provenance ('from list_saved_ads or save_competitor_ad'). The description adds no further meaning about the parameter, 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?

States a specific verb and resource ('Read one saved competitor ad in full') plus the notable payload ('stored decode — the ad's formula and a recreation prompt'). This clearly separates it from list_saved_ads (listing), save_competitor_ad (writing), and decode_ad (running a new decode).

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 frames the cost/behavior contrast — 'Costs no credits; never runs a decode' — which implicitly routes agents to decode_ad when they need a fresh decode, and the schema points to list_saved_ads/save_competitor_ad for the ad_id. It lacks an explicit 'use this instead of X when Y' sentence, keeping it just under 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?

Goes well beyond the annotations by disclosing the return payload ('the board and the new frame'), the credit cost (zero), and a detailed sign-in requirement with both OAuth and API-key paths including where to mint the key. The annotations already cover read-only/destructive/idempotent flags, so the remaining gap is minor: it doesn't say what happens on a revision conflict or whether a repeat call nests a second frame.

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 operative content is front-loaded in the first two short sentences (action, return, cost), with auth requirements clearly separated and labelled. The OAuth/API-key block is verbose but genuinely actionable for an unauthenticated agent, so it earns most of its space.

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?

An output schema exists, so return shape needn't be explained further, and the description covers auth and cost — the two things an agent most often gets wrong here. It is complete enough to invoke correctly; only mutation edge cases (repeat calls, revision mismatch) are unaddressed.

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 each of the four parameters, including the optional revision fallback behavior, is documented in the schema itself. The description adds no parameter-level meaning beyond what the schema already provides, 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 and resource: 'Wrap chosen cards in a labelled frame that encloses them', plus what it returns. This implicitly distinguishes it from add_frame (which creates a frame on its own) and arrange_cards, but the sibling differentiation is left for the agent to infer rather than stated.

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

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

'Wrap chosen cards' implies the precondition that the cards already exist, and 'Costs no credits' hints at when it is cheap to use. However, there is no explicit guidance on when to choose this over add_frame, arrange_cards, or move_cards, and no stated exclusions or prerequisite ordering.

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-read-only, non-destructive, idempotent, open-world), and the description adds material context the agent could not infer: the 10 MB cap, accepted MIME types, the fact that it costs no credits, and the auth requirement with a concrete OAuth/API-key path. That is exactly the value-add the behavioral dimension rewards.

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

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

Front-loaded with purpose and effect, then constraints, then auth — a sensible ordering with no filler. The auth sentence is dense but genuinely actionable rather than 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 single-parameter import tool the description covers cost, size/format limits, auth, and the returned hosted URL (an output schema also exists, so return values need no elaboration). An agent has everything required to call it correctly on the first attempt.

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 one parameter at 100% schema coverage, the schema already documents `url`; the description nonetheless contributes constraints absent from the schema — public accessibility, https, and the allowed formats and size ceiling. Minor gap: it doesn't say whether redirects or signed URLs are acceptable.

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 precise verb and resource ("Copy a public image ... onto AI Content Drop") and states the intended downstream uses (avatar, product/photo reference). That distinguishes it clearly from generate_image and generate_avatar in the sibling list, which create rather than import.

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 the deciding context — you already have a public image URL and want it hosted for reuse — plus hard preconditions (public https URL, JPEG/PNG/WebP, ≤10 MB). It stops short of naming an explicit alternative (e.g. "use this instead of generate_image when you already have the image"), so a 4 rather than 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?

Beyond the annotations (which already flag a non-read-only, open-world, idempotent write), the description discloses credit cost, the low-confidence confirmation path, and concrete auth options (OAuth or Bearer acd_live_ key with a URL). This is behavior an agent cannot infer from the structured fields and is directly needed to call it successfully.

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

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

Front-loads the core action and extracts before the auth block, and every sentence carries information. The OAuth/API-key sentence is dense but necessary; overall it is close to optimally sized with minor verbosity in the auth instructions.

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 an output schema, full parameter documentation, and annotations present, the description covers cost, auth, and the confirmation path. It leaves mode selection (product vs app) to the schema, which is acceptable, so completeness is high but not exhaustive.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by tying the persist flag to the low-confidence confirmation behavior and clarifying what the read produces. It does not elaborate on the product/app mode distinction beyond what the schema says.

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 (read website, save profile) and enumerates exactly what is extracted (name, value props, CTA, tone, product images). This clearly distinguishes it from the sibling list_brand_profiles, which reads rather than creates profiles.

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: no credit cost, low-confidence reads are surfaced for confirmation instead of saved, and sign-in prerequisites are spelled out. It stops short of explicitly naming an alternative tool or a 'when not to use' condition, so it lands just below the top band.

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

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

Annotations already cover readOnly, idempotent, non-destructive, closed-world behavior; the description adds auth context ('No account needed') not present in annotations, which is useful for an agent deciding whether it can call this early. It also previews the shape of each entry (one-line description, default aspect, shot count and duration), though the output schema likely covers much of that.

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 action and resource, then the return contents and the ID-usage note in two short sentences. The format enumeration is illustrative rather than redundant, and 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 zero-parameter read-only catalog tool with an output schema, the description supplies everything an agent needs: what is listed, what each entry contains, and how the IDs are consumed downstream. No missing prerequisites.

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 no parameters, so there is nothing to document; the baseline for a zero-parameter tool applies. The description correctly implies a full-catalog, unfiltered listing, which matches the empty schema.

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

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

States a specific verb and resource ('See the ad formats the studio can produce') and enumerates the catalog contents (UGC, talking head, unboxing, tutorial, TV spot, etc.). This clearly separates it from sibling listing tools such as list_models, list_ugc_avatars and list_brand_profiles, which list different resources.

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

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

The description gives clear context for use ('No account needed') and explains downstream relevance: 'A brief names one of these formats by its id,' implying this is a discovery step before writing a brief or generating an ad. It does not explicitly state when to prefer it over sibling catalogs, but the resource specificity makes the fit obvious.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds the thing annotations cannot: an explicit auth prerequisite with two concrete paths (host OAuth prompt, or a Bearer acd_live_… API key header) and the URL where the key is created — genuinely actionable context that prevents a failed first call. It does not add rate-limit or pagination context, keeping 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?

Two sentences, with purpose and payoff front-loaded and the auth block clearly demarcated by a capitalized label. Every clause carries information — there is no filler or repetition 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?

An output schema exists, so the description is not obliged to describe return values, and the annotations cover the safety profile. What would otherwise cause a call to fail — authentication — is spelled out with both credential paths and a signup URL. Nothing an agent needs in order 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?

The tool takes zero parameters, which is the baseline-4 case; there are no argument semantics to explain. The field list in the description is a preview of results rather than parameters, so it neither helps nor hurts here.

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

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

Specific verb ('List') plus resource ('the account's saved brand profiles'), with the returned fields enumerated (name, site, value props, CTA, tone, product images). It is clearly distinguished from the mutating sibling import_brand_profile, and the closing clause states the business reason the list exists.

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 clause 'so ads for the same brand reuse the same facts' tells the agent this is the read step that precedes ad generation for an existing brand, which is real usage context. It never names import_brand_profile as the alternative for creating a profile, nor states an exclusion, so it stops short of 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: zero credit cost, first-class auth requirements (OAuth prompt or Bearer acd_live_… API key with a URL), and the meaning of an empty result. These are exactly the operational facts an agent needs before calling.

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 and return fields, then cost, id linkage and auth. The auth sentence is long and dense with an embedded URL, but it is the only verbose part and carries real information for a first-call tool.

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?

Output schema exists so return values needn't be re-specified, annotations carry the safety profile, and the description covers cost, auth, empty-state and id usage. Nothing material is missing for a zero-parameter 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 schema cannot mislead and the baseline is 4. The description correctly implies no filtering arguments are needed while still describing what the caller receives.

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 ('List the account's boards (visual canvases)') plus ordering ('newest first') and the exact fields returned. It also distinguishes itself from get_canvas by explaining that the ids it returns are the canvas_id consumed by the other board tools.

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

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

Clearly frames this as the discovery step whose ids feed the other board tools, and explains the empty-list case ('an empty list means the account has no board yet'). It does not explicitly say when to prefer get_canvas over this or address pagination limits, so it stops short of 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?

Annotations already declare read-only, idempotent, closed-world, non-destructive behavior, so the description does not need to repeat safety traits. It adds genuinely useful behavioral context: results are newest first, include status and URLs, and require OAuth or an API key header. It does not describe rate limits or pagination beyond the limit parameter, but it covers the most important operational constraints.

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

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

The description is two sentences and front-loads the core listing behavior and return contents. The second sentence is longer but earns its place by covering the required authentication path in concrete terms. There is essentially no wasted text.

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

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

For a simple read-only list tool with one fully documented optional parameter, an output schema, and strong annotations, the description is nearly complete. It adds ordering, returned fields, and auth requirements beyond structured fields. The main remaining gap is explicit routing guidance versus get_generation or other list siblings.

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

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

Schema description coverage is 100%, and the single optional limit parameter is fully documented in the schema with range and default. The description adds no additional meaning about the limit parameter. Baseline 3 is appropriate when the schema carries all parameter semantics.

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

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

The description states a specific verb and resource: list the account's recent video generations. It adds scope and ordering (newest first) and says results include status and URLs. It does not explicitly distinguish this from get_generation or other list tools, but the list-vs-single distinction is reasonably clear from the name and description.

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 'List the account's recent video generations' and the newest-first ordering. However, the description does not say when to use this instead of get_generation or when-not to use it. The sign-in instructions are useful setup guidance, not tool-selection 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 readOnly/idempotent/non-destructive, so the description needn't re-state safety. It adds genuine context beyond that: no authentication is required, the list is live rather than cached, and the `count` field reflects how many models are currently offered — useful traits an agent can't get from annotations.

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

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

Two front-loaded sentences with no filler; the capability list and cost note come first, then the operational caveats. The trailing `count` clause is slightly orphaned without saying what field it lives in, 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?

An output schema exists, so return structure needn't be explained, and the description covers the two things an agent can't infer: no auth required and live data. With zero required parameters and full schema coverage, this is close to complete; only the absence of an explicit 'use before generate_*' nudge keeps it from a 5.

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

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

Schema coverage is 100% and both parameters are documented in-schema, including the type enum and its video default. The description gestures at credit cost (mapping loosely to max_credits) but adds no filtering syntax or semantics beyond what the schema already says, so baseline 3 applies.

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

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

A specific verb-plus-resource ('see which AI video or image models...') with concrete capabilities enumerated (video ad, animate a photo, product clip, image) and the added dimension of credit cost per generation. It clearly distinguishes itself from generation siblings like generate_video, though it never explicitly contrasts with other list_* siblings such as list_ad_formats.

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

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

Usage is implied rather than stated: an agent can infer this is the discovery/cost-check step before calling a generation tool, and 'No account needed' hints at pre-auth contexts. But there is no explicit 'call this before generate_video to pick a model' or any condition excluding alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds value beyond them: zero credit cost, deterministic newest-first ordering, the fields returned, and the required OAuth or Bearer API-key authentication with a concrete header format.

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

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

Front-loaded with purpose, then return fields, cost, id linkage, and auth — a sensible priority order with no filler sentences. The sign-in block is verbose but operationally necessary, so the density is justified.

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?

Zero parameters, an output schema for return values, and annotations for safety — the description fills the remaining gaps (auth, cost, ordering, id reuse). Nothing an agent needs in order to call 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?

The tool takes no parameters, so the baseline is 4. The description goes slightly further by describing the fields of each item and their ordering, but return shape is already covered by the output schema, so no additional credit is warranted.

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

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

Specific verb + resource ('List the competitor ads saved on the account') plus ordering ('newest first') and the returned field set. It is clearly distinct from search_competitor_ads because it is scoped to ads already saved, though it never names that sibling explicitly to make the contrast airtight.

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

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

Provides forward routing: the returned ids are exactly the ad_id consumed by get_saved_ad, decode_ad and ad_to_canvas_card, so an agent knows this is the lookup step preceding those tools. It also notes 'Costs no credits', a useful decision input. It stops short of saying when to prefer this over search_competitor_ads.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: no account is required, and using a real person's photo requires their consent — an important operational constraint not present in structured fields.

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

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

One compact sentence that front-loads the resource and its returned fields. The em-dash aside about generate_ugc_video fields and the trailing consent remark are both informative, though the middle clause reads a bit tangled.

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 zero parameters, full schema coverage, an output schema, and complete annotations, the description only needs to add auth and usage context — which it does via 'no account needed' and the consent caveat. Nothing essential to invoking it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description does not need to compensate for any schema gap here.

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 — a catalogue of UGC creators with name, style and portrait URL — which is clearly distinct from the generate_* siblings. The clause about 'the fields generate_ugc_video accepts' is slightly ambiguous (does it return a schema or just matching metadata?), but the core purpose 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?

Implies the correct usage context by naming generate_ugc_video, so an agent can infer this is the lookup step preceding UGC generation. It also names an alternative path — using the person's own photo with consent — though it does not state explicit when-not-to-use conditions.

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

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

Annotations already cover the safety profile (readOnly=false, destructive=false, non-idempotent, closed-world), so the description needn't repeat that. It adds genuinely new behavioral facts: the operation costs no credits and requires OAuth or a Bearer API key, including where to obtain the key — details absent from all structured fields.

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

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

Purpose is front-loaded in one sentence, followed by the disambiguating note and the auth requirement. The auth block is long (URL plus header format) but is load-bearing information that prevents a failed call.

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 an output schema present, return values need no explanation, and all three parameters are documented in the schema. The description completes the picture with cost and authentication, leaving only the arrange_cards boundary unresolved.

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

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

Schema description coverage is 100%, including the optional x/y and revision semantics, so the schema carries the parameter burden. The description adds no extra meaning beyond noting the server handles placement of new cards, which is already stated in the position property description.

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 ('Move one or more cards to new positions on a board') and clarifies the scope by contrasting with server-side card placement. It does not name the overlapping sibling arrange_cards, so the boundary is only partially drawn.

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 server places new cards itself; this is for the board view's drag' implies when to use it (manual repositioning rather than creation). However, it never mentions arrange_cards, which is the obvious alternative for bulk repositioning, so the agent must guess which to pick.

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 declare readOnlyHint=true, but the description says each read sets a generation card's status to done and its media_url, which is a state mutation. That directly contradicts the read-only annotation, even though the description otherwise adds useful auth, cost, and refresh-interval 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 core behavior is front-loaded, and the remaining sentences cover materially useful invocation context: render-status side effects, automatic refresh timing, credit cost, and sign-in requirements. There is 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?

An output schema exists, so return values need not be explained. For a single-parameter read tool, the description supplies the important operational context: render-checking behavior, auto-refresh conditions, cost, and authentication requirements.

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

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

Schema coverage is 100%, and the schema already documents canvas_id as the board id from list_canvases or create_canvas. The description adds no parameter-specific detail beyond that schema, so the baseline 3 is appropriate.

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

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

The description uses a specific verb and resource ('Re-read a board') and explicitly relates the result to get_canvas while adding render-status checking behavior. This gives an agent enough to distinguish it from the many board/card siblings 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 gives clear context for use: same answer as get_canvas, no new view opened, auto-refresh behavior while cards render, and no credit cost. However, it stops short of explicitly saying when to choose refresh_canvas versus get_canvas.

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 real value beyond annotations by disclosing auth requirements (OAuth or Bearer API key) and zero credit cost. However, for a mutation flagged destructiveHint=true it says nothing about the revision-based concurrency behavior (what happens on a stale revision) or whether the old name is recoverable, so the mutation semantics remain thin.

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

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

Core action is front-loaded in three words, then cost, then auth. The auth/sign-in block is boilerplate-length but genuinely actionable and does not obscure the purpose.

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

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

Params and return values are well covered by schema and output schema, and auth is addressed. The gap is behavioral: conflict/overwrite semantics around the optional revision parameter — the most likely failure mode for this tool — are left to the schema field text alone.

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% — name length bounds, revision provenance, and canvas_id source are all documented in the schema. The description adds no parameter-level detail, which is the baseline case rather than a 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?

"Rename a board" states a specific verb and resource, clearly distinct from card-level siblings like update_card or the create/get canvas tools. It does not explicitly name a sibling or disambiguate from refresh_canvas/update_card, but the intent 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?

Usage is only implied by the verb — an agent can infer it should call this when a board's title must change. It adds one useful decision factor ("costs no credits"), but gives no when-not guidance (e.g., use update_card for card changes) and no prerequisite ordering.

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 that credits are charged only on success, that the quote is verified against the card, that a from_card_id run is refused with nothing charged until the source image is done, and that retrying with the same quote_id returns the same job. These are exactly the expensive, mutation-adjacent behaviors an agent needs to understand before calling a destructive, open-world tool.

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

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

The description front-loads the core action and then layers prerequisites, failure behavior, billing, idempotency, and sign-in details. It is dense but appropriate for a charge-incurring, open-world operation, with only minor repetition around quote verification.

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

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

The description covers authentication, required quote provenance, source-card dependency, billing timing, retry idempotency, and failure behavior. With a rich input schema, an output schema, and annotations already declaring safety traits, an agent has everything needed to call this tool correctly.

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

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

Schema description coverage is 100%, so card_id, quote_id, revision, and canvas_id are already documented in the input schema. The description reinforces the quote_id requirements and adds context about duration and resolution, but it largely repeats what the schema already provides and adds no meaning for revision.

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

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

The description uses a specific verb and resource: it renders a generation card by turning its prompt and model into a video or image job whose result lands in the card. This distinguishes the tool from direct sibling generators such as generate_image and generate_video, which create output without operating on an existing card.

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

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

The description gives clear prerequisites and conditions: the card must have a model and prompt, the caller needs a quote_id from estimate_credit_cost, and source-card runs require the source image to be finished. It does not explicitly contrast when to use this tool versus generate_image or generate_video, so it stops short of a full routing 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?

Adds substantive behavior beyond the annotations: zero credit cost, idempotent dedupe semantics ('Saving the same ad twice returns the existing saved ad'), and explicit sign-in/auth setup with the OAuth and Bearer-key paths. These are exactly the operational facts an agent needs before invoking a write tool.

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

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

Front-loaded with purpose, then cost, idempotency, and auth — sensible ordering with little waste. The auth block is long, but it is genuinely required setup rather than filler; it could be tightened slightly by moving the URL to a trailing note.

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 purpose, source tool, input contract, cost, idempotency, and authentication, and an output schema already exists so return-value explanation is unnecessary. Nothing an agent needs to call 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% and every nested field is documented, so the schema does the heavy lifting. The description still adds a real constraint — the single `ad` object must be the row exactly as returned, unmodified — which clarifies the copy-back requirement beyond the per-field descriptions.

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

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

States a specific verb and resource ('Keep one ad ... on the account') and names its upstream source, search_competitor_ads, so the agent can distinguish it from get_saved_ad/list_saved_ads and from the search tool itself. It also names the downstream uses (decode, place on a board), which anchors the tool in the workflow.

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?

'Keep one ad from search_competitor_ads' plus 'Pass the row exactly as returned' gives clear conditions for use and the input contract. It stops short of explicitly contrasting with adjacent consumers like decode_ad or ad_to_canvas_card, so the choice between saving-then-decoding versus decoding directly 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 readOnly, idempotent, non-destructive, and closed-world; the description adds genuine context beyond them by scoping the corpus to AI Content Drop's own published content and naming its subject areas, which tells the agent this is an internal knowledge lookup rather than a web search. It does not mention ranking behavior, empty-result handling, or that matching is keyword-based rather than semantic.

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

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

A single sentence with the resource and corpus scope front-loaded and no filler. Every clause is doing work — the brand ownership, publication status, content types, and topic areas all narrow expectations.

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 an output schema present and both parameters fully documented in-schema, the description only needs to define the searchable corpus and topical scope, which it does. The one remaining gap is disambiguation from get_article and search_competitor_ads for agents choosing among retrieval tools.

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

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

Schema coverage is 100%: query is documented with example keyword strings and limit is documented with its range and default. The description adds nothing about parameters beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Search) and a specific resource (published guides and model comparisons), plus the topical domain (AI video generation, prompting, ad creative), so the agent knows exactly what corpus is being queried. It stops short of naming how it differs from the related get_article sibling, so an agent must infer that this returns matching results while get_article fetches one document by id.

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 by the verb 'Search' and the topic list; there is no explicit when-to-use, when-not-to-use, or alternative named. Given siblings like get_article and search_competitor_ads, a routing sentence would have added real value. The topical scope does at least signal the domain where this tool is the right pick.

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: zero credit cost, the demo/sample-data behavior with the demo: true marker and result note, and the full auth path (OAuth host prompt or 'Authorization: Bearer acd_live_…' key with a URL). Those are exactly the behavioral facts an agent needs before calling and that readOnlyHint/idempotentHint 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-loads purpose and returned fields, then cost, demo caveat, and auth in a logical order with no filler sentences. The auth block is dense but every clause (scheme, header format, key URL) is actionable, so it earns its space.

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

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

For a read-only search tool with an output schema, the description covers the remaining gaps: cost, sample-data semantics and marking, and authentication. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and both enums (platform, sort) already document their defaults and meaning, so the schema does the heavy lifting. The description adds only the platform framing ('on Meta or TikTok') and no detail on keyword syntax, sort, or limit beyond what is already structured.

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 ('Search live competitor ads by keyword') and names the platforms (Meta, TikTok) plus the fields each ad returns (advertiser, copy, hook, CTA, media, run time). It is clearly distinguishable from generation/canvas siblings, though it never names its natural counterpart save_competitor_ad.

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

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

Gives clear operating context: keyword search over live ads, no credit cost, and the explicit fallback rule that when live data is unavailable rows are samples marked demo: true. It stops short of naming alternatives or stating when another sibling (e.g. save_competitor_ad) should be chosen instead.

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 the annotations it adds real behavioral context: no credit cost, merge semantics (unnamed fields kept), server-side refusal of run-managed fields, and explicit auth requirements (OAuth or Bearer API key with signup URL). It does not explain what a destructiveHint=true overwrite of an existing data field means in practice, which is the one behavioral gap.

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

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

The core action and field mapping are front-loaded, and every sentence is information-dense with no filler. The per-second-model pricing/quote sentence is tangential to this tool and slightly bloats an otherwise tight definition.

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 7-parameter mutation tool with a full output schema and annotations, this covers field semantics, merge behavior, refused fields, and auth — everything needed to invoke it correctly. Minor gaps: no note on revision-conflict handling or the practical meaning of the destructive overwrite.

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 would be 3, but the description goes further by unpacking the opaque generic 'data' object into per-card-type field sets — meaning the schema cannot convey. Width/height/position/revision semantics remain carried by the schema, which is acceptable.

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

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

The description gives a specific verb ('Change a card') and then enumerates exactly which fields are mutably per card type (text/title on text cards; prompt/model/kind/aspect_ratio/duration/resolution/image_url on generation cards; etc.), plus move/resize. This is far more specific than the sibling add_* / move_cards tools and lets an agent distinguish 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 clearly establishes the context in which to call it (editing card data or geometry) and states exclusions — server-managed fields like status, job_id, media_url are refused here. It does not explicitly name alternatives such as move_cards or arrange_cards for repositioning, so routing between overlapping siblings is left partly 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?

Adds real context beyond the annotations: 'Costs no credits' reinforces the readOnly/non-destructive hints, and the SIGN-IN REQUIRED block discloses the exact OAuth and 'Authorization: Bearer acd_live_…' requirements plus where to create the key, which the annotations do not carry. Missing only edge behavior such as whether repeated calls produce identical storyboards despite idempotentHint.

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

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

Front-loads the core action and output shape in the first sentence, with pipeline and auth details following. The auth block is long but each element (OAuth vs API key, header format, settings URL) is actionable; slight density keeps it from a 5.

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

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

Given a nested-object schema with full descriptions, an output schema, and read-only annotations, the description covers the remaining agent needs: cost, auth, and downstream consumption by estimate_ad_cost and generate_ad. Nothing critical is missing 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 coverage is 100%, so the baseline is 3, and the description earns more: it explains that product_image_url is the same image generate_ad will take and is passed as storyboard context. The brief's fields are left to the schema, which already documents them thoroughly.

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

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

States a concrete verb and resource ('Turn an ad brief into a storyboard') and specifies the output shape (1-5 shots with framing, spoken line, caption, duration). It also positions itself precisely against estimate_ad_cost and generate_ad, so an agent can place it in the pipeline 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?

Explicitly says the returned/edited storyboard is what estimate_ad_cost prices and generate_ad renders, which is a clear ordering rule for the sibling tools. It does not give explicit exclusions (e.g. when to skip the storyboard and call generate_ad directly), so it stops short of the top score.

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