Spytrend

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

Going well beyond the idempotentHint/destructiveHint=false annotations, the description discloses concrete behavioral traits: idempotency semantics (already_saved reported, never duplicated or re-charged), per-type token costs (1 token per ad, 10 per creative, free for webmaster/hub/shop), automatic folder creation with a stable dated fallback, and the required hub parameter when entity_type=hub. This materially helps an agent predict side effects and cost before invoking.

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

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

The purpose is front-loaded in the first sentence, and every sentence carries decision-relevant information: parameter mapping, conditional requirement, folder guidance, idempotency, and billing. It is a long single paragraph that could benefit from section breaks, but there is no 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?

An output schema is present, so return values need no explanation, and the description covers purpose, all parameters, the conditional hub requirement, idempotency, and billing. Nothing an agent needs to call this tool correctly is missing.

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

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

The input schema already documents all 4 parameters with 100% coverage, so the baseline is 3. The description adds value by linking ids provenance to the exact sibling search tools, clarifying the hub/entity_type dependency with an example, and tying entity_type to billing behavior. It is somewhat redundant with the already-thorough schema, so not a 5.

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 ('Save'), a clear resource ('a SELECTION of entities to one of the caller's favourites folders'), and the purpose ('so they can review them later on spytrend.com'). It also disambiguates all five entity_type values and ties each to its source search tool, making it clearly distinct from the read/search siblings like list_favorites and the 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?

It states the intended use case — saving entities surfaced by the search_* tools for later review — and adds practical guidance such as preferring a folder name from the user's search context and the billing implications per entity type. It does not explicitly name alternatives or exclusions (e.g., 'use list_favorites to view saved items'), so it stops 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 mark this as readOnly and non-destructive, and the description adds important behavioral context beyond those: the source ad is excluded from results, pagination.total reflects the upstream count before exclusion, metadata-only returns, and cursor pagination. No contradictions 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 every sentence earns its place: it defines the operation, disambiguates from a sibling, clarifies pagination semantics, and states quota. The key exclusion and alternative are 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?

With an output schema present, annotations covering safety, full parameter schema coverage, and the description covering pagination, exclusion behavior, quota, and alternative routing, the agent has everything needed to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the parameters are already fully documented in the schema. The description reinforces the meaning of basis and the 1-token-per-row quota but does not add substantial semantics beyond what the schema already provides.

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 ('Find ads related to'), resource ('one source ad'), and the overlap basis ('fanpage' or 'domain'). It explicitly distinguishes itself from find_similar_creatives, so an agent can differentiate between entity overlap and visual similarity without inspecting 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?

It gives explicit when-to-use guidance: entity overlap by fanpage or domain, and explicitly names the alternative ('use find_similar_creatives for that') for visual similarity. This makes the selection boundary 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?

Beyond the readOnly/openWorld annotations, it discloses the 20-candidate upstream cap, conservative has_more semantics, threshold_status vs result_status meaning, metadata-only output without media URLs, and per-row quota. This is substantial behavioral context that helps an agent predict side effects and limits. 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?

Four dense sentences that all earn their place: purpose, visual-similarity clarification, cap/has_more semantics, get_media routing, and quota. Front-loaded with the main verb and resource, with no filler.

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

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

For a read-only similarity search with 3 documented parameters and an output schema, the description covers the relevant edge cases (default vs explicit threshold, native cap, has_more behavior) and routing. Nothing an agent needs to call or interpret the result 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?

Input schema documentation covers all three parameters (100% coverage), including threshold's lower-is-stricter semantics and default. The description adds no substantive parameter-level detail beyond framing threshold as part of the production similarity index, 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: finding creatives visually similar to a source creative via the production similarity index. Explicitly differentiates visual similarity from exact creative membership, and the resource term 'creatives' distinguishes it from sibling tools for ads and 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?

Provides clear context that this is for visual look-alikes and explicitly says it is not exact membership, giving a when-not. It also points to get_media for media URLs. However, it does not explicitly compare against find_similar_ads or find_similar_webmasters, leaving some routing to the tool name.

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 readOnly/openWorld/destructive annotations, the description discloses determinism, the canonical 5000-result cap, result completeness fields (result_status/result_cap/total_status), and the token quota per delivered row. This gives an agent substantial behavioral expectations without contradiction.

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 efficiently organized: purpose first, workflow second, behavioral semantics third, quota last. Every sentence adds information and there is no filler or repetition of schema 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?

The description covers the prerequisite call, parameter selection, result ordering, cap behavior, completeness signals, and quota. Since an output schema exists, return-value details are not necessary, and nothing essential is missing for an agent to invoke the tool 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 meaningful context: param_key must come from get_webmaster_similarity_facets, values are an optional subset of normalized source values, and webmaster_id is the source webmaster. It also clarifies pagination/quota behavior tied to limit.

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: 'Find other webmasters sharing normalized URL-parameter values with a source webmaster.' It also names the matching mechanism (url_parameter_overlap) and differentiates from the sibling find_similar_ads/find_similar_creatives tools by explicitly targeting 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 an explicit workflow: first call get_webmaster_similarity_facets, then pass one returned param_key, and optionally narrow by values. This is clear contextual guidance for when and how to use the tool, though it does not state when-not-to-use alternatives or explicitly exclude sibling 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?

The description goes far beyond the readOnly/openWorld/destructive annotations by disclosing absence semantics for body and body_chars, permanent vs. expiring media URLs, and the TikTok billable-resource behavior. It explicitly warns against treating absent fields as zero and against putting expiring media into reports or exports. This is rich behavioral disclosure that genuinely helps an agent avoid misuse.

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 every sentence carries essential operational information: field availability, absent-field semantics, media URL permanence, expiring-link warnings, and quota distinctions. It front-loads the core purpose before diving into caveats, and no sentence is filler or redundant with the schema.

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

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

Given that output schema exists and annotations cover the read-only safety profile, the description supplies the remaining context an agent needs: exact response semantics, data-quality caveats, quota behavior, and how to handle the TikTok source variant. Nothing essential is missing for correctly selecting and invoking this tool.

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 covers both parameters with 100% coverage, so the baseline is 3. The description adds value by clarifying the quota implications of source=tiktok and by tying the tool's purpose to the media-delivery expectation. It does not add new meaning to the id parameter itself, but the source parameter is meaningfully enriched.

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 precise verb and resource: 'Fetch a single ad by its id with FULL details including its creative media,' then enumerates the specific fields returned. It also differentiates this tool from sibling media/search tools by stating that this is 'the only surface' that serves the full ad text, making its 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?

The description gives clear context about when to use this tool: when fetching a single ad by id and when full creative media and text are needed. It also provides practical guidance around TikTok source selection and quota costs, and warns against using expiring media links in reports. It does not explicitly name sibling alternatives or state exclude conditions, so it falls just 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 only state readOnly/openWorld/non-destructive, leaving the description to carry behavioral detail, and it does so richly. It discloses token costs per delivered row, refund behavior on pending/error, row limits and defaults, flattened output shape with dimension field, section readiness/truncation metadata, nullable totals with non-zero semantics, status-section filter behavior, and retry guidance. This is far beyond what annotations provide and contains no contradiction.

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 information-dense; every sentence conveys a distinct operational constraint or behavioral caveat. It front-loads the core purpose before layering cost, limits, null semantics, and exclusions. This is appropriate given the tool's 49-parameter surface and the many edge cases an agent must respect.

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 49 parameters, 100% schema coverage, an existing output schema, and read-only annotations, the description covers the critical non-obvious context: pricing, retries, null semantics, section-scope behavior, unsupported features, and auto-applied vertical metadata. An agent has everything needed to decide whether and how to call this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3 and the description is not required to restate all parameters. It does add useful context around output semantics and limits, such as default 10 rows and maximum 20, but this largely mirrors the max_items_per_section schema description. There is no meaningful per-parameter enrichment beyond what the schema already states.

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 names a specific verb and resource: "Get the bounded analytics overview for the current Meta /ads selection." It enumerates exactly which breakdowns are included (statuses, countries, AI categories, landing domains, advertisers, webmasters) and the key totals, making the tool's scope unmistakable. This clearly differentiates it from search or single-entity sibling 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 provides strong usage context: it targets the current Meta /ads selection, is a Pro-or-higher paid surface, and explicitly lists unsupported features such as pagination, sorting, source, scheduler, force-scrape, TikTok, raw SQL, and storage coordinates. It also instructs agents to re-issue identical calls after retry_after_seconds and not to blindly retry paid calls. It stops short of explicitly naming alternative tools and when to prefer them, so it does not fully earn 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, openWorldHint, and destructiveHint, and the description adds substantial behavioral detail beyond them: quota cost ('1 token'), exact vs. estimated count semantics, the AI-labeling caveat for category counters, and the top_creatives market-wide reuse contract. These are significant non-obvious behaviors that could change how an agent interprets results.

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 front-loaded with the core purpose and field list, then proceeds through essential contracts and caveats. It is quite long and dense, but nearly every sentence carries a necessary distinction or warning. Some redundancy and lack of paragraph breaks reduce readability, but there is minimal fluff.

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 presence of an output schema, and the low parameter count, the description is extremely complete. It covers id formats, quota, when to use alternatives, caveats about counts and categories, and the meaning of top_creatives totals. There is no obvious gap an agent would need to guess about.

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 only says 'the resource id to fetch', which is generic and unhelpful. The description compensates fully by explaining the id can be an advertiser UUID, a Facebook page id, a fanpage id, or a pasted facebook.com page link, and that page ids are auto-resolved to advertisers. This transforms a vague parameter into a precisely understood input.

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 advertiser's FULL card by id', and enumerates the exact fields included. It differentiates itself from search_ads by noting this is 'the cheap way to answer how many ads' and from get_media by directing creatives downloads there. This is a clear, distinguishing statement of purpose.

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 tells when to use this tool versus alternatives: use it for exact counts instead of 'paginating search_ads', use search_ads to list an advertiser's ads, and use get_media for downloading creatives. It also explains what kinds of IDs can be passed and that Facebook page links resolve automatically, giving an agent actionable selection criteria.

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 indicate readOnlyHint=true and destructiveHint=false, and the description substantially extends this with behavioral detail: canonical bounded breakdown, omission of the ambiguous legacy languages alias, copy_languages provenance and scope, breakdown status semantics, sorting/capping at 1000 rows, per-dimension status fields, and the explicit statement that this read never starts transcription. 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?

Although long, the description is front-loaded with the core purpose and every subsequent clause carries operational meaning: statuses, sorting, truncation, provenance, exclusions, and quota. There is no redundant filler or repetition of schema or annotation content.

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

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

For a single-parameter read tool with a full output schema, the description covers the essential context: how to obtain the id, what data is included and excluded, how to route to get_media, breakdown status conditions, quota cost, and behavioral guarantees like no transcription. Nothing critical is left unresolved.

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 only says id is 'the resource id to fetch,' while the description adds crucial meaning: it is a creative UUID from search_creatives, the same id used for get_media with entity_type=creo, and it selects a single creative. This is meaningful value beyond the schema's generic description.

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 ONE creative's metadata plus its canonical bounded breakdown by id.' It clearly distinguishes this from search_creatives by emphasizing a single id lookup rather than search, and it names the id provenance as a creative UUID from search_creatives.

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: it tells the agent to use get_media for media URLs with entity_type=creo and the same id, and states that fanpage ids feed the search_creatives fanpages filter and search_ads page_id. It also clarifies this tool never starts transcription, preventing misuse for transcript generation.

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 detail beyond the readOnly/destructive annotations: quota charges, retry of fallback_urls on stale blob coordinates, malformed UUIDs not consuming quota, duplicate_count billing behavior, and partial/interrupted item handling. This fully prepares the agent for real-world failures.

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 every sentence carries operational information. It uses clear labels like QUOTA and IMPORTANT, front-loads the core purpose, and organizes edge cases logically without repetition or filler.

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

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

For a tool with quota, paid delivery, fallback URLs, and partial-failure semantics, the description is remarkably complete. It covers success, malformed input, mixed batches, duplicates, quota exhaustion, stale URLs, and the recommended call flow, so an agent can invoke it correctly in nearly any scenario.

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 meaningful semantics beyond the schema, especially for ids: malformed UUIDs never reach the API or consume quota, valid peers in a mixed batch are still processed, and duplicates are fetched/billed once.

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: 'Fetch downloadable creative MEDIA (image/video URL + thumbnail)' for 1-500 ad or creative UUIDs. It clearly distinguishes from siblings like get_ad or get_creative by emphasizing the media delivery use case and the search_ads/search_creatives source.

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 typical flow 'search_ads → pick ids → get_media' and the explicit phrase 'This is the paid delivery step' give clear usage context. It does not explicitly name alternative tools to avoid, but the flow and media-specific wording effectively route an agent to the right 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 mark the tool read-only and non-destructive, but the description adds substantial field-level caveats: legacy traffic snapshot fields are not interchangeable, domain_created is registration date not launch date, ads_monthly marks open months incomplete, and fb_signal is correlation-only. It also discloses the QUOTA and warns that domains may be funnels/runtime pages rather than companies.

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 sentence is front-loaded with the action and resource, and every subsequent caveat earns its place. However, the description is one sprawling paragraph with lowercase continuations and run-on transitions, so it could be better structured without losing information.

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

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

For a single-object fetch tool, this is remarkably complete: the output schema covers structure, and the description provides non-obvious field semantics, provenance limitations, quota information, and a save-to-favorites workflow. Nothing essential for calling the tool correctly is missing.

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

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

The input schema already covers the domain parameter with 100% description coverage and a concrete example, so the baseline is met. The description adds extra meaning by warning that the domain/subdomain may be a funnel, runtime, blog, or redirect rather than a company/product, which is not present 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?

Main clause 'Fetch one domain surface's FULL profile' pairs a specific verb with a clear resource and scope. It is easily distinguishable from the sibling get_* tools because 'shop'/'domain surface' is explicit in the title and description.

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?

No explicit when-to-use or when-not-to-use guidance relative to siblings. It never mentions search_shops as the discovery step or get_advertiser/get_webmaster as alternatives; the only workflow hint is 'To save it use add_to_favorites', which is a next action, not a selection 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds substantial value on top: quota and token accounting, free-plan preview restrictions, rate-limit error codes, one-at-a-time concurrency admission, auth requirements for autonomous agents, and which dimensions return has_more vs. intentionally omit it. There is 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 description is front-loaded with the purpose and dimension selector, then logically organized into plan, quota, auth, rate-limit, and concurrency sections. It is extremely dense and useful for a 52-parameter tool, but it repeats the FREE PLAN COUNTS passage almost verbatim, which is an avoidable redundancy.

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

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

The description covers dimension row semantics, pagination semantics, free-plan limitations, quota accounting, rate limiting, concurrency, authentication, and even tells the agent that full field semantics arrive in meta.dimension_semantics. With an output schema present, nothing material is missing for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is already high, but the description still adds meaningful parameter-level guidance: dimension-specific filter behavior, site-mirroring defaults (date_basis=parsed, mode='exploding', min_growth=2), snapshot=long restrictions, and free-plan refusal semantics. This goes well beyond simply restating 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 ('Get aggregated trend rankings for a dimension') and then enumerates every dimension, including a one-line definition for each. It also explicitly contrasts the tool with search_ads, making its purpose unmistakable. The first sentence omits 'domains', but the later per-dimension list resolves that ambiguity.

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 says when to use the tool ('Use for rankings/aggregates') and when not to ('NOT to list individual ads (use search_ads)'). It also names sibling alternatives such as get_media and search_webmasters for specific follow-up actions, and explains free-plan versus paid-plan behavior with concrete pagination 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?

Beyond the annotations, the description discloses the key behavioral fact that the call consumes no quota, and it explains the broader cost model including auto-refund behavior for short pages. It also clarifies plan-specific limits, adding meaningful context not present in 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 information-dense but well organized, front-loading the core purpose before plan details and cost rules. Every sentence adds value: the plan breakdown, token costs, and the free-call note are all relevant to using the tool correctly.

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

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

With no parameters and an output schema present, the description fully covers the situational and behavioral context an agent needs: what the quota is, how plans differ, how token costs are computed, refund behavior, and that the call itself is free.

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 the schema is an empty object, so there is nothing for the description to document. The baseline of 4 applies because no parameter explanation is needed and the description doesn't mislead about parameters.

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

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

The description opens with a specific verb and resource: "Return the caller's current MCP quota." It enumerates the included fields (plan, tokens used, remaining, limit), making the tool's function unambiguous and distinct from sibling data-fetching 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 provides clear context: it explains plan variants, token costs, and that "This call is FREE." It doesn't explicitly name alternatives or exclusion criteria, but the tool is unique among siblings and its purpose is so evident that no alternative-routing is needed.

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 readOnly/openWorld/destructive hints: 1-token quota, 100-token TikTok cost, analytics_pending semantics, total_ads folding and flooring, fanpages_status lifecycle meaning, and merge-edge interpretation. These are exactly the non-obvious behaviors an agent needs to avoid misreading results.

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 it is information-dense and front-loaded: the core fetch behavior appears first, followed by warnings, field semantics, alternatives, and quota/TikTok caveats. Every sentence carries meaningful guidance; none is filler or repetition.

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 description is complete given the call's complexity and the presence of an output schema. It covers input constraints, token costs, plan requirements, open-world caveats, sensitive field interpretations, source-specific behavior, and sibling endpoints for extending the query. 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?

Although schema coverage is already 100%, the description enriches both parameters: id must be the canonical UUID from search_webmasters and domain/display names are rejected, while source=tiktok is explained as the business-id cluster card with Meta-only embeds omitted. This goes well beyond the schema's enum and type descriptions.

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

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

The description opens with a specific verb and resource: 'Fetch a single webmaster (affiliate NETWORK) by UUID.' It clearly defines the return focus — aggregate stats plus top_creatives — and explicitly distinguishes the canonical-UUID requirement from silent widening, which separates it from search-style 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?

The description gives explicit routing guidance: for the rest of the network use search_creatives?webmaster_id / search_ads?webmaster_id, and download media with get_media. It also defines when the TikTok variant applies and that it requires Pro or higher, leaving no ambiguity about when this tool should be selected.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior, so the description adds value by disclosing extra behaviors: only facets with at least one other webmaster match are returned, and the tool is FREE. It also clarifies the semantic scope of similarity, which is not present in annotations. No contradiction 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 compact and front-loaded, with the key verb and resource in the first sentence. Each subsequent sentence earns its place: the similarity definition, the match-filtering behavior, and the cost note. No filler or repetition.

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 one fully documented parameter, strong annotations, and an output schema present, the description covers the important non-schema context: what facets are, how similarity is defined, and that only matched facets are returned. An agent has enough information to select and invoke this tool correctly without confusion.

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 single parameter webmaster_id is already fully documented as 'source webmaster UUID from search_webmasters'. The description itself does not add significant parameter-level detail beyond the tool's overall purpose. This matches 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 clear resource ('URL-parameter keys and normalized values' / facets). It also actively disambiguates the meaning of similarity by stating it is about shared affiliate/tracking parameter values, not name or domain similarity. This clearly separates it from siblings like find_similar_webmasters and get_webmaster.

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 frames when to use the tool: to discover URL-parameter facets that can be used for finding related webmasters. It gives helpful context about what similarity means and that only facets with at least one other match are returned. It does not explicitly name alternatives or say when not to use it, but the use case is clear enough for an 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds useful behavioral context beyond them: the operation is caller-scoped, consumes no quota, and the return content differs by folder type. No contradiction exists between the description and 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 front-loaded with the primary purpose, then packs filtering, folder-item behavior, return shapes, a use-case, and quota information into a compact set of sentences. Every sentence earns its place and none are redundant with the schema.

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

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

The description covers the tool's scope, all parameter behaviors, return-shape differences, the intended use case, and quota impact. With an output schema present and no required parameters, an agent has everything needed to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters in detail. The description adds some interpretive context such as using returned ids with get_creative/get_webmaster/get_ad, but it largely restates what the schema already provides, so a baseline score of 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 uses a specific verb ('List') with a clear resource ('the caller's favourites folders') and explicitly explains the two modes: listing folders or listing items inside a named folder. It also distinguishes itself from add_to_favorites, its write counterpart, making the tool's role 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 gives explicit usage guidance: pass entity_type to filter, omit it to list across all types, and pass folder to read items. It also tells the agent when to use this tool — to confirm what add_to_favorites saved and to read a folder back — naming the sibling tool that performs the corresponding write.

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 indicate readOnly/openWorld/non-destructive, so the description carries the behavioral burden and fulfills it richly. It discloses the token-cost model (1 per Meta row, 100 per TikTok row), exact/estimated/unavailable count semantics, the 'unavailable is pending, not zero' rule, status_today's current-state interpretation, and the AI-labeled-subset caveat. 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 a single dense block with no section breaks, lists, or formatting, making it hard for an agent to scan quickly. It also repeats details already present in the input schema, such as formats, status_today values, and min/max body_chars semantics. While front-loaded with a clear purpose, its excessive length and lack of structure undermine its usability.

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

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

