Spytrend

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the description's idempotency statement aligns but adds value by explaining already_saved behavior and billing details. It also discloses that saving incurs costs for ads and creatives but is free for others, which is crucial for agent decisions. However, it does not detail output schema, but since idempotency and cost are covered, a 4 is appropriate.

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

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

The description is dense and well-structured, with key information front-loaded (what it saves and what entity types are supported), followed by specific requirements and billing. Every sentence serves a purpose, and the use of bold for critical notes (MUST, OPTIONAL, BILLING) enhances scannability without waste.

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?

Despite having an output schema, the description still explains return behavior (already_saved) and billing, which are not fully captured in the schema. It covers all necessary details for correct invocation: entity type mapping, source of IDs, special hub requirement, folder naming guidance, and cost implications. This is complete for an agent to use safely.

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 description largely repeats parameter info. It adds minimal extra meaning, like clarifying that 'ids' must come from search results and that 'hub' is only required for hub entity type, but this is already in the schema descriptions. The billing details per entity_type add some value but not beyond what the schema implies.

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 clearly states the tool saves a selection of entities to favorites folders, naming the valid entity types and how IDs are sourced. It distinguishes itself from sibling search and get tools by focusing on the save action, and the detailed breakdown of entity types and required parameters makes the purpose 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 description explicitly explains when to use this tool (to save entities for later review) and provides guidance on prerequisite sources (search_* tools), the required hub parameter for hub entities, and folder naming preferences. It also indicates when it is not applicable (e.g., no duplication) and implies alternatives like list_favorites for reviewing saved items.

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?

Beyond the readOnlyHint annotation, it reveals the source ad exclusion, the pagination.total semantics, the existence of source_excluded and total_semantics fields, and the quota cost per row. This added context explains edge cases an agent might otherwise misinterpret.

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 dense and information-rich, with each sentence serving a purpose (purpose, distinction, output semantics, quota). It is slightly verbose but well-structured and front-loaded with the core action.

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 tool's complexity (pagination, output schema, annotations), the description covers behavioral quirks, quota, and alternative tools. It fully compensates for anything not obvious from the schema or annotations, making it complete for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the description adds little beyond the schema for parameters. It does reinforce the meaning of basis, but the schema already describes all parameters adequately; no new parameter-level insight is provided.

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 clearly states the verb (find) and resource (ads related to one source ad) with an explicit overlap basis (fanpage or domain). It distinguishes itself from visual similarity tools by directly naming find_similar_creatives, making the purpose 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?

It explicitly states when to use (entity overlap on fanpage/domain) and when not to (not visual similarity) along with the alternative tool. This gives clear selection guidance relative to siblings without any ambiguity.

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?

While readOnlyHint and destructiveHint already indicate a safe read operation, the description still adds meaningful behavior beyond annotations: threshold_status vs production default, result_status=bounded_native_cap meaning the upstream faces at most 20 candidates and has_more is conservative, the absence of media URLs, and QUOTA per delivered row. This is valuable operational context for an agent.

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 opens with the core behavior, then adds disambiguation, boundary behavior, output-usage guidance, and quota in a compact set of sentences. Each sentence carries information an agent needs; there is no filler or omitted critical nuance.

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 lightweight read-oriented tool with a strong schema, an output schema present, and helpful annotations, this description fills in exactly the gaps an agent cannot get from structured data: quota cost, upstream candidate cap, default threshold behavior, and which parameter to use. No critical external context is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% description coverage for the three params, so the baseline is 3. The description improves on that by explaining threshold semantics more concretely and by documenting that result cap is 20 and conservative, which directly makes limit and threshold more useful. It does not belabor the already-documented parameter types/defaults.

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 action and resource: 'Find creatives that look the same as one creative' using a named mechanism, the production similarity index. It also adds an explicit disambiguation—'This is visual similarity, not exact creative membership'—which helps an agent distinguish this tool from exact-match or metadata-based search tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly establishes the intended context: given one creative, retrieve visually similar creatives. It also gives follow-up guidance ('Returns metadata without media URLs; use get_media for selected ids') and clarifies semantics around threshold and result caps. It stops short of naming sibling tools like search_creatives or find_similar_ads for explicit when-not-to-use conditions, so it is not quite 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?

