Proxy

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's added value is the operational caveat that TikTok cover URLs expire and a fresh one should be passed, plus the chaining guidance. That is genuinely useful behavioral context beyond the annotations, though no detail is given on rate limits, batching behavior, or failure modes on unreadable URLs.

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 when-to-use condition and efficient overall, with the source tools and TikTok caveat placed usefully. However, the opening sentence and the later 'Use for comprehensive ad analysis' restate the same usage trigger, which is a small amount of wasted text.

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, the description need not explain return values, and it is otherwise sufficient for a 6-parameter, chunked workflow tool. It could go further on how multiple media_urls are handled in one call, but nothing essential for correct invocation 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 description coverage is 100%, so all six parameters including media_urls and total_impressions are already documented in the schema, and the baseline is 3. The description only adds provenance context (which tools produce valid media_url values) and the TikTok URL freshness caveat, which is mildly useful but mostly redundant with the schema.

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+resource ('analyze ad images') plus an explicit enumeration of what is extracted (text, colors, people, brand elements, composition), which is image-specific and implicitly separates it from the analyze_ad_video sibling. An agent can tell what this tool produces 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?

States when to use it ('when you want to understand the visual elements in ad images') and names the upstream sources (get_meta_ads, get_google_ads, get_tiktok_ad_details) plus the follow-up tool (get_competitive_brief). It does not explicitly state when NOT to use it, e.g. directing video content to analyze_ad_video, so it falls short of a full 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 the safety profile (readOnly, non-destructive), so the bar is lower; the description still exceeds it by disclosing that signed CDN URLs (fbcdn/tiktokcdn/byteoversea) expire within minutes, that the server re-fetches a fresh URL for stable IDs, and that tiktok_id costs 1 credit. These are non-obvious operational behaviors an agent must know to call correctly.

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 use case and dense with actionable content, so every clause earns its place. It is a single long paragraph heavy with em-dashes and parentheticals, which makes it slightly harder to scan than it could be.

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?

An output schema exists so return values needn't be re-explained, yet the description still summarizes the response shape (transcript plus analytic sections) and links the next step. For a 9-parameter, zero-required tool, nothing an agent needs to select or invoke it 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 description coverage is 100%, so the baseline is 3; the description adds genuine meaning on top by defining the resolution precedence ('tiktok_id > ad_archive_id + page_id > media_url') and the coupling rule that page_id is required with ad_archive_id, which the per-parameter schema text does not state as a whole.

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 ('analyze video ad content') and enumerates the concrete outputs (timestamped Full Transcript, visual storytelling, audio elements, pacing, scene transitions, brand messaging). 'Video' distinguishes it cleanly from the sibling analyze_ad_image.

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 gives the triggering condition ('Use this when you want to analyze video ad content or get a transcript'), recommends the stable-ID path over media_url, states the mutual-exclusivity precedence chain, and names the follow-up sibling get_competitive_brief. Nothing is left 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, openWorldHint, and destructiveHint=false, so the safety profile is covered and the description adds real context on top: it discloses the computed signals returned, warns against fabricating hook_type/format, and constrains inputs to 'factual metadata'. It does not discuss cost, rate limits, or whether the brief depends on prior tool calls in the conversation.

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, front-loaded with the usage trigger before the input rules and return summary. The trailing sentence listing return signals is slightly redundant given an output schema exists, but it is short and does not bloat the definition.

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 aggregation tool sitting above the analyze_/search_ siblings, the definition covers the trigger, the required per-ad shape, the omit-if-unknown rule, and the shape of what comes back. Since an output schema exists, the description is not obliged to detail return values, and nothing an agent needs 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 baseline is 3, but the description earns above-baseline by explaining intent ('Pass factual metadata per ad') and the optionality rule for hook_type/format with an explicit anti-hallucination directive. The brands/context/conversation_id parameters are fully documented in the schema and the description sensibly does not duplicate them.

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-plus-outcome set (comparing brands, summarizing ad analysis, finding whitespace, producing takeaways) over 'analyzed ads across one or more brands', which clearly sets it apart from the search_* and analyze_ad_* siblings as a synthesis layer rather than a retriever. It stops short of naming those siblings, so an agent must infer the boundary itself.

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?