For a complex 45-parameter search tool, the description covers every operationally relevant area: filter semantics, pagination, exact-count windows, quota/token costs, status interpretations, TikTok-specific behavior, and unsupported-parameter rejections. Given that an output schema exists, not restating return shapes is acceptable; nothing critical 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 coverage is 100% with detailed per-parameter descriptions, so the baseline is 3. The description adds cross-parameter value by grouping filters, explaining the date_from vs. first_seen_from distinction, max_countries behavior with and without a selected GEO, and which parameters are honored or rejected on the TikTok source. However, much of the parameter-level detail already appears in the schema, so the increment above baseline is moderate.

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: 'Search the spytrend.com ad database' and explicitly enumerates the returned metadata fields (title, body_chars, landing domain, status, etc.). It also distinguishes itself from siblings by stating what it deliberately does not return (ad text, media) and pointing to get_ad and get_media for those needs.

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 rules: fetch ad text with get_ad, media with get_media, exact advertiser/webmaster counts with get_advertiser/get_webmaster, aggregate rankings with get_trends, and saving with add_to_favorites. It also warns not to use query for domain lookups and not to use first_seen_from/to for market newness, steering instead to landing_domain and date_from/date_to.

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 mark the call read-only and non-destructive, and the description goes much further: it discloses plan-window count restrictions, quota/token accounting, required account linking for autonomous agents, rate-limit refusal behavior, and one-at-a-time concurrency for heavy calls. These are exactly the behavioral traits an agent needs to avoid failed or expensive calls.

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?