Beyond the annotations (readOnlyHint, openWorldHint, destructiveHint), the description discloses deterministic ordering, a bounded result cap of 5000, status fields (result_status/result_cap/total_status) for completeness, a quota of 1 token per row, and a dependency on a prior facets call. This is rich behavioral context that the annotations alone do not provide.

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 dense but well-organized, leading with the core purpose, then the workflow, then behavioral details, and finally quota. Every sentence adds value with no filler. The structure supports quick comprehension by an agent.

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 tool with 5 parameters, 2 required, and an output schema present, the description covers the necessary invocation steps, behavioral constraints, quota, and dependency on another tool. The output schema handles return structure, 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?

With 100% schema description coverage, the baseline is 3. The description adds meaning by explaining that param_key comes from the facets call, webmaster_id comes from search_webmasters, and values is an optional subset of normalized source values. It also clarifies the role of similarity_basis and rarity_count as output concepts, which helps the agent understand the data flow 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 clearly states the specific function: finding webmasters that share normalized URL-parameter values with a source webmaster. It explicitly names the mechanism (url_parameter_overlap) and the required dependency on get_webmaster_similarity_facets, distinguishing it from sibling tools like find_similar_ads or search_webmasters.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear workflow: first call get_webmaster_similarity_facets, then pass one returned param_key, optionally narrowing to selected values. It gives explicit prerequisites and ordering but does not explicitly compare against alternative tools or state when not to use it, which would make it 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?

The description adds substantial behavioral context beyond the readOnlyHint/openWorldHint/negative-destructive annotations: it details quota semantics (50/1/100 tokens), the live status of unsigned expiring CDN links (never put in reports), billing debits via `_meta.billing.tokens_charged`, no-charge edge cases (blurred cards, no usable media), no subscription behavior, field-absence semantics (body_index), and primary_creative selection status. This is rich, actionable behavior that far exceeds 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?

The description is thorough but long and dense, with many paragraphs and repeated references to the shared carousel used by both tools. It front-loads 'Fetch a single ad by its id' and then layers a large amount of billing and media edge-case detail. Every sentence does add value, yet the volume of information could overwhelm the average agent; there is no pruning or prioritization.

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?

Backed by a high coverage schema and output schema, the description still adds edge cases that are not present in structured data: body-field absence logic, the `expiring` CDN flag and its consequences, billing charge rules, `_meta.billing.tokens_charged`, and also the special behavior when source=tiktok. Considering the complexity of the tool and the provided schemas, this description is highly complete, although it could leave a few niche topics (e.g., error codes for non-existent ad IDs) to inference.

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?

Input schema has 100% description coverage for both parameters: `id` and `source` already have robust descriptions including source default and pricing. The tool description adds pricing side-effects and source-specific price warnings (`source=tiktok` in provenance), but does not add any meaning about parameter syntax, types, or constraints beyond what the schema defines. Baseline 3 is appropriate because the schema carries the weight.

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 opens with a specific verb and resource: 'Fetch a single ad by its id with FULL details including its creative media'—clearly distinguishing it from siblings like get_creative or get_media. It also enumerates exact fields returned (text, body_chars, title, creative URL, geo, status, advertiser), making the tool's 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 context of use is implied: call this when you need a single ad's full details by ID. However, it does not explicitly state when to choose this tool over get_media or get_creative, aside from a note that get_media(ad) has the same detail carousel. The source=tiktok switch is described, but no alternative pathway or 'do not use when' guidance is given, so the description carries only implied usage direction.

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 and destructiveHint=false, and the description adds substantial behavioral context beyond that: it is a paid surface with token costs per row, pending/error responses refund the reservation, totals are nullable with null meaning pending/unavailable (not zero), only the status section removes its own filter, and results are flattened with dimension field and truncation metadata. This is rich, non-obvious behavior that an agent needs to know.

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 dense but well-structured: it front-loads the core purpose, then covers cost, limits, return shape, null semantics, filter behavior, exclusions, and retry guidance. Every sentence carries information. It is long, but the tool is complex (49 parameters, paid surface, nuanced null semantics), so the length is justified. It loses one point for being a wall of text without paragraph breaks, which slightly reduces 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?

