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 establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered; the description goes further by disclosing non-obvious behavior: brand_name is matched literally, country/city-qualified strings return nothing, and results span all countries so the agent must pick by region. It does not discuss rate limits or result volume, but the failure-mode disclosure is genuinely useful beyond the annotations.

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 dense block that is well front-loaded: usage trigger first, then what it returns, then parameter pitfalls, then result interpretation. Every clause earns its place, though the matching rules and result-scoping advice are packed tightly enough that a slight restructuring would improve scannability.

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?

Output schema exists, so return-value detail is correctly omitted, and annotations cover the safety profile. The description completes the picture with trigger conditions, parameter pitfalls, and next-step routing; the only untouched area is what to do when multiple advertisers match beyond the brief 'pick the one whose region matches'.

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 'bare brand name or bare domain, not both, and no country or city' rule, so the schema already carries the semantics. The description largely restates that constraint and adds only the consequence ('returns nothing'), which is a marginal gain over the structured fields.

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 (looks up) and resource (advertiser ID and domain) in a named system (Google Ads Transparency Center), and positions itself relative to siblings by calling itself the 'first step before get_google_ads'. An agent can distinguish it from get_google_ads, get_google_ad_details, and get_meta_platform_id 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?

Explicitly scopes usage to researching a brand's Google advertising on Search, Display, or YouTube, names the follow-up tool (get_google_ads), and gives a when-not rule via the input constraint (never pass country/city qualifiers). Nothing about selection 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=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?

Annotations already declare readOnlyHint/openWorldHint/non-destructive, and the description layers on substantive extras: server-side throttling of parallel single-ID calls, 1-credit-per-page fetching, the may_be_inactive signal, and the headline-may-be-null-on-video edge case. These are operational traits not visible in any structured field.

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 sentence is front-loaded and well formed, but roughly half the text is show_ad_carousel orchestration policy that belongs with that tool rather than this one, making the block long and partly duplicative. The param guidance in the middle is useful but interleaved with workflow commands.

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 sketches returns (ad content, dates, targeting, media_urls lookup) while covering output richness, pagination via cursor, credit economy, and downstream rendering obligations. Nothing an agent needs 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?

Coverage is 100%, so the schema carries the load and the baseline is 3. The description still adds marginal meaning the schema lacks, such as a concrete min_duration_days=7 example, why include_reach matters (reach and age/gender/country delivery demographics), and the batch-one-list idiom for platform_ids. Much of this nonetheless paraphrases existing 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 precise verb and resource plus its entry condition: "Use this when you have a Meta Platform ID and want to see what ads a brand is currently running." This cleanly separates it from search_meta_ads_by_keyword (keyword-driven) and get_meta_platform_id (ID resolution).

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?

Names explicit when-to-use (have a Platform ID), how to batch across brands, and hands off to three named siblings (analyze_ad_image/analyze_ad_video via media_urls, get_competitive_brief for cross-brand comparison, show_ad_carousel for rendering). It also states when the carousel step is skipped (zero ads).

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 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 readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety and scope profile is covered. The description adds the filterable dimensions but says nothing about return format, pagination behavior, or credit cost. With annotations bearing most of the burden, this is adequate but thin.

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 the usage trigger first and the supported search modes following. Efficient with no redundant padding, though it is minimal enough that slightly more detail could still have fit.

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?

The tool has an output schema and full annotation coverage, so return values and safety needn't be explained. Given those aids, the description is sufficient for a search tool, though it omits any mention of pagination or the credit/multi-turn conversation mechanics that the schema handles.

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 fully documents all 10 parameters including pagination_token, conversation_id, and the company/company_name alias. The description only echoes the filter categories already in the schema, adding no meaning beyond it. 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') and resource ('LinkedIn ads') plus the three search dimensions (company name, keyword, company ID), which cleanly separates it from the Google/Meta/TikTok search siblings by platform. It stops short of explicitly differentiating from get_linkedin_ad_details (search vs. detail lookup), so it isn't fully sibling-resolved.

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?

Opens with 'Use this when you need to...' and describes the trigger conditions and optional filters, giving clear context for invocation. It never states when NOT to use it or names an alternative tool (e.g., get_linkedin_ad_details), 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond them: the full-library cross-brand scope, the mandatory show_ad_carousel follow-up, the {ad_id, page_id} reference format, and cross-platform carousel mixing. It does not state auth/rate-limit behavior, but the mandatory downstream-call workflow is substantive disclosure.

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 alternative-routing are front-loaded and tight, which is good. However, roughly 70% of the text is a verbose, partially repetitive carousel-placement protocol ('REQUIRED', 'at least once this turn', 'Never render just 2-3 ads', 'strictly point → its carousel') that is more about show_ad_carousel than about this tool, bloating 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?

