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

Beyond the readOnlyHint/openWorldHint annotations it adds context an agent cannot get elsewhere: billing cost of 4 credits per network, that only active ads are returned, and the ranking heuristic (30+ days running or 3+ variations = strong winning-ad signal). That ranking and cost disclosure materially change how an agent should budget and interpret results.

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?

Information is front-loaded: what it searches, what it returns, how it is ranked, then use cases and cost. It is dense but every clause carries content; the enumeration of return fields makes one sentence long but is not padding.

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

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

With no output schema, the description appropriately enumerates the returned fields and the sort order. Remaining gaps are modest but real: result volume/pagination behavior and the 40-item limit are not addressed, so an agent cannot predict how many ads come back per network.

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 80%, so the schema carries most parameter meaning. The description still adds value by tying 'per network' cost to the platforms array (adding networks multiplies credits) and by framing the query as a topic/product/keyword. It doesn't clarify limit behavior or the meaning of country=ALL beyond what the schema says.

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

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

The description names a concrete verb and resource ('Active ads about a topic in the public ad libraries of Meta, TikTok and LinkedIn') and enumerates what is returned (copy, headline, CTA, landing page, format, placements, days running, variations). It is clearly a keyword/topic search over ad libraries, which implicitly separates it from advertiser-scoped or single-ad siblings, but it never names those siblings 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?

It states intended scenarios directly: 'what is trending in X ads', creative research and offers, and it discloses a transactional condition ('Costs 4 credits per network'). There is no explicit when-not guidance or pointer to alternatives such as advertiser_ads or read_ad for narrower lookups.

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