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

With no annotations, the description carries the full burden and does: it discloses wallet billing at per-respondent rates, the ~15 minute wait with progress reporting, the timeout/retry hazard, and the aggregation level ('You get the totals, without individual answers'). It also pre-empts misinterpretation by framing predicted rates as a panel's reading benchmarked against placement and industry, 'not a forecast of a live campaign'.

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 and the paragraph order (what it does → pricing → input rules → flow → returns) is logical. There is some duplication: 'Every plan tests up to 4 creatives on a panel of 100, 200 (the default), 400 or 1,000, the sizes the web offers' restates the population_size enum and media maxItems, and the long Returns block is dense, but it is load-bearing given there is no output 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?

For a 7-parameter tool with nested objects, no annotations and no output schema, this is unusually complete: it documents the return shape per mode, billing, latency, timeout recovery, input validation rules, and how to interpret the numbers. An agent has everything needed to call it correctly and handle the failure case without guessing.

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 earns above that by adding constraints the schema does not carry — accepted file types and the 10 MB image / 100 MB video caps, and the requirement that the link open without signing in and point at the file, 'not a page that shows it'. It also ties population_size and media count to pricing, which the schema does not.

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 ('Test ad creatives in Ads Labo') and immediately explains the mechanism: a simulated panel scrolls past the ad in a chosen placement. It clearly splits the two modes (1 creative = predicted metrics, 2-4 = comparative verdict), so an agent knows exactly what it gets. It stops short of naming which sibling to use instead (e.g. screen_creatives or compare_options), so sibling differentiation is only implicit.

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 RECOMMENDED FLOW block gives an explicit ordered sequence with named siblings: list_demographic_presets when no audience is picked, preview_cost for pricing, confirm with the user, then run. It also states the error path precisely ('On error=timeout with a sim_id... collect it with get_simulation, do not re-run'), which prevents duplicate spend. What's missing is any exclusion rule against the other analysis siblings.

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