Meta Ad Library, Google Ads Transparency & Video Ad Analyzer

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the no-effect-on-terminal-states rule, which is exactly what makes the idempotent hint meaningful, plus the fact that updated run details come back. It omits auth/permission requirements and any rate-limit behavior.

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?

Front-loaded with the core action and the state constraint, and every prose sentence earns its place. The 'USAGE EXAMPLES' block of raw user_input lines is mostly decorative and pads the definition slightly.

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 an output schema present, return values need not be spelled out, and the description still notes that updated run details are returned. For a two-parameter mutation with full annotation coverage, only auth requirements are unaddressed, which is a minor gap.

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 100%, so both parameters and the 30-second graceful-abort timeout are already documented in the schema. The description only gestures at 'gracefully' via an example, adding no syntax or semantic meaning beyond the schema. Baseline 3 applies.

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?

Specific verb (Abort) plus resource (Actor run) and a state qualifier ('currently starting or running'), which immediately distinguishes it from siblings like call-actor and get-actor-run. An agent can select it without opening the schema.

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?

Explicit when-to-use ('stop a run that is taking too long or misconfigured') and an explicit no-op condition (terminal statuses such as SUCCEEDED, FAILED, ABORTED, TIMED-OUT). It does not name an alternative tool or describe prerequisites, so it falls short of a 5.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world, so the safety profile is handled. The description still adds useful behavior: the default field set (all except outputSchema and serverInterface), the token-saving selective pattern, the readme fallback (summary when available, full README otherwise), and the 262144-byte section limit with un-expanded references.

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?

Front-loaded with the core action and the exact-name constraint, then segmented by purpose (output control, readme, when to use, examples). Slightly long, and the readme sentence partly duplicates the schema property text, but the density of routing information justifies most of the length.

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 an output schema present, return values need no explanation, and annotations cover safety; the description fills the remaining gap by explaining default vs selective field sets and Server Actor interface modes. It is silent on failure behavior (e.g., an actor that does not exist) and on how to obtain a valid ID, which would complete the picture.

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 goes beyond it by explaining how to combine the `output` flags in practice (selective true-flags, "common patterns" list, serverInterface string forms) and by clarifying the readme fallback semantics rather than just restating the field names.

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 ("Get detailed information about an Actor") plus the exact lookup key (ID or "username/name"), with a concrete example. Siblings operate on entirely different entities (runs, datasets, key-value stores, video analyses), so the resource distinction is unambiguous.

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?

Explicitly says "Use when querying Actor details, documentation, or input requirements" and backs that with four representative example questions. It adds a hard constraint ("Requires the exact ID or full name — do not construct a plausible-looking name"), but never names an alternative tool for discovering an ID, which is the natural when-not case.

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

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

Annotations already declare readOnly, idempotent, non-destructive, but the description adds real behavioral context beyond them: the summary vs. nextStep semantics, and that waitSecs blocks for up to 45s (default 30) before returning the current state. This is substantive added value, though it doesn't cover error/failure modes.

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?

Front-loaded with the core purpose, then segmented into Returns/USAGE/EXAMPLES blocks. Every line carries information, though the two usage examples are somewhat redundant with the USAGE prose, adding minor length.

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 an output schema present and 100% parameter coverage, the description need only orient the agent, which it does fully: purpose, when to use, wait semantics, and concrete invocation examples. Nothing needed to call it correctly is missing.

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, but the description goes further by framing waitSecs as a blocking/wait mechanism with its cap and default, and by describing what runId's run produces. Slight above-baseline value over the schema text.

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 ('Get detailed information about a specific Actor run') and enumerates the returned result fields (status, storages, stats, summary, nextStep). It does not explicitly distinguish itself from siblings like call-actor or abort-actor-run, so it falls just short of the 5 benchmark.

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 USAGE block names the condition ('check the status of a run started by any Actor-running tool') and explains when to pass waitSecs > 0 to block until terminal. It gives clear context but stops short of explicit exclusions or naming the sibling to use for other run operations.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description adds value by disclosing the default limit of 20, what clean=true does, and that results are the raw rows. Return-shape details are largely deferred to the existing output schema, which is appropriate.

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?

