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

Annotations only declare readOnlyHint=false, openWorldHint=true and destructiveHint=false; the description goes well beyond them by disclosing real cost (1,036 credits for up to 50 enriched videos, 20 credits each thereafter, capped at 4,036) and latency (1–3 minutes, 60 s wait before returning a run id for get_run). A dry-run path via estimate=true is also disclosed, which is valuable for an expensive non-idempotent call. The only gap is that it does not say whether a partially completed Run is still charged.

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 definition is front-loaded with the trigger and outcome, then layers in alternatives, price and latency, with no filler sentences. It is dense and readable, though the capitalized product jargon ('Run', 'Digest', 'Customer') and the compressed clause 'estimate=true quotes' force a little re-parsing.

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 9-parameter, high-cost, slow, potentially asynchronous tool, the description covers the things that matter most: what it produces, what it costs, how long it takes, what to do on timeout, and where to go for cheaper or free alternatives. An output schema exists so return values need no explanation, though region and window remain undocumented anywhere in prose.

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 67%, so the schema carries most of the load, but the description adds genuine meaning: it explains the platform default and that facebook is opt-in, ties max_videos/max_credits to concrete price tiers, and explains that a run id is returned for long jobs. It does not explain region or window semantics, which the schema leaves terse.

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 concrete verb and resource chain: one Run searches TikTok, Instagram and YouTube, analyses and ranks videos, and returns a Digest with themes, hooks, formulas, gaps, angles and ranked ids. It explicitly names what it is not (search_videos, get_keyword, breakdown) so an agent can distinguish it from those siblings without opening their schemas.

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 an explicit trigger ('Use when the Customer asks what is working in a niche'), explicit exclusions with cheaper alternatives ('Not for a quick page of videos or one phrase's stats: search_videos or get_keyword cost far less'), and names breakdown for Named Creators. It also routes follow-up reads to get_research (free) and async polling to get_run, covering both before and after use.

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