Long but well labeled and front-loaded: core semantics and alternatives come first, then quotas, auth, rate limits, and concurrency. Some sections are dense enough to be hard to scan, but almost every sentence earns its place; only minor trimming would improve it.

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, authentication, rate-limit, and concurrency constraints, the description covers all operationally critical areas while the output schema covers return structure. The only completeness issue is the limit-range contradiction, but that is better attributed to parameter semantics.

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 covers both parameters at 100%, so the baseline is 3. The description adds useful cost semantics (1 token per delivered result; default 20) and query-form resolution, but it says limit is 1–200 while the schema says 1–50 with clamping, a conflicting instruction that makes the added semantic value partially unreliable.

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 action and resource: 'Search advertisers by NAME, numeric Facebook page id, or a pasted facebook.com page link', and specifies the typeahead behavior (query ≥2 chars) and primary returns (external_id, ad_count). It also clearly contrasts with search_ads and get_advertiser, so an agent can tell which tool is intended.

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 routes to alternatives: get_advertiser for one full card, search_ads for an advertiser's ads, and get_trends with dimension=advertisers for rankings, ordering, and filters. This is direct when-to-use vs when-not-to-use guidance with named sibling 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?

The description goes far beyond the readOnly/destructive annotations by disclosing quota semantics (1 token per delivered result, short-page auto-refund), metadata-only behavior, separate media billing, the period_axis contract, empty-page behavior, and rejection of invalid periods before upstream work. These are behavioral details not inferable from annotations alone.

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 operationally important information, and it is front-loaded with purpose then quota then contracts. However, it repeats the period_axis contract and last_seen/period definitions in multiple places, so it is not maximally 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?

