Ad Radar

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the result is a frequency count 'over all of its ads in the library', clarifying the aggregation scope rather than a sample or single-ad view. It omits any pagination or result-size detail.

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 tight sentences, front-loaded with what is returned and its aggregation scope, with the parameter provenance tacked on second. No filler or redundancy.

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 must carry the return-value burden, and it does explain the shape of the result (hooks, hook mechanisms, angles with counts). Missing details such as paging, limits, or ordering keep it from being fully complete, but nothing critical is absent for calling it correctly.

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 the single parameter is fully documented in the schema, so the baseline is 3. The description's note that advertiserId comes from search_ads rows largely repeats the schema's own wording, adding little new semantics.

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: returns an advertiser's most-used hooks, hook mechanisms and angles, aggregated as counts across all of its ads. This distinguishes it from sibling search_ads (raw rows) and get_ad (single ad), letting an agent tell it apart without opening a 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?

There is no explicit when/when-not guidance or named alternative (e.g., winning_patterns). The one usage clue is the workflow linkage: 'advertiserId is the advertiser id shown in search_ads rows', implying you call search_ads first, but the selection criteria versus siblings is only implied.

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, non-open-world, so the safety bar is low. The description nonetheless adds real interpretive context beyond them: spendEstimate is engagement-derived, not real spend, spendLowerBound is a true minimum, text fields are null when unavailable, and transcripts are English translations with translatedFrom/transcriptOriginal. Operational details (auth, errors, invalid-key behavior) are absent but not critical here.

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 purpose, then a dense but purposeful enumeration of return fields, null semantics and translation behavior. It is a long run-on paragraph, but with no output schema each clause carries information the agent cannot get elsewhere, so little is wasted.

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 correctly carries the burden of explaining the return shape, and does so thoroughly, including null handling and translation fields. The main gap is what happens when the key doesn't resolve or is malformed, which is minor for a read-only lookup.

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?

One parameter with 100% schema description coverage — the schema already documents the accepted key formats (adKey, bare id, Meta Ad Library id). The description adds nothing about the key, so 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 first clause states a specific verb and resource: 'Returns the full record of one ad.' The scope (single ad by key, versus the sibling search_ads which lists ads) is discernible from 'one ad' and the reference to tags that 'search_ads shows,' though no sibling is explicitly named as the alternative.

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 never states when to reach for this tool versus search_ads or the other siblings, nor that it should be called after a search to expand a specific result. The search_ads mention is a field-format cross-reference, not usage guidance, so the agent must infer the lookup workflow.

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, so the safety profile is covered. The description adds useful behavior beyond that: the return is JSON with the template in a 'template' field (compensating for the missing output schema), and it discloses that product/niche are written into the template and that omitting product leaves a placeholder.

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 return shape, then parameter semantics. It is slightly redundant where it re-explains the 'kind' enum already documented in the schema, but every sentence still carries useful information.

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 steps in and describes the return payload (JSON with the 'template' field). Combined with full parameter coverage and clear kind semantics, an agent has everything needed to call this correctly.

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 further by explaining the effect of 'product' (written into the template) and the fallback placeholder when it is absent, plus distinguishing the two 'kind' behaviors. It adds real semantic value over the enum and field descriptions.

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 returns a prompt template built from one ad, for the user to run on their own product. It also spells out the two output variants (kind='swipe' vs kind='analysis') in concrete terms, so an agent can distinguish this from siblings like get_ad or advertiser_hooks 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?

The description explains what each kind produces and notes the template is meant for the user's own product, which implies when to reach for it. However, it never names an alternative sibling or states when NOT to use this tool (e.g., use get_ad for the raw ad, advertiser_hooks for hooks), leaving routing to inference.

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, idempotentHint, non-destructive and a closed-world scope, so the safety profile is fully covered. The description adds value by disclosing the shape of the result (dimensions with their valid values), but says nothing about caching, stability of slugs, or whether the list is exhaustive/fixed.

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, no filler, and the primary purpose is front-loaded before the cross-reference to search_ads. Every clause earns its place.

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, so the description correctly compensates by stating what the tool returns (taxonomy dimensions plus their valid values) and why that matters. For a zero-parameter read-only lookup, nothing an agent needs 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?

The tool takes zero parameters, which sets the baseline at 4. Schema coverage is 100% and there is nothing for the description to clarify, so no adjustment is warranted.

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 ('Lists the taxonomy dimensions of the Ad Radar library') and enumerates examples of what those dimensions are, so the agent knows exactly what comes back. It also ties itself to a sibling by naming the 'tags filter of search_ads', which no other tool in the list would do.

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 second sentence establishes the reason to call it: these slugs are what the tags filter of search_ads accepts, implying it should be used to discover valid filter values before searching. It stops short of an explicit when-to-use/when-not-to-use statement or naming a fallback if the taxonomy is already known.

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), and the description layers on substantial behavior the annotations cannot convey: default filtering to active ads, sort default, row compaction, null semantics for headline/body, truncation at 140/280 characters, and the caveat that spendEstimate is an engagement-based estimate with spendLowerBound meaning a floor.

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 but front-loaded: the purpose and default behavior come first, then row semantics and caveats. Every sentence carries information, though the paragraph is long and a few clauses (truncation vs get_ad) could be split for 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?

With 11 optional params, nested tag objects and no output schema, the description compensates well by describing row shape, field provenance, truncation behavior and estimate semantics. An agent has what it needs to call it correctly and interpret the results.

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 adds real meaning: it ties the tags dimensions/slugs to list_taxonomy's output as the valid source, and clarifies that adKey from rows is what get_ad and get_swipe_prompt accept. That elevates it above the schema-does-everything baseline.

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+resource (search the Ad Radar library of FB/IG ads from the Meta Ad Library) and scopes it with a concrete qualifier ($50k+ estimated spend). It distinguishes itself from siblings by naming get_ad, get_swipe_prompt and list_taxonomy and explaining how each relates.

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 clear context: default is active-only, sorted by score, compact rows; use get_ad for full untruncated text; use list_taxonomy for valid tag dimensions/slugs; adKey feeds get_ad and get_swipe_prompt. It stops short of explicit when-not/exclusion guidance, but the routing to alternatives is unambiguous.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real value by sketching the return payload (lift, adoption by ads/advertisers, example ads), explaining the doThis vs 'lower' split at the above/below-average boundary, and confirming exampleAdKeys are valid get_ad inputs.

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 dense but front-loaded sentences; the primary return shape leads and the supporting keys follow. The semicolon-heavy middle sentence is slightly compressed but every clause carries information.

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, so the description must sketch the return shape, and it does – lift, adoption, example ads, doThis/'lower' grouping. The only gap is how the format parameter affects results, which is minor for a single optional filter.

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?

Only one parameter with 100% schema description coverage, so the schema already documents the format enum and its default. The description adds nothing about how the format filter changes the computed lift, which is the baseline 3 for schema-documented parameters.

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 precise verb and resource – returns lift per taxonomy value with adoption counts and example ads – and anchors it to a known artifact ('What to do now' block of Ad Radar). An agent can distinguish this from advertiser_hooks, search_ads and list_taxonomy 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?

Usage is implied through the 'What to do now' analytics-block mapping and the note that exampleAdKeys are consumable by get_ad, which hints at a call chain. However, it never states when to prefer this over siblings like search_ads or list_taxonomy, nor any exclusion or prerequisite.

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