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

Beyond the annotations, it discloses that the call uses one search from the account's plan, that repeating the same niche and market on the same day does not, and that it returns either a result within about 25 seconds or a running status requiring retry after 30 seconds. It also explains the result structure (views, author, age, link, next_steps) and how follow-up works.

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?

Although dense, it is front-loaded with the use case, then covers parameters, plan consumption, timing, retry behavior, and exclusions in a compact paragraph. Every sentence provides operational information needed to call the tool and handle its async behavior.

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?

There is no output schema, and the description compensates by explaining the result contents, status modes, next steps, and relation to analyze_video. It also covers cost, idempotency-like same-day behavior, timing, and retry handling, which is complete for this tool's complexity.

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 0%, so the description carries the full burden. It defines niche as a slug from list_niches or the user's own words, market as us for an American user writing in English otherwise world, and explains period and kind defaults and enum meanings.

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: it finds Instagram reels that went viral in the last 30 days, with concrete output scope (7 market, 3 worldwide, outlier/stable labels). It also explicitly distinguishes itself from analyze_video for single linked videos, so an agent can separate it from 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 opens with an explicit trigger: use when the user names their niche and wants to know what went viral, what to film next, or ideas from their niche. It also names the exclusion and alternative: do not use for one linked video; analyze_video does that.

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