For a complex 33-parameter tool with no required parameters and an output schema present, the description covers pricing, pagination, period semantics, aliases, sort behavior, slice semantics, error handling, and sibling routing. Nothing essential for correct invocation appears 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 already 100%, so the baseline is 3, but the description adds substantial meaning: last_seen vs period date semantics, date_from/date_to aliases, period_axis interpretation, slice.ads_in_slice ordering, min_geo_share's country requirement, and the closed-period auto-enablement of ads_in_period. This clearly exceeds 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 opens with a specific verb-resource pair: 'Browse and filter unique creative families and return metadata only.' It also explicitly distinguishes the tool from search_ads by stating that creatives have no free-text search and that search_ads is for discovery, which helps an agent tell siblings apart.

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 search_ads for free-text discovery, get_media for downloading media, and add_to_favorites for saving. It also advises requesting small limits and narrow filters instead of wide pagination, making the intended usage pattern clear.

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

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

Annotations only declare readOnlyHint/openWorldHint/destructiveHint; the description adds significant behavioral context: token costs, restricted archive counts, window no-op behavior, unlinked-agent refusal handling, rate-limit error codes, and concurrency admission limits. 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 front-loaded with the core purpose and call patterns, but it becomes a long rambling paragraph with repeated FREE/token reminders and extensive quota/rate-limit/concurrency details that could be summarized or bulleted. It is informative but 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?