Given the tool's complexity (49 parameters, paid surface, output schema present), the description is remarkably complete. It covers cost, limits, null semantics, filter behavior, exclusions, retry guidance, and subscription category reporting. The output schema exists, so return values need not be described in detail. An agent has everything needed to call this tool correctly and avoid costly mistakes.

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 meaningful parameter-level context beyond the schema: it explains the default and maximum rows per section (10/20), which maps to max_items_per_section; it clarifies that totals are nullable and the distinction between null and numeric 0; and it notes that auto-applied subscription categories are reported in auto_applied_verticals and scope_note. It doesn't enumerate every parameter, but the schema already covers them, and the description adds the critical semantic nuances.

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 opens with a specific verb and resource: 'Get the bounded analytics overview for the current Meta /ads selection' and enumerates the exact breakdown dimensions (statuses, countries, AI categories, landing domains, advertisers, webmasters). It clearly distinguishes this from sibling search tools by emphasizing it is an analytics overview for the current selection, not a search or retrieval tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: for bounded analytics on the current /ads selection, and it names exclusions: 'No pagination, sorting, source, scheduler, force-scrape, TikTok, raw SQL or storage coordinates are accepted.' It also provides operational guidance: re-issue after retry_after_seconds when pending, do not blindly retry paid calls. This is strong usage guidance.

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

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

Annotations only declare readOnlyHint=true and openWorldHint=true, but the description goes far beyond: it discloses that the returned card includes exact precomputed counts, that top_creatives are the most re-uploaded creatives with media stripped, and that category counts are only for AI-labeled ads. It also discloses quota (1 token) and the top_creatives contract regarding market-wide reuse. No contradiction with annotations; the description adds rich behavioral context that annotations alone do not convey.

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 long, but most content is essential given the tool's complexity (many fields, nested contracts, interpretation rules). It is front-loaded with the core purpose and a list of fields, then procedural nuances. Some redundancy (e.g., repeating 'top_creatives' explanations) could be trimmed, but overall it is packed with actionable detail and avoids fluff. Not as succinct as possible, but justified.

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?

Despite an output schema existing (indicated by context), the description explains return contents thoroughly: the list of fields, the special semantics of counts (exact vs labeled), the top_creatives contract, and quota. It covers all practical aspects an agent needs to call the tool correctly, including id resolution and interpretation of metrics. No missing information is apparent for a 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?

The input schema describes 'id' only as 'the resource id to fetch' (generic). The description vastly enhances meaning: id can be an advertiser UUID or a Facebook page id, and provides multiple sources (ad's advertiser_id, get_trends dimension, get_creative's fanpages, page_id, or pasted Facebook link). It also explains automatic resolution of page ids and links. This far exceeds schema coverage and gives an agent concrete guidance on constructing the id value.

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 explicitly states the tool fetches a single advertiser's full card by id and enumerates all contained fields (name, external_id, avatar_url, page_url, total_ads, active_ads, etc.). It distinguishes itself from search_ads by positioning itself as the exact-count source and mentions alternatives like get_media and search_ads for other purposes. The verb 'Fetch' and resource 'advertiser's full card' make the purpose 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 description provides explicit usage directives: it is the cheap way to get exact ad counts, and warns against paginating search_ads for that. It also instructs to call search_ads when listing an advertiser's ads, explains how to resolve IDs (UUID, page id, Facebook link), and details how to interpret category counters and ai_coverage. It includes a clear exclusion (do not compare category counts to total_ads directly) and naming of alternatives, satisfying the 'when-not' criterion.

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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses extensive behavioral specifics: it never starts transcription, breakdown lists are sorted and capped at 1000, status values are explained (available_bounded, partial, unavailable), copy_language statuses are detailed, and media URLs are intentionally excluded. There is no contradiction with 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?

Though lengthy, the description is densely packed with essential details and every sentence serves a purpose. It is logically ordered: core fields, language specifics, breakdown behavior, id source, media exclusion, and quota. No fluff or repetition, and the most critical purpose is front-loaded.

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 tool with this many status codes, edge cases, and output nuances, the description leaves nothing critical uncovered. It explains all breakdown statuses, language copy statuses, sorting/capping behavior, and the quota, making it sufficient for an agent to call correctly without opening the output schema. Complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema describes the id as 'the resource id to fetch' with 100% coverage. The description adds crucial semantics: the id is a creative UUID from search_creatives and the same id is used for get_media, providing provenance and cross-tool linkage that the schema alone lacks. This elevates it above 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?

The description clearly states the tool fetches one creative's metadata and its bounded breakdown by id, listing specific fields like activity period, languages, and aggregates. It differentiates itself from siblings by noting the id comes from search_creatives and that media URLs are handled by get_media, making its purpose distinct and 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 description provides clear context for when to use this tool: when you need detailed creative metadata by UUID, especially from search_creatives. It also points to get_media for downloading media and mentions that fanpage ids feed other search filters, giving practical guidance. However, it doesn't explicitly state scenarios where one should NOT use this tool over alternatives, leaving some inference to the agent.

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?

