ai-content-drop

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

Annotations already flag it as a non-read-only, non-destructive, non-idempotent mutation. The description adds value beyond them by disclosing that the call costs no credits and detailing the auth requirements (OAuth or Bearer API key). It still doesn't describe what happens on revision conflicts, though the schema covers the revision parameter.

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 followed by the alternative and the cost/auth notes. The auth sentence is long but earns its place as setup-critical information; overall tight with no filler.

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

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

Return values needn't be explained because an output schema exists, and the annotations cover the safety profile. The description adds the two things structured fields don't convey — credit cost and authentication requirements — making it complete for this mutation tool.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema, including defaults, the position fallback, and revision semantics. The description only supplies illustrative label examples and adds nothing new about parameters, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('Add a labelled frame') and even clarifies the resource with concrete examples ('a region such as Week 1 or Hooks'). It explicitly distinguishes itself from group_cards, 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?

Names the alternative explicitly for the key case: use group_cards to wrap existing cards. However, it does not address when to use add_frame relative to the other 'add_*_card' siblings (add_text_card, add_media_card, etc.), leaving that boundary 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 substantial context beyond the annotations: no cost on add, no rendering until run, the duration/resolution values must be carried into the run_generation_card quote, and a full sign-in requirement (OAuth via host prompt or an acd_live_ API key header). The annotations only say it is a non-idempotent, non-destructive write, so the description carries the real behavioral payload.

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, then the lifecycle, then the duration/resolution rule, then auth. Every sentence is load-bearing, though the auth sentence is long and could be tightened without loss.

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. Given 12 parameters (all schema-documented), a nested position object, and one enum, the description supplies exactly the missing pieces: cost behavior, deferred rendering, parameter coupling, and authentication.

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 a genuine cross-parameter constraint not in the schema: duration and resolution only apply to per-second models and must be reused in the quote. That coupling meaningfully informs how the parameters are set.

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 names the two defining ingredients (a prompt and a model id from list_models). It is immediately distinguishable from the add_media_card, add_text_card, and add_frame siblings.

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

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

Explains the lifecycle clearly: adding costs nothing and nothing renders until it is run, with run_generation_card named as the follow-up and the quote prerequisite spelled out. It does not explicitly say when to prefer add_media_card or add_text_card instead, but the draft-generation context is unambiguous.

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

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

Adds real behavior beyond the annotations: the operation costs no credits, it returns the whole board plus the new card, and it details the two auth paths (OAuth host prompt or an 'Authorization: Bearer acd_live_…' header created in settings). Annotations only cover read-only/idempotent/destructive flags, so this auth and cost context is genuinely additive.

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

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

Front-loaded with the core action and input constraint before the cost, return, and auth sentences. The auth/sign-in block is long, but it is operational information an agent needs 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 10-parameter tool with nested objects, an output schema, and 90% schema coverage, the description supplies the missing pieces: cost, return shape, and authentication. Nothing critical is absent, though the revision/position defaults are only covered in 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 already 90%, so the schema carries most parameter detail. The description still adds value by enumerating URL provenance ('import_asset result', 'generation's video_url', 'ad's video_url'), which maps to the enum values of the nested source.kind field (upload/generation/ad/studio) that the schema leaves unexplained.

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 ('Add an image or video card to a board') and immediately bounds the input ('from a public https URL'), which distinguishes it from add_text_card, add_frame, and add_generation_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?

Gives clear context for when this applies by naming where the URL typically comes from (an import_asset result, a finished generation's video_url, an ad's video_url). It does not explicitly say when to prefer add_generation_card or ad_to_canvas_card over this tool, so the routing against those siblings 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?

Goes well beyond the annotations (which only say non-readOnly, non-idempotent, non-destructive) by disclosing that the operation is free of credit cost, that the server auto-places unpositioned cards in the first free grid cell, and that the response contains the whole board plus the new card. The detailed sign-in/OAuth-vs-API-key requirement is exactly the kind of auth context an agent needs before invoking.

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

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

Front-loads the action and behavior, then cost, then returns, then auth conditions — a sensible ordering with no filler. The auth sentence is long and URL-heavy, but it carries necessary setup 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?

Covers the mutation's behavior, cost, placement defaults, and authentication prerequisites, and an output schema exists so return values need not be spelled out. Nothing critical is missing for an 8-parameter mutating tool, though a brief note on revision conflicts would have closed the last gap.

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

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

Schema description coverage is 100%, so every parameter is already documented, including the nested position {x, y}. The description restates the position-omission behavior but adds no new meaning for parameters like revision, color, or width/height, so this lands at the baseline 3.

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

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

States a specific verb (add) and resource (text card) and clarifies the resource with concrete examples ('a note, an idea, a script line'), which cleanly separates it from add_frame, add_media_card, and add_generation_card. An agent can pick this tool without opening any schema.

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

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

Gives clear operating context: it places the card on a grid unless a position is supplied, and explicitly notes it costs no credits, which is decision-relevant when choosing between this and credit-consuming generation tools. It never names a specific alternative or states an explicit when-not-to-use condition, 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?

Goes well beyond annotations by disclosing that the call costs no credits, that it returns the whole board plus the new card, and by spelling out the exact auth mechanics (OAuth host prompt or 'Authorization: Bearer acd_live_…' header with the settings URL). These are behavioral facts an agent cannot derive from the readOnly/idempotent/destructive hints.

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

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

Front-loaded with the action and composition, then cost/return, then auth. Three sentences, each carrying distinct information with no redundancy.

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

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

An output schema exists, so return values need no elaboration, and the description still summarizes them usefully. Auth, cost, and composition semantics are all covered, leaving nothing an agent needs missing.

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

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

Schema description coverage is 100% and each parameter already names where its value comes from (list_saved_ads, list_canvases, revision semantics). The description adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('place a saved competitor ad on a board as a media card') and details exactly what is composed onto the card (video/image, advertiser as title, hook as caption, decoded brief attached). This clearly distinguishes it from generic siblings like add_media_card or add_generation_card, which have no competitor-ad origin.

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 well by 'a saved competitor ad' and the requirement that the ad come from list_saved_ads/save_competitor_ad (per schema). It also notes the 'when it has one' conditional for the brief. However, it never explicitly names an alternative (e.g. add_media_card for non-ad media) or states when not to use it.

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

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

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the description isn't required to restate them. It does add two things annotations cannot convey: the operation is credit-free, and it requires OAuth or an 'Authorization: Bearer acd_live_…' header, which is essential operational context for calling it at all. It stops short of explaining what the revision/concurrency behavior means for repeated calls.

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 sentence is front-loaded and tight, and the layout modes are enumerated in one clause. The sign-in block is longer than the functional text but is necessary auth information not carried anywhere else in the 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?

