ai-content-drop

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

Annotations already declare readOnlyHint/idempotent/non-destructive, and the description is consistent with that. It adds genuinely new behavior: it returns credit lines plus a total plus a quote_id, states no account is needed, and discloses that the quote_id is a prerequisite for the generator tools. Return-format detail is limited, but the output schema is the better place for that.

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

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

Three dense sentences with no filler: purpose, kind taxonomy, and return/contract information, all front-loaded. Every clause carries information the agent needs.

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

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

For a read-only estimator with a full output schema, this covers what is needed: what it prices, the output contract, the quote_id dependency, and the no-auth condition. Nothing essential is missing or left to inference.

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 still adds value by expanding the meaning of the kind enum values (what 'ad', 'ugc', 'avatar', 'decode' actually price) and by giving submission guidance ('quote exactly the fields you will submit'). It does not add syntax detail beyond the schema for the nested brief/storyboard objects.

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 studio job before making it') and then enumerates the four job kinds it prices (ad, ugc, avatar, decode). It also names the downstream consumers (generate_ad, generate_ugc_video, generate_avatar, decode_ad), so an agent can place it precisely relative to 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?

It states the timing ('before making it') and adds the concrete rule 'For an ad, quote exactly the fields you will submit.' That is clear context for when to call it, but it does not address the near-neighbour sibling estimate_credit_cost, which an agent would need to disambiguate between.

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?

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?

Goes well beyond the annotations: states that credits are charged only on success, that an OAuth sign-in or a specific API key header is required, and that a job id is returned for polling. This adds billing, auth and async-job context that the hints (readOnlyHint=false, idempotentHint=true) do not convey, and it is consistent with 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 and the required quote_id flow before the auth block, and every sentence carries information. The OAuth/API-key sentence is long and partly host-handled, but it is genuinely needed setup context rather than padding.

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

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

For a multi-parameter, async, credit-charging tool with an output schema, the description covers the cost gate, the auth requirement, and the follow-up call (get_generation). 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; the description still adds value by naming the sibling that produces quote_id and framing the quote as the agreed price, and by tying reference_video_url to a quote priced with reference_video_seconds. It does not add syntax beyond the schema for the remaining parameters.

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

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

States a specific verb and resource ('Make an AI video') and enumerates concrete output types (product ad, vertical social clip, cinematic shot, image-to-video). It distinguishes the image-to-video mode explicitly, but never differentiates itself from close siblings such as generate_ugc_video or generate_ad.

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

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

Gives a clear required workflow: obtain a quote_id from estimate_credit_cost first, then poll the returned job with get_generation. Prerequisites (quote must exist, price agreed) are stated. No explicit when-not-to-use guidance versus generate_ugc_video or generate_image is offered.

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

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?

Annotations already establish readOnly/idempotent/non-destructive, but the description adds genuinely new behavioral facts: no authentication is required and the list is live (so results change over time). It also clarifies that `count` reflects models currently offered. No safety or rate-limit info, but for a read-only catalog this is solid added value.

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

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

Three tight sentences: capability scope first, then the no-account and live-list facts, then the meaning of `count`. No filler and the most decision-relevant information leads.

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 0 required params, 100% schema coverage, and an output schema present, the description need not restate return fields; it still goes further by defining `count` and the live nature of the list. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so both parameters (type enum, max_credits threshold) are already fully documented in the schema — the baseline of 3 applies. The description's purpose phrases ('make a video ad, animate a photo, ... generate an image') loosely map to the video/image families but add no syntax or edge-case detail beyond the schema.

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

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

Specific verb (see/list) plus resource (AI video or image models) and concrete scope: what each model can produce and its credit cost for one generation. An agent can distinguish it from generate_video, generate_image, or estimate_credit_cost 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?

Clear context for use: it is a live catalog of available models, needs no account, and reports per-generation credit cost — useful before choosing a generator. It stops short of explicitly naming sibling alternatives (e.g., if you already know the model, go straight to generate_video), so usage is strong but not fully routed.

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

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

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

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?

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) already cover the safety profile, and the description is consistent with them by framing this as a free drafting step. It adds genuinely useful context beyond the annotations: 'Costs no credits' and detailed OAuth/API-key auth instructions with a concrete header format and 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-loaded with purpose and output shape, then workflow, then auth. Every sentence carries load, though the trailing auth block is dense and could be split for readability. Still efficient 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?

An output schema exists, so return values need not be explained; the description instead covers the input artifact, the downstream workflow, and the sign-in prerequisites. Nothing an agent needs to call 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 description coverage is 100% and the single nested 'brief' object enumerates its fields (brandName, valueProps, shotCount, aspect, etc.) in the schema itself. The description describes the output shape rather than adding input meaning, so the baseline 3 applies.

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

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

States a specific verb and resource (turn an ad brief into a storyboard) and immediately defines the produced artifact: 1-5 shots with framing, spoken line, caption, duration. It also names the sibling tools that follow it in the workflow (estimate_ad_cost, generate_ad), so an agent can place it precisely in the pipeline.

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

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

Explicit when-to-use and sequencing: show the storyboard to the person, edit if needed, then price with estimate_ad_cost and submit with generate_ad. This routes the agent to the correct alternatives and states the ordering constraint rather than leaving it to inference.

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