Adds substantial behavior beyond the annotations: quota token costs, per-item failure handling, mixed-batch prefix processing, duplicate handling, fallback_urls retry on HTTP errors, and multilang content behavior. It even explains what happens to malformed/zero UUIDs. No contradiction with the readOnlyHint/destructiveHint 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?

The description is thorough but extremely long and dense, with many details that duplicate the output schema, such as the response fields block. It is front-loaded with the core purpose, but it would benefit from bullets or sectioning to improve scanability. While much of the content is valuable, it is not concise.

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?

Covers an unusually complete set of edge cases: quota billing, partial failures, mixed batches, fallback URLs, duplicate items, multilang selection, and pricing rules. Given the output schema exists, nothing critical appears missing for an agent to correctly select, invoke, and interpret the results of this paid endpoint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents both parameters with 100% coverage, including the entity_type enum and the ids array limits. The description adds operational context such as billing and malformed-id handling, but it does not meaningfully enrich the semantic meaning of the parameters beyond what the schema already provides, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action and resource: 'Fetch downloadable creative MEDIA (image/video URL + thumbnail) for 1-500 ad or creative UUIDs returned by search_ads / search_creatives.' It also says it is the 'paid delivery step,' which gives an immediate sense of why this tool exists and how it differs from free browsing tools. It distinguishes itself from get_ad by warning against duplicate fetching.

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 an explicit typical flow: 'search_ads ... → pick ids → get_media.' It also gives clear exclusion guidance: 'get_ad already includes media, so do not call get_media again for files you already received,' and notes 'get_usage is free.' This is strong when-to-use and when-not-to-use guidance.

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

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

Discloses important data-quality caveats beyond the annotations: traffic estimates, legacy snapshots, non-canonical page titles, correlation-only AI signals, missing rank behavior, and quota consumption. These are exactly the non-obvious behaviors an agent needs to interpret results 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?

The description is dense and long, but nearly every sentence carries a distinct warning or clarification that prevents misuse. The core purpose is front-loaded, and the additional caveats are organized around the returned fields rather than random trivia.

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 output schema exists, the description focuses on field semantics, entity-type caveats, quota cost, and the follow-up save action. It covers the important interpretation pitfalls and operational constraints without needing to restate the full return shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes the domain parameter well, and the description adds context about domain surfaces and the correct ID for saving. However, the added value over the schema is moderate; most parameter meaning comes from the schema itself.

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?