An output schema exists, so return values need not be described, and annotations carry the mutation safety profile. The description covers scope, cost, and auth. It omits only the concurrency implications of the revision parameter, which is a minor gap for a non-destructive layout tool.

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

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

Schema coverage is 80%, so the schema already documents gap, ids, revision, and canvas_id well. The description only reinforces the ids semantics ('chosen cards or the whole board') and echoes the layout values already present as an enum, adding little beyond 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?

The description gives a specific verb ('Lay out') plus the resource ('chosen cards or the whole board') and enumerates the three output arrangements (grid, row, column), matching the layout enum. It is immediately clear what the tool does, though it never names or contrasts the adjacent siblings (move_cards, group_cards) that an agent might confuse it with.

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?

'Chosen cards (or the whole board)' implies the optional-ids case, and 'Costs no credits' is a genuinely useful decision signal. However there is no explicit when-to-use guidance or any statement of when to prefer this over move_cards or group_cards, so usage must be inferred.

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

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

Annotations already cover the safety profile (readOnly=false, idempotent=false, destructive=false), so the bar is lower, yet the description adds meaningful context: 'Costs no credits' and a full auth requirement (OAuth sign-in or an Authorization Bearer API key). That materially helps the agent handle invocation failures.

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

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

Front-loaded with the purpose, then usage, then cost, then auth. The auth sentence is long but actionable and earns its place. Minor verbosity from the full URL, but no filler.

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

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

For a zero-required-param creation tool with an output schema already documenting return values, the description covers purpose, cost, usage pattern, 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% for the single optional 'name' parameter (including the default), so the schema already does the heavy lifting. The description adds no param detail, which is acceptable but earns only the baseline.

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

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

States a specific verb+resource ('Create a new, empty board and return it') and immediately situates it among siblings by noting that cards are added with the add_* tools. An agent can distinguish it from get_canvas, list_canvases, and rename_canvas without opening any schema.

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

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

Gives concrete usage context ('Use one board per plan or campaign') and points to the add_* tools as the follow-up path. It lacks an explicit when-not or a named alternative, but the guidance is clear and actionable.

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

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

Adds substantial context beyond annotations: credits are charged only on success, a previously decoded ad returns its stored result at no cost (consistent with idempotentHint), and it spells out two concrete authentication paths (OAuth or an Authorization bearer key). This is exactly the billing, idempotency, and auth detail an agent needs to call it safely.

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, then pricing, then auth in a logical order; every sentence carries operational weight. The sign-in block is slightly verbose boilerplate but is genuinely actionable, keeping it from a full 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?

With an output schema present there is no need to describe return values, and the description covers the remaining critical gaps: prerequisites, billing behavior, idempotency, and authentication. Nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by clarifying that quote_id must be a kind 'decode' flat-price quote from estimate_ad_cost, tying the parameter to a specific upstream tool. It does not add syntax detail for ad_id beyond the schema, so it is not a full 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 ('Decode') and resource ('a saved competitor ad') and enumerates the concrete outputs (hook, script, scenes, audio, CTA, style, recreation prompt). An agent can distinguish this from siblings like save_competitor_ad and get_saved_ad 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 gates usage on a quote_id from estimate_ad_cost with kind 'decode', establishing the prerequisite workflow step. It does not name when-not-to-use or a sibling alternative, so it stops short of a 5, but the triggering condition is clear.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: it returns credit lines, a total and a quote_id, states no account is required, and notes the quote_id is required by the four generation tools. It does not discuss quote expiry or whether a quote locks in pricing, which is the only material 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?

Purpose is front-loaded in the first clause, then kinds, then return contract, then the two operational notes. Every sentence carries distinct information with no repetition of the schema, despite covering four modes.

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

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

For an 8-parameter tool with nested brief/storyboard objects and an output schema, the description covers mode selection, downstream consumption, auth needs, and input consistency. Return values are properly left to the output schema, though the brief/storyboard precedence could have been spelled out slightly more explicitly.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: it ties the kind enum values to their artifact types and warns "For an ad, quote exactly the fields you will submit," which is a parameter-consistency rule the schema cannot express. The storyboard/brief interaction is also clarified.

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/quote) and resource (a studio job), then enumerates all four kinds and maps each to the concrete artifact it prices. It even names the sibling generators that consume the quote_id, so an agent can distinguish it from generate_ad, decode_ad, and estimate_credit_cost without opening a schema.

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

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

"Price a studio job before making it" gives clear timing context, and it explicitly names the downstream tools that require the returned quote_id, telling the agent when this call is mandatory. It does not, however, contrast itself with the sibling estimate_credit_cost, so the alternative-tool dimension 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 mark the tool read-only and idempotent, and the description adds meaningful behavioral context: it returns an exact credit cost and a spendable quote_id, requires no account, and notes that some video models bill per second. This clarifies auth needs and cost behavior beyond the structured 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?

Three concise sentences, front-loaded with the purpose, followed by the key output and usage pointers. Every sentence earns its place with no filler or repetition.

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

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

The description covers the tool's purpose, the required output, the no-account condition, and the pricing nuance. Since an output schema exists, return values are sufficiently specified, and the overall combination of description, schema, and annotations is complete for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reminds users to pass duration and resolution, but that information is already present in the schema, so it adds little beyond the baseline.

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

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

The description opens with a specific verb and resource: "Price a video or image before making it." It further distinguishes the tool by stating it returns a quote_id required by generate_video and generate_image, which sets it apart from cost tools like estimate_ad_cost.

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

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

The description clearly says to use this tool before generating and to pass the intended duration and resolution. It does not explicitly mention alternatives or when not to use it, but the precondition and typical workflow are 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?