Front-loaded with the core purpose and the anti-scope sentence, followed by short usage notes and examples. Slightly redundant in repeating the limit default and the clean flag across sections, but nothing wasteful enough to hurt.

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 read tool with full schema coverage and an output schema, the description supplies the purpose, trigger, and key defaults an agent needs. Pagination interaction (offset/limit) and flatten behavior are left to the schema, which is reasonable given the output schema exists.

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 100%, so the schema already documents all eight parameters in depth. The description only restates the default limit and clean=true semantics, adding little beyond the structured fields; baseline 3 applies.

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 ('Get items (rows) from a dataset') and immediately delimits scope by saying it returns rows themselves, not metadata, counts, or schema. An agent can distinguish the intent without opening the schema.

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 a clear trigger ('When the user provides a datasetId and asks to retrieve results, output, data, or rows, call this tool directly') plus a usage section and two concrete examples. It lacks explicit when-not guidance relative to any alternative, but the sibling list contains no competing dataset-read tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered elsewhere. The description earns credit for adding behavioral context beyond that: the 'requires the exact key name' precondition and the note that the response preserves the original Content-Encoding, which most clients decompress automatically — a real return-value trait callers would otherwise trip over.

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 key facts — scope, exact-key requirement, encoding caveat — are front-loaded in three tight sentences. The subsequent USAGE and USAGE EXAMPLES blocks are somewhat redundant with the first paragraph, costing a little efficiency.

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?

A two-parameter read tool whose annotations, 100% schema coverage, and output schema already cover safety, inputs, and return shape. The description closes the remaining gap with the Content-Encoding behavior, which is exactly the non-obvious detail an agent needs.

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 100%, including the keyValueStoreId resolution rules (name vs. username~name) and minLength constraints in the schema itself. The description only reinforces that the key must be exact, adding little semantics beyond what the schema already documents, so the baseline 3 applies.

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 ('Get the value stored under a specific key in a key-value store') and preemptively scopes it against a listing tool: 'a single record, not a listing of all keys.' An agent can immediately tell this is a point lookup, not an enumeration.

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 says when to use it ('when you need to retrieve a specific record (JSON, text, or binary)') and includes two concrete usage examples showing the store identifier formats. However, it never states when NOT to use it or names an alternative/sibling for enumeration, so the guidance is implied rather than comparative.

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

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

Annotations already declare openWorldHint and destructiveHint, so the safety profile is covered; the description adds genuinely new behavioral facts not present in schema or annotations, namely the pricing model ($0.003 per ad, +$0.002 for transcript, not-found advertisers free) and the fact that results include running duration and creative IDs. It does not explain the async run/polling model, but that detail is captured in the waitSecs schema description, so no contradiction exists with the destructive/openWorld hints.

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?

Two sentences with essentially zero waste: one identifies the Actor invocation, the other packs source, selectors, return fields, optional add-ons and cost. Nothing is repeated or padded, and the substantive information follows immediately after the short wrapper clause.

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 12 optional parameters, complete schema coverage and an output schema present, the description supplies what an agent still needs: what data comes back, that transcripts are opt-in, and that per-ad cost and free not-found cases exist. The only real gap is that it says nothing about how to invoke it against the sibling run/dataset tools or about pagination, which is a minor omission given the rich structured fields.

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 100% and all 12 parameters carry their own explanations (region enum, dateFrom period syntax, onlyNew for scheduled runs, includeSrt, transcriptLanguages, etc.). The description only echoes the optional transcript, adding no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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: pull YouTube video ads from Google Ads Transparency by brand, domain or advertiser ID, returning video link, title, views, shown dates, days running, creative IDs and optional transcript. That is far more specific than the boilerplate opening sentence ('calls the Actor ... and retrieves its output results'). It implicitly distinguishes itself from tubetext--meta-ad-library-videos by naming the Google Ads Transparency source, though it never says so 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?

There is no when-to-use guidance, no exclusions, and no mention of the sibling tools such as tubetext--meta-ad-library-videos or get-dataset-items. The only hint of context is that advertisers can be given as brand, domain, ID or a Google Transparency link, which is input advice rather than routing guidance.

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

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

Annotations declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, so the safety profile is partly covered; the description adds genuinely new context with the cost model ('$1.50 per 1,000 ads; brands with no ads are free') and the note that 'brands with no ads are free', which lets an agent reason about spend. It does not contradict the destructive hint despite being a scraper (it writes datasets/KV entries for 'onlyNew'). It could have disclosed run duration or that an Actor run is started, but the pricing disclosure is a real value-add.

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 opening boilerplate ('This tool calls the Actor ... and retrieves its output results') restates the name and earns no place, and the actor blurb is a single dense paragraph mixing purpose, return fields, and pricing. The substantive content is compact once past the wrapper, but front-loading the actual scraping purpose before the boilerplate would be better.

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 an output schema present and 100% parameter coverage, the description needn't explain return values or parameter mechanics. It covers purpose and cost, and the async-run/polling behavior is handled in the waitSecs schema text. The remaining gap is that it doesn't situate the tool among its sibling ad-analysis tools, which matters for a 9-parameter billed scraper.

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 100%, so every one of the 9 parameters (brands, keywords, adTypes, country, onlyNew, waitSecs, activeOnly, maxAdsPerBrand, debugCheckDownloads) is already documented in the schema. The description adds no parameter-level syntax, defaults, or interaction rules beyond what the schema states. Baseline 3 applies when the schema does the heavy lifting.

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 gives a specific verb and resource: a Facebook Ad Library scraper that gets Meta (Facebook, Instagram) ads from brand names, page links or keywords, plus an enumeration of returned fields. Platform scope (Meta) implicitly distinguishes it from the Google Ads sibling, but it never names or contrasts with siblings like video-ad-analyzer or shot-by-shot-video-analysis. The generic wrapper sentence ('calls the Actor ... and retrieves its output results') is tautological but followed by substantive detail.

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?