Clearly identifies the action ('Fetch') and resource ('one domain surface's FULL profile') with a specific domain parameter. The description also clarifies what the profile does and does not represent, which prevents misclassification of the entity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context: use it to fetch a single domain surface, and explicitly redirects saving to add_to_favorites with the correct entity type and parameter shape. It also tells the agent to inspect registrable_domain and domain surface type to avoid misreading the entity, though it does not contrast directly with the sibling search tools.

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 say readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds extensive behavioral detail: quota costs (1 token per delivered result, refunds for short pages), free plan restrictions (6-row preview, no pagination, offset refused), rate limits (60/min, 1000/hr, structured error code), concurrency admission (one heavy call at a time), pagination semantics (has_more/offset on certain dimensions, absent on others), and plan-window truncation with total_status='restricted'. It also notes that dimension semantics arrive in meta.dimension_semantics. No contradiction with 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?

The description is very long but structured: opening summary, dimension one-liners, then pagination, free plan, quota, and concurrency. It front-loads the core purpose and dimension list. However, there is redundancy, e.g., the 'FREE PLAN COUNTS' paragraph appears twice with near-identical text, and some sentences are dense. It earns a high score for necessity given the 52 parameters and intricate behavior, but loses a point for not being tightened.

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 tool's complexity and the existence of an output schema, the description covers most operational aspects: dimensions, filters, pagination, quotas, rate limits, concurrency, account linking, and free plan behavior. It deliberately defers per-dimension row semantics to meta.dimension_semantics delivered with the response, which is acceptable. Some specific details (e.g., exact output format for each dimension) are omitted, but the description explains they arrive with data. This is complete enough for an agent to call correctly, though a bit more explicit explanation of scaling signals could help.

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?

Though schema coverage is 100%, the description adds significant meaning beyond the schema. It explains common filters, dimension-specific parameter applicability (e.g., 'snapshot=v4 unlocks spike_window...', 'store_type has NO effect on dimension=advertisers'), default behaviors (page size 20, default page cost), and nuances like 'limit is ignored for geo_timeline'. It also clarifies parameter interactions (e.g., date_basis to reproduce site numbers, min_growth compared to site default). This enriches the schema substantially.

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: 'Get aggregated trend rankings for a dimension' and enumerates the dimensions (geo, geo_timeline, advertisers, webmasters, apps, timeline, scaling, domains). It explicitly distinguishes from siblings, e.g., 'Use for rankings/aggregates, NOT to list individual ads (use search_ads)' and 'Rows never carry media URLs... fetch the asset with get_media'. This makes the tool's role unmistakable.

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?

Clear usage context is provided: it says when to use (rankings/aggregates) and when not to (listing individual ads, use search_ads; fetching media, use get_media). It also advises on concurrency: 'Issue heavy calls sequentially; light lookups... are not gated.' It even notes dimension-specific choices like 'For BRANDS use domains' and 'For creative trends use scaling'. This goes beyond minimal guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds genuinely non-obvious behavior: 'This call is FREE — it consumes no quota,' plus the auto-refund billing nuance. No contradiction with 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?

The main purpose is front-loaded in the first sentence, and the token-cost tariff is genuinely useful context for cost-aware calling. It loses a point because ~100 words of billing detail appear as one dense unformatted paragraph for a tool with no parameters; light structure (bullets or separation of quota semantics from tariffs) would improve digestibility.

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 0-parameter, read-only tool with a full annotations set and an output schema available, the description is complete: it names the returned fields (plan, tokens used, remaining, limit), explains the plan tiers, and discloses that the call itself costs nothing. 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?

The tool has zero parameters and schema_description_coverage is 100% (it's an empty object), so the baseline of 4 for 0-parameter tools applies. The description appropriately does not fabricate parameter details; there is nothing more to add 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 states a specific verb+resource: 'Return the caller's current MCP quota: plan, tokens used, remaining and limit.' The quota resource is clearly distinct from all ~20 sibling tools, which target ads, webmasters, creatives, shops, trends, or favorites, so an agent can tell this tool apart without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to call it — to see the current plan, token count, and limits — and it emphasizes the call is free, which is exactly the information an agent needs before making costly searches. There is no sibling quota tool, so explicit 'when-not-to-use' instructions or alternative names would add little; a small deduction for not explicitly stating when to prefer it.

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 readOnly/openWorld/non-destructive, but the description adds substantial behavioral context: top_creatives ordering semantics, total_ads interpretation as market-wide family size, analytics_pending meaning, fanpages_status nuance, strict UUID rejection, TikTok token cost and Pro-plan requirement, and edge-weighting caveats for attribution merge edges. No contradiction with annotations exists.

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 long but densely packed, with every sentence carrying a distinct operational warning or semantic clarification. It is front-loaded with the core purpose and uses recognizable labels like QUOTA and TIKTOK to structure auxiliary details. Nothing reads as filler or tautology.

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 tool with intricate output semantics, the description is remarkably complete: it explains ambiguous fields, quota costs, plan requirements, source variants, and interpretation pitfalls. The presence of an output schema covers the raw return shape, while the description covers the semantics that the schema cannot express.

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 value beyond the schema by explaining that id must be the canonical UUID from search_webmasters and that domain names/display names are rejected. Source semantics are already in the schema enum description, so the added parameter insight is limited but meaningful.

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 opens with a specific verb and resource: 'Fetch a single webmaster (affiliate NETWORK) by UUID: aggregate stats PLUS top_creatives'. It clearly identifies what the tool returns and distinguishes it from sibling search tools by emphasizing single-entity retrieval by canonical UUID. The TikTok variant is also explicitly differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit routing guidance: use this tool for a single webmaster card, use search_creatives/search_ads for the rest of the network, and get_media for downloading creatives. It also states a hard precondition: the id must be the canonical UUID from search_webmasters, with domain/display names rejected. This leaves no ambiguity about when to invoke this tool versus alternatives.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, and the description adds meaningful specifics: normalized values, only facets with at least one other match, and FREE. This goes beyond what annotations communicate without contradicting them.

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 three concise sentences with the core purpose front-loaded and no filler. Every sentence adds information: what is returned, what similarity means, and the inclusion filter.

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 simple one-parameter, read-only tool with a rich output schema and strong annotations, the description covers purpose, scope, filtering behavior, and constraints. Nothing critical is missing for invoking 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% and the only parameter's description already says it is the source webmaster UUID from search_webmasters. The tool description adds no additional parameter semantics, matching the baseline for high schema coverage.

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 uses a specific verb ('List') and a concrete resource ('URL-parameter keys and normalized values') and clarifies that similarity means shared affiliate/tracking parameter values, not name or domain similarity. This distinguishes the tool from similarity-oriented siblings such as find_similar_webmasters.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: use it to get URL-parameter facets for related webmasters, and explicitly excludes name/domain similarity. It doesn't name a sibling alternative like find_similar_webmasters or state a when-not condition beyond the similarity definition, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and nondestructive behavior; the description adds quota info ('FREE — does not consume quota') and explains the different item representations returned per folder type (ids, hub profiles, domains). No contradiction with 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?

The description is dense but not bloated: it states the return shape, both parameter modes, the recommended use, and the quota effect in about four sentences. Every sentence carries operational value.

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 output schema and rich annotations, the description still adds enough to call the tool confidently: return fields for the folder list, exact item-return behavior for the folder parameter, how to disambiguate duplicate names, and quota impact. No important operational gap remains.

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 both parameters fully; the description largely restates the same mode information and even the disambiguation caveat ('pass entity_type to disambiguate') that appears in the schema. It adds a little value by tying ids to get_creative/get_webmaster/get_ad, but does not substantially extend 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 opens with a specific verb and resource, 'List the caller's favourites folders (name, entity_type, item_count)', and then clarifies the two modes: folder listing and folder contents. It also names the related tool add_to_favorites, so an agent can see how this read operation fits.

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 instructions about when to omit entity_type (all folders), when to pass it (filter), and when to pass folder (return items). It also states the purpose: 'Use this to confirm what add_to_favorites saved and to read a folder back.' It does not mention explicit exclusions, but no sibling tool overlaps directly with favourites.

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 cover read-only/open-world safety, but the description adds extensive behavior beyond them: per-row token billing (1 vs 100 for TikTok), the 40,000/month cap, Pro-plan gating with refund/partial-delivery semantics, exact vs estimated vs unavailable count contracts, the 'unavailable is not zero, re-issue' rule, and the most_reused_creative group-total omission.

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?

It is front-loaded with the return-shape constraint and routing, but it is extremely long and repetitive — the token/quota model and the TikTok premium are re-explained multiple times, and the filter list duplicates the schema. For a 45-parameter tool some length is warranted, but the verbosity costs readability.

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 45 parameters, no required params, an existing output schema, and a complex billing/counting contract, the description covers everything an agent needs: filters, sorting, pagination, exact-count windows, plan restrictions, and TikTok-specific shape and cost. Nothing essential is omitted.

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 such as 'use landing_domain — NOT query' for domain lookups and the category-vs-trends semantics. However, much of the per-filter detail (keyword, status_today, ranges) merely restates schema-documented parameters, so it does not rise far above 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 (search) and resource (the spytrend.com ad database) and immediately scopes what is returned (ad METADATA, not ad text). It distinguishes itself from siblings by naming get_ad for text, get_media for creative download, get_trends for aggregates, and get_advertiser/get_webmaster for entity counts.

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 routing rules are given for nearly every alternative: use get_ad for ad text, get_media for downloadable creative, add_to_favorites to save, get_trends for rankings, and do NOT paginate search_ads for advertiser totals. It also warns which date axis to use (date_from/date_to vs first_seen_from) and when not to cross-compare category totals with get_trends.

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 description goes far beyond the minimal readOnlyHint=true and destructiveHint=false. It discloses quotas, rate limits (60/min, 1000/hr), concurrency gating for 'heavy' calls, free-plan archive window restrictions, and the meaning of pagination.total_status='restricted'. It even explains that a zero means 'nothing in the archive window', preventing misinterpretation. No contradiction with 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?

The description is long but deliberately front-loaded: first sentence states the core purpose, then immediately differentiates alternatives, then dives into quota/rate-limit/concurrency details. Every section serves a real decision the agent faces. While dense, it avoids redundancy and earns its length given the tool's operational complexity.

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 tool with quota, rate limits, concurrency gates, and a free-plan special case, the description covers every conceivable decision point: how to size pages, what errors look like, how to connect an unlinked agent, and what happens when the archive window shrinks. The existence of an output schema means return-value details need not be spelled out. Nothing essential 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 both parameters are already described in schema. The description adds actionable details beyond schema: query must be ≥2 chars, a link in any form resolves to canonical fanpage with exact match first, limit defaults to 20 but is clamped to 50 upstream (not rejected). These are value-add semantics, not just repetition.

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 opens with a clear verb+resource ('Search advertisers') and specifies exactly the three input forms accepted (name, numeric page id, or pasted link). It explicitly distinguishes itself from siblings: get_advertiser for one full card, search_ads for ads, get_trends for rankings. No ambiguity remains about what this tool does.

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 versus alternatives is given: 'To fetch ONE advertiser's full card by id use get_advertiser; to see an advertiser's ads, call search_ads with advertiser_id. For advertiser RANKINGS, ordering and filters ... use get_trends with dimension=advertisers.' It also explains when to expect restricted results and how to handle them. This is textbook usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description goes substantially further: full quota model (1 token per delivered result, short pages refunded, 50 tokens per multilang ad opening, 10 per catalogue item, billed separately), period parity contract, axis contract, rejection-before-charge guarantees, and empty-page semantics. This is rich beyond what annotations provide, though the density borders on documentation-level rather than concise 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 description is dense and largely front-loaded with the meta-only scoping and sibling routing first, which is good. However, it is extremely long for a tool description, with duplicated contract material (PERIOD PARITY CONTRACT and AXIS CONTRACT restate much of what is already in the schema descriptions for period_from/period_to, sort_by, and last_seen fields). Several sentences repeat concepts already covered by the schema, reducing signal density.

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 34 parameters, 100% schema coverage, an output schema, and rich annotations, the description is more than complete—it covers quota semantics, period parity, axis semantics, and rejection behavior that the structured fields alone would not convey. It arguably over-delivers on completeness at the expense of conciseness, but nothing an agent needs to invoke 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 schema already documents all 34 parameters in depth, establishing a baseline of 3. The description adds meaning beyond the schema by grouping filters, clarifying cross-parameter interactions (country cannot combine with hub_category or channel; advertiser_ids supersedes advertiser_id; period_from requires period_to), and explaining sort_semantics for slices—all of which exceed the schema's per-field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (search/browse creative families), scopes it to source=meta, and explicitly differentiates from the sibling search_ads for TikTok callers. An agent can distinguish this tool from all 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 names when to use this tool vs search_ads (TikTok callers must use search_ads with dedupe=true), names get_media for downloading and add_to_favorites for saving. It also states when NOT to combine filters (country + hub_category or channel) and gives routing guidance for related tasks.

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 state readOnly/open/destructive hints, and the description goes far beyond: token pricing (catalog free, 1 token per delivered profile), free-plan restricted totals with meta.plan_window_cutoff semantics, quota tiers (500 lifetime / 40k monthly with auto-refund), rate limits with structured error.code=rate_limit_exceeded, concurrency admission (one heavy analytical call at a time), and autonomous-agent auth requirements with refusal behavior. An agent literally knows the failure modes and costs before calling.

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 genuinely long (a dense wall of text), but it is front-loaded — the first two sentences carry purpose and call modal, and sections are clearly marked with caps headers. The tool is complex (13 optional params, two modes, auth, billing, rate-limit, concurrency, free-plan constraints), so the length is mostly earned. It loses a point for writing style: the crammed prose would read better as bullets; the token-cost and quota paragraphs are best with tight formatting.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter, 0-required, complex tool, the description covers everything an agent needs: both modes, which params apply to which mode, free/paid quotas, restricted-window semantics, rate limits, concurrency policy, auth refusal behavior, paging defaults, and even examples. The output schema exists, so not delineating return fields is acceptable. There is almost nothing left for an agent to discover through costly trial-and-error.

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 is unusually detailed, so the baseline is 3. The description adds strategic meaning beyond the schema: it connects parameters into usage recipes (country+relevance+exclude_cloaking to surface storefronts), explains the catalog-vs-profile split that determines which parameter groups apply, clarifies sort=active 'hot now' semantics, and explains the pricing consequence of limit. This is real additive value rather than schema restatement.

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: 'Explore HUBS where ads send traffic, grouped by destination', enumerates the categories (Social Media, App Stores, Amazon, E-commerce, Popular, Platforms), and distinguishes the two call modes (catalog vs hub drill-in). It clearly separates this tool from sibling search tools like search_ads and search_advertisers by anchoring on destination grouping rather than ad/campaign or individual objects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-call scenarios: 'Call WITHOUT hub to get the catalog', 'Call WITH hub set to a slug to drill into', an example recipe ('combine country + sort=relevance + exclude_cloaking for a per-geo ranking of real storefronts'), and clear when-not guidance ('window is a no-op', 'a category slug is rejected'). It stops short of naming sibling tools as alternatives or explicitly stating 'use search_ads instead when...', so it gets a 4 rather than 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?

Beyond annotations (readOnlyHint=true, destructiveHint=false), the description discloses many behavioral nuances: visits is a monthly estimate not live, traffic_paid_share is only trustworthy under a condition, growth filtering has precise qualification rules, created_from/to refer to registrable root not first-seen, fb_signal is correlation-only, sort_by=relevance requires ai_category, pagination total_status can be 'restricted', quota per delivered result, concurrency gating, and autonomous-agent linking requirements. This far exceeds the annotation baseline.

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 long but tightly packed with critical information. It is front-loaded with the core definition, then details, then operational constraints (quota, rate limits, concurrency). Every section earns its place; the length is justified by the tool's complexity (40 parameters, multiple data-quality caveats). Minor redundancy (e.g., some parameter semantics repeated in the schema) means it could be trimmed slightly, but it remains well-structured.

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 tool's complexity, the description covers all essential aspects for correct invocation: output pagination (total, has_more, offset), free-plan behavior, quota accounting, rate limit details, concurrency admission, and relationship to related tools. The output schema presumably handles field-level documentation, and the description complements it with interpretive guidance. 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?

The schema has 100% parameter description coverage, yet the description adds essential global semantics not fully captured by individual parameter descriptions: e.g., the interpretation of visits_growth_pct as percent and its qualification rules, the meaning of traffic_start_max as max of preceding two complete months, the caveat about category vs ai_category, and the trust condition for traffic_paid_share. It also explains the interaction between parameters (e.g., min_growth and sort_by=growth). This adds significant value 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 precisely that the tool searches domain-level traffic surfaces with commerce and advertising intelligence, and clarifies the unit of analysis (domain/subdomain, not necessarily company/product). It clearly distinguishes from siblings like get_shop (full payload) and search_ads/search_creatives. The core purpose is unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: use get_shop for the full source payload, and notes that heavy analytical tools (get_trends, search_ads, search_creatives) are concurrency-gated while this tool is not heavy. It also explains quota semantics, rate limits, and when free-plan restrictions apply. This gives clear selection and operational context.

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 cover the safety profile (readOnly/openWorld/non-destructive); the description adds the operationally decisive facts an agent cannot get elsewhere — per-row token cost, 100x TikTok premium, auto-refunds, plan window cutoffs (total_status=restricted), rate-limit error codes, per-account concurrency admission for heavy calls, and the linked-account auth requirement with its refusal shape. This is exactly the beyond-annotations context the dimension rewards.

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 correctly (definition, then workflow, then cost/auth), but the TikTok block is heavily verbose and repeats cost/plan/refund mechanics already implied earlier, and the message runs very long for a search tool. Much is justified by the paid TikTok corpus and 28 params, but there is clear redundancy that dilutes signal.

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 28-parameter open-world search with a complex paid corpus and output schema present, the description covers selection, cost, auth, concurrency, plan-window semantics and lifecycle caveats. An output schema exists so return-value detail is not required, and the description still flags what the row payload contains. Nothing an agent needs to call it safely is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3, but the description adds cross-cutting meaning: min_geo_share as a dominance gate rather than a presence match, sort_by=relevance requiring countries, and source=tiktok rejecting Meta-only filters before charging. It does not, however, touch many of the 28 params (folder_id, saved, languages, platforms) 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?

Opens with a specific verb+resource and immediately disambiguates the domain concept ('a webmaster is a whole ad NETWORK — landing domains, pixels, pages and geos grouped as one'), which is essential since 'webmaster' is not self-evident. It also names the sibling workflow steps (search_creatives/search_ads, get_webmaster) so an agent can place it among alternatives without opening schemas.

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 workflow ('search by domain, take the canonical UUID, then search_creatives/search_ads with webmaster_id'), names alternatives for reuse analysis (get_webmaster.top_creatives or search_creatives sort_by=total_ads), and states the conditional recipe for geo ranking (countries + min_geo_share + sort_by=relevance). TikTok-vs-Meta routing is spelled out with what is accepted and rejected in each corpus.

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