Goes well beyond the annotations, which only declare non-readonly, open-world, idempotent and non-destructive. The description adds the billing contract (credits charged only on success and never more than the quote), the async job/poll pattern via get_ad_job, and the concrete auth requirement (OAuth connect or an 'Authorization: Bearer acd_live_…' header).

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

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

Three sentences, front-loaded with what is produced, then prerequisites, then cost and auth. Dense but every clause carries obligations an agent needs; the long parenthetical listing of ad components is the only slight slack.

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, nested-object, async generation tool with an output schema, the description covers the prerequisites (quote_id, avatar/product images), the return handle (job_id), billing behavior and auth. Nothing needed 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 already 100%, so the baseline is 3, but the description adds genuinely non-obvious semantics: quote_id must come from estimate_ad_cost and match these exact fields, and the storyboard-vs-brief precedence rule ('when present it is what renders').

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 with full scope: a finished multi-shot video ad with speaking creator, product shots, captions and optional music bed. It also names the two input modes (brief or storyboard) and the image inputs, which separates it from generate_video, generate_ugc_video and 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 clear workflow context: requires a quote_id from estimate_ad_cost for exactly these fields, and returns a job_id to poll with get_ad_job. It also clarifies that storyboard takes precedence when present and that the brief is optional alongside it. It stops short of explicitly contrasting itself with sibling generators like generate_ugc_video, so no exclusions are stated.

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 the annotations: the call finishes synchronously, credits are only charged when a portrait returns (billing semantics), defect checking on hands/face/background, and full auth requirements (OAuth or Bearer API key). Annotations only cover the safety profile (non-readonly, idempotent, non-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 core purpose and the prerequisite quote_id before the billing and auth details. Dense but every clause carries distinct value (defect check, billing trigger, auth options); the auth sentence is long but necessary.

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 generation tool with an output schema and full annotation coverage, the description supplies the missing pieces: prerequisite tool, billing trigger, and auth setup. Nothing an agent needs to invoke it correctly 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 baseline is 3, but the description adds a cross-tool constraint the schema doesn't: quote_id must originate from estimate_ad_cost with kind "avatar". Other params (prompt, save_as, aspect_ratio) are already well documented in the schema.

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

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

States a specific verb (Generate) and resource (creator portrait / avatar) with clear downstream usage ('to use as the avatar in generate_ad'), distinguishing it from siblings like generate_image and generate_ugc_video. An agent can identify its role 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 context: it's the avatar source for generate_ad and requires a quote_id from estimate_ad_cost with kind "avatar", effectively naming the prerequisite step. It stops short of explicitly stating when to prefer this over generate_image, but the workflow routing is strong.

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

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

Beyond the annotations, the description discloses that credits are charged only on successful generation, that the call returns a job id rather than an immediate image, and that OAuth or an API key is required. These are meaningful behavioral details that an agent needs to manage cost expectations and polling flow.

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 organized logically: purpose, workflow prerequisite, return behavior, pricing, then auth. It is dense but every sentence adds needed information, and the primary purpose is front-loaded before the procedural details.

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

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

For a tool with four parameters and an output schema, the description covers the full invocation contract: what to prepare (quote_id), what happens next (job id poll via get_generation), cost timing, auth methods, and input constraints. Nothing essential for calling the tool 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 input schema already documents all parameters with 100% coverage, so the baseline is 3. The description adds practical semantics by explaining that quote_id must come from estimate_credit_cost, that model must match the quoted model, and that only certain models accept image_url, which goes beyond the schema's individual 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?

The description opens with a specific verb and resource, 'Make an AI image,' and lists concrete output types such as product still, thumbnail, poster, concept art, and reference frame. It further distinguishes the tool's output channel by noting the job returns a kind of 'image' to poll with get_generation, separating it from video generation.

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

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

The description clearly states the prerequisite workflow: first obtain a quote_id from estimate_credit_cost, then call this tool, then poll with get_generation. It also explains when authentication is needed and how to provide it, but it does not explicitly name a sibling alternative such as generate_video for when video output is desired.

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

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

Annotations cover the safety profile (non-destructive, idempotent, open-world), and the description adds substantial context beyond them: credits are charged only on success, the call returns an id to poll, an explicit image_rights_consent requirement, and full auth instructions (OAuth or Bearer acd_live_ key with URL). This is genuinely rich behavioral disclosure.

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

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

Front-loaded with the core action and modes, then prerequisites, then cost/polling behavior. The trailing SIGN-IN block is dense but earns its place for an auth-required tool; overall efficient though slightly long.

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 complex, authorized, credit-charged generation tool, the description covers inputs' provenance, consent gating, cost timing, async polling, and authentication. Since an output schema exists, no return-shape detail is needed, and nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool meaning: it names where template comes from (list_ugc_avatars) and where quote_id comes from (estimate_ad_cost with kind "ugc"), clarifying the authoring flow beyond what the schema states.

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

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

States a specific verb+resource ('Make a UGC-style creator video') and clearly delineates the two modes (catalogue creator via template vs. person's own photo via image_url), distinguishing it from generic siblings like generate_video and generate_avatar.

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

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

Gives clear prerequisites and routes the agent to sibling tools: template 'from list_ugc_avatars', quote_id 'from estimate_ad_cost with kind "ugc"', and polling via get_generation. It implies when to use it (UGC creator content) but doesn't explicitly state when to choose generate_video or generate_avatar 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?

The description adds significant behavioral context beyond the annotations: it explains the asynchronous pattern (returns a job id to poll), the credit-charging policy, and the authentication requirement. These are not captured in the annotations (which only note non-read-only, open-world, idempotent, non-destructive). The description enriches the agent's understanding of side effects and required setup.

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 comprehensive and well-structured, front-loading the purpose and key use cases, then prerequisites, then authentication. It is longer than typical but every sentence carries necessary information (billing, polling, auth, reference video constraints). No filler or repetition; the structure aids comprehension.

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

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

Given the tool's complexity—8 parameters, async job handling, authentication, billing, and strict quote-matching requirements—the description covers all critical operational details: the need for a quote_id, how to poll, when credits are charged, auth setup, and reference video constraints. It omits nothing an agent needs to invoke the 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?

While schema coverage is 100%, the description adds crucial cross-parameter semantics: quote_id must match model, duration, and resolution; model must match the quoted model; reference_video_url must have its length match the quoted reference_video_seconds. These constraints are not evident from individual parameter descriptions and are essential for correct invocation. The description therefore adds value beyond the schema.

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

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

The description clearly states the tool's purpose: generating AI videos for specific use cases (product ads, vertical clips, cinematic shots, image-to-video). It uses a specific verb ('Make') and resource ('AI video'), and explicitly distinguishes from image generation and other video variants. The mention of image-to-video and reference video further differentiates it from siblings like generate_image.

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

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

It explicitly requires a quote_id from estimate_credit_cost, describes the async flow with get_generation, and details authentication methods (OAuth or API key). It does not explicitly contrast with sibling tools like generate_ugc_video, but the use cases and prerequisites are clear enough for an agent to decide when to use it. The billing caveat (credits charged only on success) is also valuable context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds the crucial behavior that sign-in is required)Skip, specifying two authentication methods and a link to create credentials. This adds meaningful context beyond annotations, though it doesn't describe the output format beyond 'informational page'.

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, front-loading the primary purpose and then providing essential authentication guidance. Every sentence adds value, with no filler. The critical sign-in requirement is placed prominently after 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?

For a zero-parameter tool with an output schema and readOnly annotations, the description is quite complete. It covers purpose, usage timing, and authentication details. The only minor gap is that it doesn't explicitly state that no parameters are required (though the schema shows this), which is trivial. The output schema presumably details the response structure.

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 has zero parametersaday, so the description need not explain parameter semantics. It correctly focuses on what the tool returns, which is abundant. With 100% schema coverage (empty schema), the description compensates fully for the lack of 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?

The description clearly states the tool checks the signed-in account's remaining credits and current plan name, and retrieves the informational page about plans and entitlement. It uses specific verbs ('Check', 'get') and a clear resource ('signed-in account', 'informational page'), which distinguishes it from siblings like 'list_models' or 'generate_image'.

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

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

Explicitly instructs to use this tool before generating, and details the sign-in requirements (OAuth or API key) and where to create the key. It provides necessary context for when to call it, though it doesn't explicitly mention alternatives; however, the use case is so unique that no alternative is implied.

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

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

Annotations already establish readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description goes further by disclosing the polling cadence, the stop condition, the fields returned at each stage, and the exact auth mechanism (OAuth or Bearer acd_live_ key). This is meaningful operational context well beyond the annotations, though it doesn't describe terminal error/failure states.

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 return contents, followed by polling guidance and then the auth block; each sentence carries distinct, actionable information. The credential sentence is long but is genuinely required context, so waste is minimal.

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-value documentation is not strictly required, yet the description still summarizes the payload. Combined with the polling policy and full auth instructions, an agent has everything needed to call this correctly on a post-generate_ad workflow.

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 job_id parameter is already documented as 'returned by generate_ad'. The description does not add format or constraint detail beyond that, 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 ('Check an ad job') and then enumerates exactly what it surfaces: stage, percent, finished video URL, storyboard sheet, duration, size and credits charged. This clearly distinguishes it from generate_ad and the list/get_generation siblings without needing to open 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?

Explicitly routes the agent: 'Poll every 15 seconds after generate_ad; stop after 15 minutes.' It names the predecessor tool and the exact polling policy, so there is no ambiguity about when and how often to call it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'published' scoping constraint and 'markdown' return format, which is useful but not rich behavioral context. No contradictions with annotations.

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

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

A single, front-loaded sentence states the action, resource, format, and input in about a dozen words. Every element earns its place, with no repetition or 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 simple one-parameter tool with a full output schema, annotations covering safety, and no nested objects, the description provides everything an agent needs: what to pass (slug), what it returns (full text as markdown), and the published-only constraint. No missing critical context.

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%: the slug parameter is already documented with a description and example. The description's 'by slug' adds no new meaning beyond the schema, so it meets the baseline but does not exceed it.

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

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

The description uses a specific verb ('Fetch'), states the resource ('full text of one published article'), specifies the output format ('as markdown'), and identifies the key identifier ('by slug'). This clearly distinguishes it from sibling tools like search_articles or list_generations without needing to open the schema.

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

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

The description implies when to use the tool (when you have a slug and need the full published text) but does not explicitly state when not to use it or mention alternatives such as search_articles for finding articles. Usage context is implied, not explicitly routed.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the description goes further and adds genuinely new behavior: zero credit cost, an explicit auth requirement (OAuth via host prompt or an 'Authorization: Bearer acd_live_…' header), and the non-obvious fact that rendering generation cards are re-checked against their jobs on every read.

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 functional payload is front-loaded in the first two sentences with no filler, and the behavioral notes follow logically. The auth/API-key boilerplate is lengthy and partly host-handled, but it is actionable information for an agent encountering an unauthenticated server.

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 read tool with an output schema already defining the return shape, the description covers purpose, cost, freshness semantics, and authentication. An agent has everything needed to decide to call it and to satisfy auth on first use.

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 canvas_id parameter is already documented in the schema with its source (list_canvases or create_canvas). The description adds no format or constraint detail beyond that, 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 ('Read one board in full') and enumerates exactly what the read returns: cards with type/position/size/data, edges, and revision. This cleanly separates it from list_canvases, which returns a collection rather than a full board.

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

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

The phrase 'Read one board in full' implicitly positions this against list_canvases for the summary case, and the note that card ids come from list_canvases/create_canvas gives context. However, it never explicitly names an alternative tool or states when not to use this one, so the routing guidance is inferred rather than stated.

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/non-open-world, so the bar is lower. The description adds genuinely useful behavior beyond them: 'Costs no credits' (relevant in a credit-metered tool family) and an explicit SIGN-IN REQUIRED block with both OAuth and API-key header paths.

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 cost note before the auth detail, and every sentence carries information. The auth block is verbose but justified for a sign-in-gated server.

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; annotations carry the safety profile; and the auth requirement is fully spelled out. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, and the single param (canvas_id) is already documented as 'The board id, from list_canvases or create_canvas'. The description adds no syntax or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Get the link to a board's page on AI Content Drop'. The 'link/page in a browser' framing implicitly separates it from get_canvas (content) and list_canvases, though no sibling is named explicitly.

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

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

Gives clear usage context — the link is for opening in a browser or the host's embedded browser panel — so the agent knows the scenario. It does not explicitly name alternatives (e.g. get_canvas) or state when-not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds meaningful behavioral context: what the tool reports (status, finished file URL, credits charged) and the requirement for authentication. This goes beyond the structured annotations and helps the agent understand the tool's side effects and prerequisites.

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, then usage instruction, then a necessary authentication note. It is compact and every sentence carries information. The auth detail is slightly verbose but justified given it's a hard requirement. No fluff.

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 tool's simplicity (2 parameters, 1 enum, output schema exists), the description covers purpose, usage, parameter semantics, and auth requirements. There is nothing an agent needs to call it correctly that remains unexplained. An output schema exists, so return values are already documented.

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

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

Schema description coverage is 100% – both `id` and `kind` have descriptive schema entries. The description reinforces the relationship between `id` and the generate calls and mentions the default for `kind`, but it does not add meaning significantly beyond what the schema already provides. Per calibration, the baseline 3 applies when schema covers 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?

The description opens with a specific verb ('Check whether') plus a clear resource ('a video or image is finished and get its URL'). It explicitly names the sibling tools it complements ('after generate_video or generate_image'), so an agent can immediately distinguish it from other generation-related tools without reading 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?

The description explicitly instructs when to use the tool ('Poll this after generate_video or generate_image') and how to parameterize it ('pass kind "image" for an image job'). It also provides authentication prerequisites (OAuth or API key), which is essential usage guidance. It doesn't mention alternatives for listing batches, but given the sibling set, the context is clear enough.

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, idempotent, non-destructive), but the description adds genuinely useful behavior: zero credit cost, the guarantee that no decode is executed, conditional decode presence ('when it has one'), and concrete auth steps including the OAuth flow and Authorization: Bearer acd_live_… header. It does not describe error/empty-decode handling, keeping it out of 5 territory.

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, then cost guarantee, then auth requirements. Every clause earns its place, though the auth sentence is fairly long and could be tightened; still well-structured overall.

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-value explanation is unnecessary, and the description still covers cost, decode behavior, authentication, and the ID source. 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 description coverage is 100% and the single ad_id parameter is already documented with its provenance (from list_saved_ads or save_competitor_ad). The description adds no additional meaning 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 (read) and resource (one saved competitor ad) and clarifies the scope: a single ad in full, including its stored decode when present. This clearly separates it from list_saved_ads (plural listing) and decode_ad (which would generate a decode rather than read a stored one).

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

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