Usage is implied by 'get Meta ads ... from brand names, page links or keywords', and the distinction between brand targeting and keyword search is available (though mostly carried by the schema). There is no explicit when-to-use/when-not guidance and no mention of the sibling tools that also handle video ads. An agent must infer the choice from the tool name alone.

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

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

Annotations flag destructiveHint=true and openWorldHint=true, and the description earns credit for explaining the real behavioral consequence: per-started-minute billing ($0.20/min, $0.60 minimum), failed videos are free, over-length videos are skipped free, plus a cost floor warning. That is meaningful context an agent needs before spending money. It does not explain latency or what a partial/terminal-status run returns, which is why it is not a 5.

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 opening sentence ('This tool calls the Actor "..." and retrieves its output results') is boilerplate tautology that should be replaced by the substantive blurb. The remainder is dense but earns its place; the trailing '· by TubeText' is pure noise.

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 an output schema present and 100% parameter coverage, most of the burden is already carried by structured fields, and the description adds the crucial cost/scope framing. The remaining gap is that a zero-required-param, 8-parameter tool gives no hint about which input mode (urls vs searchQueries vs datasetId) suits which intent.

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 100% and every parameter already carries rich inline docs (cost math, waitSecs polling semantics, overlay availability). The description adds essentially no parameter meaning of its own, so the baseline 3 applies.

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 actor blurb states a specific verb and resource set: 'Get timecoded shots, framing, camera moves, edit rhythm and AI director notes from public video links.' That is far more than a restatement of the name. However, it never distinguishes itself from the very similar sibling 'tubetext--video-breakdown-ai', so an agent cannot resolve which of the two to pick from the description alone.

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?

There is no 'use this when / not when' guidance and no reference to any sibling alternative, even though 'tubetext--video-breakdown-ai' appears to overlap heavily. The only conditional text is schema-level input requirement ('provide at least one of urls / searchQueries / datasetId') and cost warnings, not usage routing.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=true, so safety is covered structurally. The description adds genuinely new behavioural context: which sources are scraped and the cost model ('No analysis fee on failure; Actor Start and Meta fetching fees may apply'). It does not explain why the run is flagged destructive, nor what the response looks like on timeout (the waitSecs schema field handles nextStep polling instead).

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?

Three sentences, no filler, with the fee caveat and data sources packed in. The opening wrapper boilerplate ('This tool calls the Actor ... and retrieves its output results') is the least informative part and is placed first, slightly delaying the useful content.

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 13-parameter, open-world scraping actor with full schema coverage, an output schema and annotations, the description supplies the missing high-value context: sources, per-ad output fields, and cost/skip behaviour. The only substantive gap is sibling routing — an agent cannot tell from the description why to pick this over the two single-source analyzers.

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 100%, so all 13 parameters — including the mutually-exclusive-ish input modes, region enums, waitSecs polling behaviour and maxVideoMinutes skip rule — are already documented. The description restates the 'at least one of advertisers / metaBrands / adUrls / datasetId' rule but adds no semantics beyond the schema, so the baseline 3 applies.

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: analyze competitors' video ads, returning hook, angle, offer, CTA, script and shot list per ad, sourced from Meta Ad Library or Google Ads Transparency. An agent can tell what it produces. It does not, however, distinguish itself from the sibling tools tubetext--meta-ad-library-videos, tubetext--google-ads-transparency-video and tubetext--shot-by-shot-video-analysis, whose names suggest overlapping scope.

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 description (and the advertisers schema field) states the input precondition 'provide at least one of: advertisers / metaBrands / adUrls / datasetId', which implies when the tool can be invoked. But there is no explicit guidance on when to choose this combined analyzer over the three sibling analyzers, nor any exclusion criteria — the agent must infer the routing from the input mode it happens to have.

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