URL2Ad

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

Beyond the annotations, the description discloses what is actually produced (free, watermarked, 15 seconds, in the page's language), how the result is delivered (link sent by e-mail), and the idempotency contract in plain terms ("Calling it again with the same page and address returns the same ad") – more concrete than the idempotentHint flag alone. It also surfaces the anti-abuse requirement that the address must originate from the user in this conversation.

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

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

Four short sentences, front-loaded with the action and result, then the trigger, then the hard constraint, then the repeat-call behavior. No sentence is redundant with the title or the schema.

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

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

With only two required parameters, 100% schema coverage, full annotations and an output schema, the remaining burden is behavioral – and the description covers output nature, delivery channel, language behavior and idempotency. An agent has everything needed to call this correctly or hand off to a sibling.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine constraint beyond it: the e-mail must be the user's own and supplied in this conversation, never inferred. That is a real interpretation rule the schema does not encode, though the url parameter gets no extra detail beyond the schema's note that social profiles fail.

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?

"Starts building a free watermarked 15-second video ad from a public web page" names a specific verb, resource, format, duration and pricing model in one clause. The scope qualifiers (public page, page language) let an agent distinguish it from get_ad_status and request_change 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?

"Use it when the user asks for a video ad for their site, product, app or store" gives a clear triggering condition, and the email constraint adds an explicit when-not (never guess the address, never use someone else's). It stops short of naming the sibling tools as alternatives for status checks or edits, so the boundary is implied 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds real value by naming the exact status enum, the failure-reason field, the notion of 'changes left', and the polling loop semantics for asynchronous builds — behavior not present in the 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 front-loaded sentences with no filler: what it returns, when to call it, how to poll. The enumerated status list partially duplicates what the output schema likely carries, which is the only thing keeping it from a 5.

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

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

For a two-parameter status tool with an output schema and full annotation coverage, nothing an agent needs is missing: trigger conditions, async polling behavior, and the meaning of a failed state are all addressed. Return-format detail is correctly left to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents both parameters. The description adds meaning beyond the schema for wait_seconds by describing the polling pattern ('call again while the status is building'), which the schema's 'holds the answer' phrasing does not convey as an invocation strategy.

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 ('Returns the state of an ad started with create_ad') and enumerates the exact state values, which lets an agent tell it apart from create_ad and request_change without opening a schema. The scope is unambiguous: it is a status read for an existing ad, not a mutation.

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 names the triggering situation ('when the user asks whether their ad is ready, or before saying that it is') and gives the follow-on protocol for the asynchronous case ('pass wait_seconds and call again while the status is building'). The only mild gap is that it does not say when to prefer request_change, but the read-vs-mutate split is already 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 only declare readOnly/destructive/idempotent/openWorld flags; the description adds what the annotations cannot: the call consumes one of the user's remaining change credits (one free change included), the rebuild is asynchronous and takes minutes, and status must be polled via get_ad_status. That is meaningful operational context beyond structured data.

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, then cost, then the usage gate, then latency and follow-up — a sensible order with no filler sentences. Slight redundancy between 'a change the user asked for' and 'call it only when the user asked for this change' keeps it from a 5.

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

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

Output schema exists, so return values need no explanation, and the description covers the async lifecycle and the follow-up tool. It does not say what happens when the quota is exhausted (error vs. refusal), which is the one gap for a credit-consuming mutation.

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 ad_id and change are already documented, and the description largely restates the 'in their words' guidance. The only added nuance is the instruction to pass the request verbatim rather than paraphrased, which is minor. 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 and resource ('Rebuilds an existing ad') plus concrete examples of the change type (wording, colors, images), which clearly separates it from create_ad (new ad) and get_ad_status (poll status). An agent can tell what this does 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 an explicit precondition ('call it only when the user asked for this change'), an argument-handling rule ('pass their request as they said it'), and names the follow-up sibling get_ad_status. The quota cost is presented as a reason to be conservative, which is exactly the kind of gate an agent needs.

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