Gives clear context: it costs no credits and never runs a decode, implicitly routing decode-generation needs to decode_ad. The schema also points to list_saved_ads/save_competitor_ad as ID sources. It stops short of an explicit 'use this instead of X when Y' statement, so it is a strong 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?

Annotations cover the safety profile (not read-only, not destructive, not idempotent), so the bar is lower; the description still adds real context beyond them: the return payload (board plus new frame), that it costs no credits, and the concrete auth path (OAuth or an Authorization: Bearer acd_live_… header with a settings URL). It does not explain what happens if the revision is stale, but that is a minor omission.

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, then returns and cost, then auth. Three compact sentences with no filler; the auth sentence is long but earns its place as a hard prerequisite.

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

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

An output schema exists so return values need not be explained, yet the description still names the return payload. Combined with cost and auth details, an agent has what it needs; only the non-idempotent/concurrent-revision behavior is left 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%, including the revision parameter's optional read-then-write behavior, so the schema carries parameter semantics. The description adds only a loose paraphrase ('chosen cards', 'labelled frame') and no format or constraint detail, matching the baseline 3.

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

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

States a specific verb and resource: 'Wrap chosen cards in a labelled frame that encloses them.' An agent can distinguish this from add_frame (which creates a frame without wrapping existing cards) and arrange_cards. It does not explicitly name those siblings, 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?