An output schema exists, so return values need not be explained, and the description covers purpose, alternatives, filters, the mandatory downstream rendering step, and the zero-results edge case. It is complete enough for correct invocation; only auth/permission or pagination-context notes are absent.

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 14 parameters (query, country, status, media_type, date range, sort_by, search_type, etc.) are already documented in the schema. The description only restates the existence of 'optional country, status, media type, and date filters' and adds no syntax, defaults, or interaction rules beyond what the schema provides, so baseline 3 is correct.

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 gives a specific verb and resource (discover ads by keyword/topic, full Meta Ad Library) and explicitly distinguishes itself from a sibling by contrasting with get_meta_ads, which 'only returns ads from the brand's own page.' It also names a second use case (partnership/influencer ads via creators), so 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?

It states exactly when to use this tool ('without knowing a specific brand', influencer/partnership discovery) and names the alternative (get_meta_ads) plus the condition that separates them. It also gives explicit when-to-skip guidance for the downstream carousel call (zero ads returned), leaving nothing 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=true, openWorldHint=true, destructiveHint=false. The description adds valuable behavioral context beyond annotations: exact-match and case-sensitive matching semantics, EU-only coverage, that results include first/last shown dates, that no engagement metrics exist at search level. It does not cover rate limits or pagination behavior, keeping 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?

The first half is tight and front-loaded with the search contract. The second half ('SHOWING THE ADS') is a long procedural block about carousel sequencing that belongs to show_ad_carousel's contract, not this tool's search contract; it bloats this tool's description significantly. It earns some place because it's a cross-tool requirement, but the volume is disproportionate.

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 not be explained, and the description correctly focuses on the search contract. It covers scoping, matching semantics, and result fields. The main gap is pagination (cursor exists but isn't explained beyond the schema description) and no rate-limit context. Adequate for the complexity, though the carousel digression dilutes focus.

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 schema already documents all six parameters including the aliases. The description nonetheless adds real semantic value: it explains that query and brand_name are aliases for advertiser_name, that the match is exact/case-sensitive, and gives the crucial hint that the value is often the parent/legal name (Anysphere vs Cursor). That's meaning beyond the schema, so a 4.

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+scope: search TikTok's public EU DSA ads library by advertiser name. It also distinguishes itself from the sibling get_tiktok_ad_details by naming the boundary (search-level vs details). An agent can tell this apart from search_meta_ads_by_keyword and get_tiktok_ad_details immediately.

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 and when-not-to-use: it says to retry with different capitalization on zero results, to point to library.tiktok.com as fallback, to use get_tiktok_ad_details for landing page/targeting, and to ONLY call show_ad_carousel when ads exist. This is unusually explicit 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?

Goes well beyond the annotations: discloses a hard 20-ad cap, cache-warming prerequisites for Google/LinkedIn/TikTok with credit-spend consequences for refetching, and that non-identifier fields are discarded because the server reconstructs from its own cache. Annotations cover only read-only safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense and front-loaded with the action and the upstream dependency, but it is long and duplicates the context/conversation_id guidance already present in the schema, which dilutes an otherwise efficient 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?

Given an output schema exists, return values need not be explained. The description nevertheless covers caching, credit costs, the safe cap, overflow handling, and per-platform ref formats, leaving no material gap for correct invocation.

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: per-platform ref shapes with required vs recommended fields (ad_id required, page_id recommended) and the strong constraint that body/headline/media_url/cards are ignored. It largely restates the context/conversation_id rules already in 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 ('Render a visual ad carousel widget inline') plus the resource URI, and makes clear this is a display step rather than a fetch step, distinguishing it from get_meta_ads/search_* siblings.

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 names the upstream tools to call first (get_meta_ads, search_meta_ads_by_keyword, get_google_ad_details, etc.) and the condition that selects this tool ('when the user benefits from visual evidence'). It also prescribes invocation cadence ('call multiple times, once per point') and scoping ('pass only the ads that evidence one point').

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real value beyond them: it is free/no-credits and imposes a hard privacy constraint against including emails, names, or personal data. It does not state what happens after submission, but the core behavioral traits are 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?

Front-loaded with purpose, then triggers, then constraints, in a compact block. Slightly dense with several distinct rules packed together, but every sentence earns its place and nothing is padded.

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 7-parameter write tool with full schema coverage and no output schema, the description covers purpose, triggers, cost, and privacy adequately. A brief note on what happens to the submitted feedback would make it fully self-contained.

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 seven parameters in detail. The description reinforces the PII constraint and hints at the missing_tool category, but adds no syntax or format guidance 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 — send the user's feedback about Proxy to the Proxy team — and the tool is clearly distinguishable from all data-retrieval siblings. An agent knows exactly what this does 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 explicit triggers (user asks to send feedback, complains, praises, or needs data no tool covers) plus a concrete escalation rule ('offer it after a tool fails twice'). It even names the missing_tool category for the gap case, leaving nothing to inference.

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