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

Goes well beyond the readOnly/idempotent/non-destructive annotations provided: it discloses the 12-ad result cap, clarifies that minSightings counts stored captures 'not impressions', warns that counts and spans 'do not prove continuous runtime or spend', and states that cursor following requires the same query, sort and filters. These are non-obvious behavioral constraints an agent would otherwise get wrong.

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?

Dense and front-loaded: purpose first, then sort/filter semantics, then the caveat, then pagination. Every sentence carries information, though the page is a long run-on chain of terse clauses that could be segmented for easier scanning.

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 an 11-parameter search with zero schema descriptions and no output schema, the description covers the semantically tricky filters but omits the large remaining filter surface (platform, category, subcategory, format, days, query) and gives no hint of the returned ad fields. Adequate minimum, with clear gaps.

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 description coverage is 0% across 11 parameters, so the description carries the full burden. It explains sort, minDays, minSightings and searchIn=transcript well, but leaves query, platform, category, subcategory, format, days and cursor unexplained — and notably never distinguishes the 'days' parameter from the near-identical 'minDays' parameter with the same enum.

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 ('Search stored NewsBreak/Rumble ads') and immediately constrains scope with the 12-result cap, so an agent can tell it apart from sibling tools. It does not name compare_ads, get_ad_evidence or get_funnel, so differentiation from siblings is left to inference. One inaccuracy: the platform enum includes 'youtube' while the description names only NewsBreak/Rumble.

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 real when-to-use guidance for the filter set: sort=newest vs longest_running, what minDays and minSightings keep, and an explicit exclusion ('These filters do not apply to transcript search'). It also tells the agent how to continue pagination. It never says when to prefer this tool over compare_ads or get_ad_evidence.

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