Usage is implied by 'chosen cards' plus the required ids/label/canvas_id parameters, but there is no explicit statement of when to use this versus add_frame or arrange_cards, and no exclusions or prerequisites beyond the auth note. Adequate but clearly gapped.

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 (readOnlyHint=false, openWorldHint=true, idempotentHint=true), the description discloses authentication requirements in detail (OAuth prompt or 'Authorization: Bearer acd_live_…' API key), the zero-credit cost, the accepted input formats/size limit, and the hosted-URL result. This is exactly the behavioral context annotations cannot carry.

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

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

Three tightly packed sentences: purpose and constraints first, then return value and cost, then auth. No filler, and the auth prerequisite is clearly flagged for the agent before it attempts the 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, the description needn't explain the response, and it still mentions the hosted URL. Combined with explicit auth, cost, and input constraints, an agent has everything needed to invoke this tool successfully.

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 'url' param is already described, so the baseline is 3. The description nevertheless adds validation semantics the schema lacks: only publicly reachable images, restricted to JPEG/PNG/WebP, capped at 10 MB.

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 ('Copy a public image ... onto AI Content Drop') plus accepted formats and size cap, and clarifies what the asset is for (avatar, product or photo reference). This clearly differentiates it from generation siblings like generate_image or generate_avatar.

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

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

It gives clear context for use (importing an existing public image as a reference/avatar) and notes 'Costs no credits,' which implicitly steers an agent away from paid generation when an existing image suffices. It does not, however, explicitly name an alternative or state when-not-to-use.

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, which only declare the non-read-only/idempotent/non-destructive profile: it adds credit cost, the low-confidence confirmation branch instead of silent save, and explicit auth mechanics (OAuth prompt or Bearer acd_live_ key). It does not clarify whether saving overwrites or duplicates an existing profile, which matters for a write tool flagged idempotent.

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

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

Three sentences, front-loaded with what is read and saved, then cost/confidence behavior, then the auth requirement last. No filler, and each sentence carries distinct operational information.

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

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

With an output schema present, return values need not be described, and the description covers cost, auth, and the confirmation escape hatch. The one gap is the write semantics of persist (create vs overwrite on an existing brand profile), which is material for a tool with destructiveHint=false and idempotentHint=true.

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 url, mode, and persist are already documented in the schema, including the enum and both defaults. The description adds no parameter-level detail (e.g., what persist=false does to the confirmation flow), 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 a brand's website and save a brand profile') and enumerates exactly what the profile contains (name, value props, CTA, tone, product images). An agent can distinguish it from the read-only sibling list_brand_profiles 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?