Provides a genuinely useful when-to-use enumeration (comparing brands, identifying winners, finding whitespace, surfacing patterns, takeaways/recommendations) and adds a negative constraint ('Omit hook_type/format if not derived from prior analysis — do not guess'). It never names an alternative tool or states when to prefer search_meta_ads_by_keyword or analyze_ad_video instead, so the routing is implied rather than explicit.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds content beyond that: it names the returned fields (remaining daily credits, reset time, plan info location). It does not mention auth or rate limiting, but for a read-only, closed-world tool those are not material.

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. Purpose comes first, then trigger conditions, then return values – correctly front-loaded so an agent can decide from sentence one.

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 zero-required-parameter, read-only tool with no output schema, the description covers destination (balance + plan), trigger conditions, and return contents. Nothing an agent needs in order 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 description coverage is 100% and both parameters are optional, so the schema fully documents 'context' and 'conversation_id' with detailed usage constraints. The description adds nothing about parameters, which is acceptable given the coverage but earns only the 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 and resource ('Check the user's Proxy credit balance and plan') rather than restating the tool name. It is trivially distinguishable from every sibling, all of which deal with ads, competitors, or feedback. An agent reading only this sentence knows exactly what the tool returns.

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 explicit trigger conditions ('credits, limits, their plan, hitting a wall, or changing plans'), which is unusually concrete routing guidance. It stops short of naming an alternative or an explicit when-not-to-use case, but no sibling overlaps this domain, so the omission is minor.

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=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds workflow context (output feeds show_ad_carousel, server hydrates creative/copy/media from cache) but says nothing about this tool's own behavior — batch limits, rate limits, or partial-failure handling when a list of URLs is passed.

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 purpose is correctly front-loaded, but roughly four-fifths of the text is prescriptive instructions for show_ad_carousel (ordering, generosity, cross-platform mixing) that belong in that tool's own definition. For a 3-parameter fetch tool this is heavily bloated and buries the operative trigger under tangential workflow rules.

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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description supplies what is genuinely missing for correct invocation: the URL-based trigger and the mandatory follow-up with show_ad_carousel. Error/empty-result handling is only touched via 'Skip it only when there were zero ads.'

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 ad_url, context, and conversation_id, making the 3 baseline appropriate. The description only reinforces how ad_url values flow into the carousel and adds no format, batching, or constraint detail beyond the schema.

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 opening sentence names a specific verb and resource ('have a Google ad URL and want full creative details') and enumerates the payload (variations, headlines, descriptions, regional targeting, impression data), which cleanly separates it from the search-oriented sibling get_google_ads. It never explicitly contrasts with get_linkedin_ad_details/get_meta_ads, but the Google+ad_url framing makes the scope 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?

The trigger condition is explicit and narrow: 'Use this when you have a Google ad URL.' That is enough to route correctly versus the search tools. However, no alternative or exclusion is named (e.g., when to prefer get_google_ads first), and most of the guidance concerns a downstream tool rather than this one.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the burden is lower. The description still adds valuable behavior: the returned payload is creatives with dates and URLs, the ID/domain prerequisite, and the mandatory downstream show_ad_carousel step, which is a genuine workflow constraint an agent must respect.

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 purpose is correctly front-loaded, but the entire 'SHOWING THE ADS' block is a long procedural prescription about interleaving carousels that arguably belongs in the carousel tool or workflow prompt. It is not pure noise, but it dominates the definition and buries the retrieval purpose under presentation rules.

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?

An output schema exists, so return-value documentation is unnecessary, and annotations cover safety. The description still supplies the prerequisite source, the content of the results, and the follow-up workflow, leaving little an agent needs missing before calling it.

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 seven parameters are already documented in the schema, including the limit/pagination, topic, region, domain and advertiser_id semantics. The description adds only the sourcing of advertiser_id/domain from get_google_platform_id, which the schema does not state, but otherwise does not go beyond the structured fields. Baseline 3 is appropriate.

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 — 'retrieve all active ads from a brand on Google — Search, Display, YouTube, and other networks' — and the title pins it to the Google Ads Transparency Center, which cleanly separates it from get_meta_ads or the LinkedIn/TikTok siblings. It does not explicitly contrast against get_google_ad_details, so the differentiation is implied rather than stated.

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 names a prerequisite ('advertiser ID or domain from get_google_platform_id') and a purpose ('for competitive analysis'), which is real context. However, it offers no explicit when-not guidance and never contrasts this tool with the adjacent get_google_ad_details or get_google_platform_id siblings, leaving the agent to infer the 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 cover safety (readOnly, openWorld, non-destructive), so the description correctly spends its budget on behavior instead: literal-exact matching, results spanning all countries with no country filter, and the need to pick the advertiser whose region matches the market. It does not mention rate limits or result caps, which keeps it from 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?

Every sentence carries a distinct instruction — purpose, chaining, matching syntax, failure mode, result interpretation, batching — with no restatement of the name or title. Front-loaded so the agent learns the constraints before composing the call.

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?

An output schema exists, so the description need not explain return values, and it instead covers the parts the schema cannot: argument formatting failure modes, multi-country result disambiguation, and the batching pattern. Nothing needed to invoke this 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 baseline is 3; the description still adds real meaning to brand_name by explaining the literal-match failure mode and the 'never both name and domain' rule that the schema only paraphrases. It gives no guidance on the context or conversation_id parameters, deferring entirely to the schema.

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 ('Looks up their advertiser ID and domain in the Google Ads Transparency Center') and positions itself in the sibling graph as the prerequisite step before get_google_ads. An agent can distinguish it from get_google_ads and get_google_ad_details 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?

Explicit when-to-use ('researching a brand's Google advertising on Search, Display, or YouTube'), what to do next (get_google_ads), how to handle multi-brand work (pass one list instead of parallel calls), and hard failure exclusions ('Purina México' returns nothing). This is close to a complete decision procedure.

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=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only which data categories come back, and since an output schema exists it does not disclose pagination, auth, or 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?

A single tight sentence with zero padding, leading with the usage trigger. It is lean and readable, though it front-loads the condition before the capability.

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 a full output schema, 100% parameter coverage, and annotations covering safety, the description only needs to establish purpose and trigger, which it does. It stops short of distinguishing itself from the other platform detail tools, which is the one remaining 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%; the schema already explains ad_id provenance, the context sentence rules, and the conversation_id echo requirement. The description adds no parameter meaning 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 (get details) and resource (LinkedIn ad), plus the payload: targeting, impression breakdown by country, and creative details. The LinkedIn specificity implicitly separates it from get_google_ad_details and get_tiktok_ad_details, though no sibling is named outright.

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 an explicit trigger ('Use this when you have a LinkedIn ad ID') and the intent that selects it (wanting full targeting/impressions/creative). It lacks any when-not or named alternative, but the platform-specific precondition makes the routing fairly 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?

Goes well past the readOnly/openWorld annotations: it warns that parallel single-ID calls are rate-limited server-side and will fail, discloses credit costs (1 per page, 1 extra per name resolution), explains the may_be_inactive signal, and flags that headline may be null on video ads. These are exactly the failure modes and cost traps an agent needs disclosed.

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 retrieval guidance is front-loaded and efficient, but roughly half the text is a lengthy, repetitive mandate about show_ad_carousel ('NEVER stack carousels back-to-back', 'Never render just 2-3 ads', 'Don't finish a turn...'), which is workflow policy for a sibling tool rather than a definition of this one. The core definition is buried under that volume.

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 16 parameters, a full output schema, and 100% schema description coverage, the description fills the remaining gaps: batching strategy, credit economics, pagination cursor behavior, and the downstream carousel contract. Nothing needed to invoke this tool 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; the description adds real value on the highest-risk parameter by insisting platform_ids be a single batched list with a concrete example, and reinforces the semantics of min_duration_days, active_only, status and sort_by. The remaining optional params (country, language, start_date/end_date) are left entirely to the schema.

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?

Opens with a specific verb+resource+scope: 'see what ads a brand is currently running on Meta', and clarifies that a brand name resolves the platform ID internally. It never explicitly contrasts with the sibling search_meta_ads_by_keyword, so the brand-vs-keyword distinction is left implicit rather than stated.

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 concrete when-to-use rules for nearly every optional flag: min_duration_days: 7 for proven winners, active_only for running ads, status='inactive' for retired creatives, sort_by for spend ordering, include_reach for audience questions. It also names the follow-up path (get_competitive_brief) and the required rendering step (show_ad_carousel).

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 (readOnlyHint, non-destructive, openWorld), so the description's job is to add beyond that. It does: it discloses the return shape (top 3 candidates sorted by verified status and followers) and the recommended fallback loop for ambiguous names. It doesn't mention rate limits or auth, but for a read-only search this is solid added context.

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 tight sentences, front-loaded with the usage trigger, followed by return behavior and a disambiguation strategy. No filler or restatement of the tool name.

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?

An output schema exists, yet the description still summarizes the shape of results (top 3, ordered), and it fully covers when to call it and what to do next. Nothing an agent needs to invoke 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 description coverage is 100%, so brand_names, context, and conversation_id are already documented in the schema. The description adds no syntax or format detail 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 ('find a brand's Meta Platform ID') and immediately clarifies the role versus get_meta_ads, which it names as the downstream step. An agent can distinguish this lookup tool from the ad-fetching siblings 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?

Explicitly frames the trigger ('Use this when you need to find a brand's Meta Platform ID') and provides a concrete disambiguation workflow: try each candidate with get_meta_ads and stop at the first that returns ads. This names both the condition and the alternative 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 read-only, non-destructive, closed-world behavior, and the description usefully adds that the tool is free with no credits. It also explains that the setup covers connection steps, page capabilities and limitations, and ready-made snippets, though it does not go into detailed auth or response-format 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?

The description is two compact sentences with no wasted phrasing. The core purpose is front-loaded, followed immediately by the usage condition and the free/no-credits detail.

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 instructional setup tool with no output schema, the description explains what the agent will get back: connection guidance, page capabilities and limitations, and snippets. The parameters are fully documented in the schema, and annotations cover the safety profile, so nothing critical 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 description coverage is 100%, so both parameters are already fully documented in the input schema. The description adds no parameter-specific guidance, which matches the baseline score of 3 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 states a specific verb and resource: getting the setup for a shareable page that reads live ads through Proxy. It clearly distinguishes this from sibling ad-analysis tools by focusing on page setup, connection instructions, capabilities, and snippets.

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 a clear usage condition: use when the user wants to share ad results with a client or team as a page. It does not name exclusions or alternatives, but the sibling tools are largely analysis/search tools rather than page-setup tools, so the intended use is still clear.

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=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: batch lookup is supported, results are served from a cache that the server backfills (creative/cover/body), and landing_page is flagged as the reliable brand signal because brand_name is often absent.

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 purpose and inputs are well front-loaded in the first two sentences, but the 'SHOWING THE ADS' block runs long with prescriptive carousel-formatting rules that read as workflow policy rather than tool semantics. It is not padded with fluff, yet roughly half the description is devoted to rules an agent shouldn't need in order to invoke this specific tool.

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 an output schema and full annotation coverage, the description supplies everything needed: input forms, batch support, field availability, and the downstream routing. Return-value formatting is correctly left to the output schema. It is complete, though the heavy workflow instruction is more than the tool's own scope requires.

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% and the schema itself documents that ad_id accepts a single ID, a list, or a URL, matching the description's 'single id/URL string or a list for batch lookup'. The description adds little parameter-level detail beyond the schema (the landing_page note concerns output, not input), so the 3 baseline for high coverage 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+resource ('Get full creative details' for a TikTok ad ID) and enumerates the returned fields (landing page, country targeting, dates, engagement data). It explicitly names the sibling that produces the required input (search_tiktok_ads) and the accepted URL form, so the agent can distinguish it from get_meta_ads/get_google_ad_details 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?

Gives an explicit trigger ('when you have a TikTok ad ID ... or a library.tiktok.com detail URL'), names the upstream tool that supplies the ID, and specifies supporting/skip conditions for the downstream carousel ('call show_ad_carousel at least once ... Skip it only when there were zero ads'). Routing 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 declare this a read-only, non-destructive, open-world operation, so the safety profile is covered. The description adds real value beyond that: it discloses the return shape ('names and domains') and, importantly, that the query param is auto-routed to domain or company_name. It does not discuss rate limits or authentication, but the added disclosure is meaningful.

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?

Four sentences, front-loaded with the primary use case before the parameter mechanics and the follow-up workflow. Every sentence carries information, though it is slightly long; nothing 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 an output schema handling return values and annotations handling the safety profile, the description fills the remaining gaps: when to invoke, how to choose between parameter styles, and what to do next. An agent has everything needed to call 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 coverage is 100%, so the baseline is 3, but the description adds genuinely useful meaning: it clarifies the either/or choice between a single `query` and the individual company_name/domain/description params, and specifies that `query` accepts a name, domain, or market description with automatic routing. The context/conversation_id session params are left to the schema.

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+resource ('find competitors for a company') and immediately distinguishes the tool from its ad-pulling siblings by positioning it as a discovery step that feeds them. An agent can tell what this does and where it sits in the workflow 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?

It gives two explicit triggering conditions ('when you want to find competitors' and 'when you've just pulled ads for a brand') and names the exact downstream tools (get_meta_platform_id, search_linkedin_ads, get_competitive_brief) for the next step. Routing guidance is concrete rather than inferred.

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, non-destructive, and open-world, so safety profile is covered. The description adds no behavioral context beyond that — no mention of credit cost, rate limits, the past-year coverage window, or the conversation_id handshake requirement, all of which live only in the schema.

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?

A single front-loaded sentence with no waste; the usage condition comes first and the search dimensions follow immediately.

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, full parameter documentation, and read-only annotations, the description needs only to establish purpose and entry conditions, which it does. The one notable omission is any hint that this tool consumes credits or that pagination/context handshake matters, but those are documented in the schema.

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?

With 100% schema description coverage, the schema already documents every parameter including defaults and format examples. The description only echoes the high-level filter categories (country, date), adding no syntax or constraint detail beyond the schema, 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?

States a specific verb (find/search) and resource (LinkedIn ads) plus the three ways to target them (company name, keyword, company ID) and the optional filters. It's clear what it does, though it never explicitly contrasts itself with get_linkedin_ad_details, so the search-vs-fetch boundary is only implied by naming.

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?

"Use this when you need to find LinkedIn ads by..." gives a clear triggering context and enumerates the search inputs. It stops short of when-not guidance or naming the sibling to use instead (e.g., get_linkedin_ad_details for a known ad).

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 establish read-only, open-world, non-destructive behavior. The description adds important behavioral guidance beyond annotations, including the required show_ad_carousel workflow and the distinction from get_meta_ads. It does not mention credit consumption or pagination behavior, but those are covered by the schema.

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 purpose is front-loaded, but the description is dominated by a long, repetitive set of carousel-rendering instructions. Several sentences restate the requirement to call show_ad_carousel, making it bloated for a search tool whose parameter semantics are already handled by the schema.

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?

Given the rich schema and output schema, the description covers the key purpose, alternative tool, and required post-processing workflow. It is complete enough to invoke correctly, though it spends disproportionate space on carousel behavior rather than search behavior.

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 14 parameters in detail. The description only broadly mentions optional country, status, media type, and date filters, adding little semantic meaning beyond the schema.

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: 'discover ads by keyword or topic' and 'Searches the full Meta Ad Library'. It explicitly distinguishes this from get_meta_ads by noting that get_meta_ads only returns ads from the brand's own page.

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 clear when-to-use conditions: when you do not know a specific brand, or when you want partnership/influencer ads via creators. It names the alternative tool and the condition that selects it, leaving little 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 only say read-only/open-world; the description adds material behavior the agent could not otherwise know: EU DSA scope, exact-match and case-sensitivity semantics, ordered multi-name execution stopping at the first hit, cost of '1 credit per name tried', and the absence of engagement metrics at search level. It also explains what first/last-shown dates imply about whether an ad is still running.

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 search constraints are front-loaded and scannable, but the description runs to roughly 350 words, and a large trailing block is post-call presentation policy for show_ad_carousel (interleaving, ordering, how many ads to render) rather than anything that helps select or invoke this tool. There is also redundancy with the schema on exact-match and the 4-variant list.

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?

An output schema exists and the description still flags the key return characteristics (first/last shown dates, no search-level engagement metrics, cursor pagination implied). For a read-only search tool with 6 params and full schema coverage, nothing an agent needs in order 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; the description mostly restates the advertiser_name schema (exact-match, case-sensitive, list of up to 4 variants tried in order). It does add genuine meaning — the parent/legal-name vs consumer-brand distinction with the 'Anysphere' not 'Cursor' example, alias acceptance, and credit cost. It leaves the context and conversation_id parameters, which carry non-obvious conversational rules, entirely to the schema.

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?

Opens with a specific verb+resource and immediately bounds the search key ('Advertiser names ONLY'), then names the sibling tools (search_meta_ads_by_keyword, search_competitors) it is not. An agent can distinguish this from search_linkedin_ads, get_meta_ads and the detail tools without opening any 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 explicit when-to-use (advertiser-name lookup), explicit when-not ('cannot search by topic, keyword, product category, industry or ad format'), and a concrete alternative pattern: run topic research on the Meta/competitor tools first, then feed the resulting advertiser names here. Follow-up routing is also stated (get_tiktok_ad_details for landing page and targeting).

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?

The annotations already mark this as read-only, open-world, and non-destructive, but the description adds substantial behavioral context beyond that: the server reconstructs ads from its own cache, non-identifier fields are discarded, Google ads must be pre-warmed via get_google_ad_details, and stale LinkedIn/TikTok refs may be refetched at credit cost.

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, the description is front-loaded with the core action and then proceeds through usage, scoping, cap, and per-platform reference rules. Every sentence carries operational value; there is no filler or redundant restatement of the schema.

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 complex, cache-dependent UI rendering tool, the description covers the critical prerequisites, call-scoping rules, limits, and identifier formats. Return-value explanation is unnecessary because an output schema exists, and annotations already cover the safety profile.

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 defines the ads, context, and conversation_id parameters. The description still adds meaningful parameter semantics for ads: exact per-platform identifier shapes, required vs. recommended fields, cache-warming prerequisites, and the instruction to pass only copied refs rather than full ad objects.

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: render a visual ad carousel widget inline at resource ui://carousel-mcp-v7. It also distinguishes the tool from its data-retrieval siblings by saying it should be used AFTER get_meta_ads, search_meta_ads_by_keyword, get_google_ad_details, search_linkedin_ads, or search_tiktok_ads.

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 explicit when-to-use guidance: after prior ad lookup tools and when the user benefits from visual evidence. It also specifies when to call it multiple times, how to scope each call to one point, the 20-ad hard cap, and per-platform cache prerequisites.

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 only declare it is a non-destructive write, so the description carries real added weight: it states the call is free with no credit cost, forbids including PII, and — most importantly — authorizes autonomous invocation without asking the user when results were poor or data was missing. It does not say what happens after submission (confirmation, storage, who sees it), which keeps it below 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?

Content is front-loaded with purpose before triggers, and 'Free — no credits' plus the PII ban are placed where they will be read. The middle sentences are noticeably run-on with stacked clauses (complaint/praise/missing-tool/after-two-failures in one breath), which costs a little clarity but nothing is filler.

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 8-parameter tool with full schema coverage and no output schema, the definition covers triggers, autonomy, cost, and privacy — everything needed to decide and call correctly. It leaves the post-submission response undefined and does not restate the conversation_id handshake, relying on the schema for that sequencing constraint.

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 baseline is 3. The description still adds meaning beyond the schema: it clarifies the missing_tool category case and the reporter=agent vs user distinction, and reinforces the PII prohibition that appears on the feedback field, tying the parameters to real invocation scenarios.

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 sentence names a specific verb and resource — sending the user's feedback about Proxy to the Proxy team — and the rest of the definition makes plain that this is the non-ad-data escape hatch, distinguishing it from every sibling (search_meta_ads, analyze_ad_video, etc.). An agent can identify this tool's role 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?

It enumerates trigger conditions (user asks, complains, praises, needs data no tool covers, a tool failed twice) and explicitly names the agent-initiated path with reporter=agent and no user confirmation. The category missing_tool case is also tied to a concrete alternative when no sibling covers the data, which is exactly the routing guidance an agent needs.

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