Given the 13 parameters and already-rich schema, the description covers everything an agent needs: invocation modes, filter semantics, sort behavior, cost model, auth requirements, rate limits, error shapes, and concurrency guidance. The output schema being present means return-value details are not required here.

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 the token cost per delivered profile, the 1–200 limit range, the semantic difference between lifetime and currently-active sorts, and how to combine country, relevance, and exclude_cloaking to get meaningful per-geo rankings.

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 that search_hubs explores destination hubs where ads send traffic, and precisely distinguishes the two modes: without hub it returns the catalog, with hub it drills into destination profiles. This makes the tool's scope unambiguous relative to sibling 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?

It explicitly explains when to call without hub vs with hub, and gives a concrete recipe for per-geo storefront rankings (country + relevance + exclude_cloaking). However, it does not explicitly contrast search_hubs with sibling search_* tools or state when not to use 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 already cover the safety profile (readOnlyHint=true, openWorldHint=true, destructiveHint=false), so the bar is lower — yet the description goes far beyond: visits is a MONTHLY estimate, fetched_at is ingestion time, quality fields must gate judgment, paid_share trusts only when traffic_sources_available=true, growth rows require a qualifying cohort, category may be wrong, provenance of registration dates is not retained (ClickHouse row caveat), free-plan archive windows change what total reports, rate-limit refusal surfaces as structured error.code=rate_limit_exceeded, and concurrency gates heavy calls. Failure modes and data caveats are disclosed in unusual depth.

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 every sentence carries a substantive caveat or behavior — no obvious padding. It front-loads the core row/visits contract before quota, rate-limit, and concurrency details. The length is justified by 40 params, a token-cost model, and complex data semantics; it loses a point only because a wall of unheadered prose is harder for an agent to scan selectively than structured sections.

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 complexity — 40 loosely-coupled filters, quota accounting, plan-window restrictions, rate limits, concurrency, and data-quality caveats — the description covers nearly everything an agent needs: return shape (total/has_more/offset), pagination restriction semantics, token cost per delivered row including auto-refund, the unlinked-agent refusal mode, and the exact rate-limit error contract. An output schema exists, so return-value details are appropriately left to 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 coverage is 100%, giving a baseline of 3. The description adds interpretave semantics beyond the schema: it ties visits_growth_pct to the growth_qualified cohort conditions, ranks ai_category over category for ad-market discovery, and explains traffic_start_max's baseline of both preceding complete months with stale windows excluded. It doesn't fully compensate for the sheer number of params on its own, but genuinely elevates understanding of the key filter semantics.

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

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