Provides useful operating context (no credit cost, low-confidence reads returned rather than saved, sign-in required), but never states when to prefer this over alternatives such as list_brand_profiles or refresh_canvas, nor what happens when a profile already exists for the brand.

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 auth context beyond the annotations ('No account needed') and previews the return payload, which is useful operational detail the structured fields do not provide.

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

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

A single dense sentence with the core action and return contents front-loaded, and the usage cue last. The format enumeration (UGC, talking head, unboxing...) is somewhat long but demonstrates catalogue breadth, so it largely 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 zero-parameter, read-only listing tool with an output schema and full annotation coverage, the description supplies everything needed: what it lists, what each entry contains, that no account is required, and when to call it.

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

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

The tool takes no parameters (0 params, empty schema), so the baseline is 4. The description correctly implies there is nothing to supply and instead characterizes the payload rather than inventing 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?

States a specific verb and resource ('See the ad formats the studio can produce') and enumerates the actual catalogue contents, so an agent knows exactly what comes back. It is clearly distinguishable from sibling lists (list_models, list_canvases, list_brand_profiles) and is tied to the ad-writing 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?

'Pick one before writing a brief' explicitly places the tool in the workflow and signals the downstream consumer (write_ad_storyboard / generate_ad). It gives clear context but names no alternative tool or exclusion condition, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so those are covered. The description adds genuinely new operational context the annotations lack: authentication is required, via OAuth or a bearer API key header, with the exact header format and the URL to create the key. It stops short of describing pagination or result limits, so not a 5.

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

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

Two sentences, front-loaded with the operation and its purpose, then the auth requirement. No filler, and the critical blocker (sign-in) is called out in caps rather than buried.

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

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

With zero params, an output schema, and strong read-only annotations, the only real risk an agent faces is auth failure — and the description covers that thoroughly. The field list is mildly redundant against the output schema, but nothing needed to invoke the tool 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 the baseline is 4 per the rubric. The description's enumeration of returned fields adds useful shape for an agent even though the output schema already exists.

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 (List) and resource (the account's saved brand profiles), then enumerates the fields returned (name, site, value props, CTA, tone, product images). This clearly separates it from the write-side sibling import_brand_profile and from the generation siblings it feeds.

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

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

The phrase 'so ads for the same brand reuse the same facts' implies why and when to call it, but there is no explicit when-not or named alternative (e.g., how it relates to import_brand_profile or get_account). Usage is inferable but not spelled out.

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

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

Adds meaningful context beyond the annotations: 'Costs no credits' is billing behavior not covered by readOnlyHint, and the SIGN-IN REQUIRED block discloses the OAuth vs API-key auth paths with a concrete header format and where to create the key. Annotations already cover safety, so this extra operational detail is valuable. Minor gap: no pagination behavior for large accounts.

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 the return fields, then the cost note, then the auth requirement. Every clause earns its place and 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 an output schema present, the description need not explain return values further, and it covers cost, auth, and usage routing. For a zero-param read tool this is complete.

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

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

Zero parameters, so the baseline is 4. The description correctly documents the shape of the response items even though there is no input to describe.

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 (List) and resource (boards/visual canvases) and enumerates the returned fields (id, name, revision, card count, page link), so the agent knows exactly what comes back. Sibling tools like list_generations, list_saved_ads, and list_ugc_avatars are clearly differentiated by resource.

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 'Start here to pick a board or to see that none exists yet', naming both when to use it and the selection decision it enables. The zero-arg, zero-cost nature makes it an obvious first call, and no alternative could serve the same purpose.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful operational context: sign-in requirements (OAuth or API key header) and output characteristics (status and URLs, newest first). This is useful supplementary behavior without contradicting 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 sentences, front-loaded with the core behavior and then the essential auth note. No wasted words or duplication of schema details.

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 list operation with one optional parameterweeney, an output schema, and readOnly/idempotent annotations, the description covers auth, ordering, and result content. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the description doesn't need to compensate. The description adds no extra meaning to the 'limit' parameter beyond what the schema already states, so baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'List the account's recent video generations'. It also specifies ordering ('newest first') and what is returned ('status and URLs'), making the tool's purpose unmistakable and distinct from a single-generation getter like get_generation.

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

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

The description clearly states the operation is scoped to the account's recent video generations)Skip and includes auth context, but it does not explicitly contrast with sibling tools like get_generation or say when not to use it. Usage is implied rather than directly guided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: 'The list is live' (dynamic data), 'No account needed' (auth not required), and clarifies that `count` reflects current offerings. This goes beyond the annotations without contradicting them.

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

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

Three sentences, all informative: use cases, auth requirement, and live-data caveat. Front-loaded with the core purpose, no filler or repetition of schema details.

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 list tool with an output schema and full parameter documentation, the description is nearly complete. It covers auth, data freshness, and the meaning of `count`. The only minor gap is not describing pagination or result ordering, but the output schema likely covers return structure.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (type enum, max_credits). The description adds the default behavior for `type` ('Defaults to video') and ties `count` to the live list, but doesn't add much beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('See which...') and resource ('AI video or image models'), and enumerates concrete use cases (video ad, animate a photo, product clip, image). It clearly distinguishes from siblings like generate_image/generate_video by being a listing/read operation, and the 'No account needed' note adds scope.

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

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

The description implies when to use it: when you need to discover available models and their credit costs before generating. It doesn't explicitly name alternatives or exclusions, but the sibling context (generate_image/generate_video) makes the read-vs-write distinction clear. A brief 'use generate_* to actually create' would push it to 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, but the description adds genuinely new operational facts: 'Costs no credits' and a full auth requirement (OAuth host prompt or 'Authorization: Bearer acd_live_…' header with a settings URL). That auth detail is the main thing annotations cannot express, though no pagination behavior is disclosed.

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, ordering, and cost before the call-to-action and auth block. The auth sentence is long (header prefix plus a settings URL) and could be terser, but every clause carries actionable 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?

Zero-parameter read tool with an output schema and full annotation coverage; the description still supplies cost, ordering, returned fields, auth, and next-step routing. 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?

The tool takes zero parameters, so the baseline is 4. The description enumerates the fields that come back, which is helpful framing but is not parameter semantics, and with zero inputs there is nothing further to disambiguate.

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 the exact ordering (newest first) and the returned fields (id, advertiser, hook, media, decode-stored flag). The 'saved on the account' scope implicitly separates it from search_competitor_ads and from get_saved_ad, so an agent can route without opening a schema.

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

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

'Start here to pick an ad to decode or place on a board' gives concrete downstream intent, pointing at decode_ad and the ad_to_canvas_card family. It lacks an explicit contrast against sibling alternatives such as search_competitor_ads (when to search instead of list), so it is clear context without exclusions.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely non-annotation context — 'No account needed' (auth requirements) and the consent caveat for using a person's own photo — which is exactly the kind of behavioral detail the schema cannot express. No pagination or catalogue-size behavior is mentioned, so not a full 5.

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

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

A single front-loaded sentence that states what the agent gets before the secondary consent note. Efficient with no filler, though the trailing photo/consent clause is slightly tangential to 'list the catalogue'.

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 further explanation, and the description still volunteers the key fields. Combined with annotations covering safety and a no-parameter schema, the definition is complete enough for correct invocation; only routing alternatives are thin.

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 per the baseline there is nothing for the description to document. The field mentions (name, style, portrait URL) describe output, not inputs, but do no harm.

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 (see/list) and resource (catalogue of UGC creators) and enumerates the returned fields (name, style, portrait URL). It also ties itself to the consumer tool generate_ugc_video, which helps separate it from list_models and list_generations. 'See' is a slightly soft verb, keeping it just below 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?

Implies usage by naming generate_ugc_video and its accepted fields, so the agent can infer this is the pre-flight lookup for that tool. However, it never states when-not to use it or names alternatives like list_models or generate_avatar explicitly, leaving routing somewhat inferred.

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

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

Goes meaningfully beyond the annotations by disclosing that the operation costs no credits and by spelling out the exact authentication paths (OAuth or Authorization: Bearer acd_live_…). The annotations cover the mutation/safety profile (readOnlyHint=false, destructiveHint=false), and the description adds cost and auth context without contradicting them.

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, then stacks behavioral facts (no credits, sign-in) in a logical order. The auth instructions are verbose but necessary and clearly delineated; little 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 values need not be described, and annotations carry the safety profile. With scope, cost, and auth covered, the definition is nearly complete, though an explicit sibling trade-off (arrange_cards vs move_cards) is the remaining gap.

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

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

Schema description coverage is 100%, so the schema already explains moves, position, revision, and canvas_id, including the omitted-position fallback. The description adds no parameter-level syntax or format detail, 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 ('Move one or more cards to new positions on a board') and clarifies scope by explaining that new card creation is handled by the server, not this tool. It does not name the closest siblings (arrange_cards, update_card) so an agent must still infer the boundary between repositioning and re-arranging.

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 usage context ('this is for the board view's drag') and rules out using it for new cards, but never states when to choose it over arrange_cards or update_card. No explicit when-not conditions are given.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds important context beyond annotations: it costs no credits, requires OAuth or an API key header, should be polled every 10 seconds, and reflects render completion via card status and media_url.

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 and efficient: purpose first, then polling cadence, then authentication requirements. Each sentence provides necessary operational information without 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 simple one-parameter read-only polling tool with an output schema and clear annotations, the description supplies the missing authentication, credit-cost, and polling-cadence context. Nothing essential for correct invocation is absent.

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

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

Schema description coverage is 100%, and the single canvas_id parameter is fully documented in the schema as the board id from list_canvases or create_canvas. The description adds no parameter syntax or constraints beyond that, 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 ('Re-read a board'), identifies it as equivalent to get_canvas, and explains its polling role during generation-card rendering. An agent can distinguish it from list_canvases, create_canvas, and other siblings without opening schemas.

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

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

Explicitly says to call it every 10 seconds while a generation card is rendering and explains the success condition (card status becomes done with media_url). It does not explicitly say when to prefer get_canvas instead or when polling should stop, so it is clear but not fully exclusive.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=false), but the description adds genuinely new behavior: the operation is free, and it requires authentication via OAuth or a specific Authorization header with a concrete key-creation URL. That auth and cost detail is not derivable from the schema or annotations. It does not, however, address the non-idempotent hint or what happens with a stale revision.

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

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

Three compact sentences with the core action front-loaded, followed by cost and auth requirements. The auth sentence is verbose but each clause carries actionable information (two connection paths plus a key 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?

For a low-complexity mutation tool with an output schema and full parameter documentation, the description covers the two things an agent cannot infer elsewhere: cost and authentication setup. Missing only edge-case behavior around the revision parameter and conflict handling.

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 explains canvas_id, name (1-100 chars), and the optional revision field. The description adds no parameter-level detail beyond the schema, making the baseline of 3 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 opens with a specific verb and resource ('Rename a board'), which is unambiguous and distinguishes it from siblings like create_canvas, get_canvas, and list_canvases. It never explicitly contrasts itself with update_card or refresh_canvas, so it earns a 4 rather than a 5.

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

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

There is no guidance on when to choose this tool over siblings such as update_card, refresh_canvas, or create_canvas, and no stated preconditions like needing an existing board. The cost note ('Costs no credits') is incidental context rather than usage guidance.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, openWorldHint=true), and the description adds genuinely new behavioral context: credits are charged only on success, a retry with the same quote_id returns the same job, the quote is verified against the card, and full auth requirements (OAuth via host prompt or API key header with signup URL) are disclosed.

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 clause, and subsequent sentences each carry distinct payloads (prerequisite, billing semantics, idempotency, auth). It is dense and a little long, and the quote_id derivation is restated from the schema, but nothing is wasted 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, and for a paid, authenticated mutation the description covers the missing pieces an agent would otherwise guess at: prerequisite quote flow, cost-on-success behavior, retry idempotency, and exact sign-in options.

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 each parameter is already documented in the schema. The description reinforces the quote_id dependency (quantity 1, card duration/resolution) but adds no syntax or format detail beyond the schema's own text; 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 (render/run) and resource (a generation card), and explains the outcome mechanism: the card's prompt and model become a video or image job whose result lands back in the card. This clearly separates it from siblings like generate_image/generate_video (which create new jobs) and add_generation_card (which only adds a 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?

Gives an explicit prerequisite workflow: a quote_id must first come from estimate_credit_cost for the card's model and kind, quoted with the card's duration and resolution. It does not, however, state when-not to use this tool or name an alternative for cases like creating a brand-new generation.

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

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

Annotations cover safety (destructiveHint=false, idempotentHint=true) but the description adds context annotations cannot: no credit cost, the concrete outcome of a duplicate save ('returns the existing saved ad'), and full authentication requirements (OAuth prompt or Bearer acd_live_ key with a settings URL).

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 source, then the pass-through rule, cost, idempotency, and auth in short clauses. Every sentence carries distinct decision-relevant information; nothing is repeated from the schema or annotations.

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 narration, and the description closes the remaining gaps: cost, idempotency behavior, auth setup, and the input hand-off rule. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, and the nested row fields are documented inline. The description goes beyond that by prescribing how to populate the parameter ('Pass the row exactly as returned'), which prevents the agent from mutating or trimming fields.

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 ('keep one ad ... on the account') and names the exact source sibling (search_competitor_ads) plus the downstream use (decoded and placed on a board). An agent can distinguish it from list_saved_ads and get_saved_ad without opening a schema.

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

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

Explicitly says to pass the row exactly as returned from search_competitor_ads, which tells the agent the precondition for calling it. It does not, however, explicitly rule out alternatives or state what to do if the ad was not sourced from that tool.

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 with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds content scope but no additional behavioral traits such as pagination, rate limits, or result ordering, so it stays at a baseline 3.

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

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

The description is a single front-loaded sentence with no filler. It packs the verb, resource scope, and topic coverage efficiently, making it easy for an agent to parse quickly.

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 search tool with two fully documented parameters, safety annotations, and an output schema, the description is largely sufficient. It is slightly incomplete in that it doesn't hint at the recommended flow of searching then fetching an article via get_article, but nothing essential to invoking the tool correctly is missing.

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

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

Schema description coverage is 100%: query and limit are both documented with examples and constraints. The description adds no parameter-specific meaning beyond what the schema already provides, 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: 'Search AI Content Drop's published guides and model comparisons' about AI video generation, prompting, and ad creative. It clearly differentiates from generation and listing tools, though it does not explicitly distinguish itself from the closely related get_article sibling.

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

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

The description implies usage when discovering published content by keyword, such as 'kling vs sora', but it provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives like get_article for retrieving a specific article by ID.

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, non-destructive, open-world behavior, so the safety bar is covered; the description goes further by disclosing that fallback rows are synthetic and flagged demo: true, instructing the agent never to present them as real ads, and spelling out the auth path (OAuth or Authorization: Bearer acd_live_ key).

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 clause, followed by cost, data-quality caveat, and auth prerequisite in that priority order. Every sentence carries function; the auth URL is long but necessary and appears last.

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 100% schema coverage, the description need not explain return values, and it covers cost, fallback data semantics, and authentication. The only gap is lack of comparative guidance against sibling ad tools.

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

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

Schema description coverage is 100%, so keyword, platform, sort and limit are already fully documented in the schema; the description's mention of "by keyword on Meta or TikTok" only echoes that. No format or edge-case detail (e.g. keyword syntax caveats) is added beyond the schema.

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

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

States a specific verb (search) plus resource (competitor ads) with explicit scope: live ads by keyword on Meta or TikTok. It even enumerates the per-ad fields returned (advertiser, copy, hook, CTA, media, run time), which separates it cleanly from siblings like search_articles and list_saved_ads.

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 the demo-sample caveat imply when this is worth calling, and the sign-in requirement is a clear precondition. However, it names no alternative tool (e.g. save_competitor_ad, list_saved_ads) and gives no explicit when-not-to-use guidance, so routing 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?

Beyond the annotations (readOnly=false, destructive=false), the description discloses that server-managed fields are refused, that a per-second model is priced from duration and resolution, that no credits are consumed, and the exact auth requirement (OAuth or Bearer API key). This is substantial behavioral context that the annotations alone 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?

The purpose is front-loaded and every sentence carries information (card-type fields, refused fields, pricing order, auth). It is dense rather than padded, though the auth block is somewhat long and the whole thing runs as one paragraph.

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 mutation tool with nested objects, the description covers edit scope, merge behavior, server-controlled fields, pricing implications, and authentication. An output schema exists, so return values need no explanation, and nothing required to invoke the tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by listing which fields belong in data for each card type (e.g., prompt/model/aspect_ratio for generation cards, label for frames). The merge semantics are also reinforced here, exceeding what the generic object schema provides.

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

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

The description opens with a specific verb and resource ("Change a card") and then enumerates exactly what is editable per card type (text, generation, media, frame) plus move/resize. This lets an agent distinguish it from the add_* and move_cards siblings without opening any schema.

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

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

It gives clear context for use (merging data, moving, resizing) and useful preconditions such as "Costs no credits" and the quoting-order note. However, it never names the overlapping sibling move_cards or states when to prefer it, so the alternative selection is 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?

Goes well beyond the annotations by disclosing that the operation 'costs no credits' (consistent with readOnlyHint=true) and by spelling out the OAuth/API-key sign-in requirement — something annotations cannot convey. The ordering constraint relative to estimate_ad_cost and generate_ad is also behavioral context 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?

Front-loaded with the purpose and the output shape, then workflow, then auth. Every sentence carries information, though the auth block is verbose and could be tightened. No wasted preamble.

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. The description nonetheless covers the output shape, cost implications, sign-in prerequisites, and the surrounding tool chain, which is complete for a nested-object input with no enums.

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 'brief' object is fully documented with field names, ranges (1-8 valueProps, 2-5 shotCount, 6-20 totalDurationSec) and enum-like options. The description adds only '2-5 shots' which duplicates the schema, so the baseline 3 for high coverage applies.

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

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

Opens with a specific verb+resource ('Turn an ad brief into a storyboard') and immediately enumerates the concrete output ('2-5 shots with framing, the spoken line, the caption and the duration of each'). This clearly distinguishes it from sibling generation tools like generate_ad or estimate_ad_cost, which it explicitly names as downstream steps.

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 an explicit ordered workflow: produce the storyboard, show it to the person, edit if needed, then price with estimate_ad_cost and submit with generate_ad. It also states when auth is needed and how to satisfy it. This is about as complete as usage guidance gets.

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