The description opens with a specific verb and resource — 'Search domain-level traffic surfaces with commerce and advertising intelligence' — and immediately defines the row unit (DOMAIN/SUBDOMAIN) to prevent over-interpretation. This distinguishes it from siblings like search_ads, search_creatives, and search_advertisers, whose resources are different entities, and it explicitly points to get_shop for the full source payload.

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 alternative guidance is present: 'Use get_shop for the full source payload.' The concurrency paragraph also implies search_shops is not a gated heavy call (unlike get_trends, search_ads, search_creatives), and the quota/plan section gives clear cost-based context for calling it. It stops short of an explicit when-not-to-use list against the other search_* siblings, so a 4 rather than 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 mark the tool read-only and non-destructive, and the description goes far beyond that: it discloses token quotas and per-row costs, free-plan archive-window restrictions, per-user rate limits, one-at-a-time concurrency gating for heavy calls, current-membership matching semantics for exact lookups, and TikTok-specific row/charge behavior. No contradiction with the 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 well-organized with clear section markers (FREE PLAN COUNTS, QUOTA, CONCURRENCY, TIKTOK) and front-loads the core search workflow before edge cases. It is very long, though, and parts of the TikTok row-shape enumeration overlap what the output schema should already provide, so not every sentence earns its place.

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

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

For a 28-parameter tool with quota, rate-limit, concurrency, and dual-corpus behavior, the description is exceptionally complete: it covers cost per delivered row, archive-window count semantics, error shapes, upgrade refusals, TikTok-only filters, and how to paginate. An agent has everything needed to invoke this tool correctly without guessing.

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 every parameter, but the description adds meaning the schema cannot convey: min_geo_share is explained as a geo-relevance dominance gate, sort_by=relevance is tied to country ad-volume, source is priced and plan-gated, and boolean/count filters get interpretation warnings. This materially helps an agent choose correct parameter values.

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: 'Search webmasters (affiliates)', then defines a webmaster as an ad NETWORK. It also embeds the tool in an explicit downstream workflow ('search by domain, take the canonical UUID, then search_creatives/search_ads with webmaster_id'), which clearly distinguishes this search tool from sibling search/retrieval 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 gives concrete when-to-use guidance: search first, capture the canonical UUID, then pass webmaster_id to search_creatives/search_ads or get_webmaster.top_creatives. It also states when alternatives apply, distinguishes Meta vs TikTok corpus selection via source, and warns which filters are rejected for TikTok — explicit usage routing.

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