RivalSweeper Signals

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

The annotations already declare this a safe, idempotent read, so the bar is lower, and the description still adds real behavioral context: it is free/non-billable, freshness is per-signal, price freshness includes the share of priced products read in the last 7 days, and large catalogs are sampled with records_approximate flagged. That sampling caveat in particular is behavior an agent could otherwise misread as incomplete data.

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 correctly, but the middle sentences are densely nested parentheticals ('records counts products, each product once however many variant rows it has; for large catalogs these come from a sample and are marked records_approximate') that require re-reading. The information is worth keeping, but the packaging is heavier than needed.

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

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

With no output schema, the description has to convey the return shape, and it does: per-signal availability plus freshness, record counts with an approximation flag, and the definition of 'available'. What it lacks is any sense of the full signal list or what a negative result means for the agent's next step, which keeps it short of a 5.

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?

There is a single parameter with 100% schema description coverage ('eCommerce domain, e.g. gymshark.com'), so the schema already carries the semantics. The description adds no format, normalization, or failure guidance for the domain argument (e.g. what happens on an untracked domain), so baseline 3 applies.

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

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

States a specific verb and resource ('Check which competitive signals RivalSweeper has for an eCommerce domain') and makes the scope explicit: this is a coverage/pre-flight probe, not a data fetch. The clause 'A signal is available exactly when its tool has data' ties it to the sibling tools it gates, so an agent can separate it from get_brand_price_statistics or get_active_promotions_and_coupons.

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 implies the intended workflow by mapping signals to the tools that return them ('promotions counts the live offers get_active_promotions_and_coupons returns, prices follow get_brand_price_statistics'), and 'Free and non-billable' is a useful selection lever. However, it never states outright when to call this versus those tools (e.g. 'call this first to confirm data exists before spending a billable call'), leaving the agent to infer the ordering.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it details what is returned ('full ad text, links, landing check and product read'), notes that some ads 'could not be checked,' and explains the default scope. This helps the agent understand the tool's output and limitations.

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 one dense sentence but front-loads the core purpose ('Ad & Deal Health, untrimmed') and then enumerates conditions and outputs. It is appropriately sized for the tool's complexity, though the run-on structure could be slightly more readable.

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 no output schema, the description adequately explains return values ('full ad text, links, landing check and product read') and scope (own store vs. rival). Annotations cover safety, and the single parameter is documented. The description is nearly complete, though it could clarify what 'landing check' entails.

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 description already explains that 'domain' is for 'One brand domain from your account; omit for your own store.' The tool description adds a mild clarification ('or one named rival'), but mostly reinforces the schema. Baseline 3 is appropriate when the schema carries the parameter documentation.

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) and resource (live ads with broken pages, expired offers, etc.), and lists the exact conditions checked. This clearly distinguishes it from sibling ad-overview tools like get_cross_channel_ads_overview, which do not focus on health checks.

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 implies usage by saying 'Checks your own store by default, or one named rival,' which clarifies scope but does not explicitly state when to use this tool versus alternatives. No sibling tools are named or excluded, leaving the agent to infer the appropriate 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 already declare read-only, idempotent, open-world, non-destructive behavior. The description adds useful context beyond that: the data is 'last-known' and 'freshness-stamped,' it costs 2 credits for developer API keys with no charge when no data is returned, and it includes the brand's own DNA profile.

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

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

Three tightly packed sentences: purpose and return contents first, then freshness, then billing. No sentence is filler.

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

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

For a simple one-parameter read tool with rich annotations and a fully documented schema, the description covers purpose, return fields, freshness, and billing. It is slightly incomplete on prerequisites, such as whether the brand must already be tracked before competitors are available.

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% for the single 'domain' parameter, and the schema already gives an example. The description says the data is 'for a domain' but adds no format or edge-case semantics beyond the schema.

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

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

The description states a specific resource (DNA competitor set: closest competing brands for a domain) and lists the returned fields, so the agent knows exactly what it retrieves. It does not explicitly contrast with competitor-related siblings like get_competitor_moves_feed or get_brand_radar_assortment_gaps, which keeps it from a 5.

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

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

There is no guidance on when to use this tool versus alternatives such as check_brand_data_coverage, request_new_brand_monitoring, or the other competitor-analysis tools. The billing sentence is pricing context, not 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 readOnly, idempotent, non-destructive, and openWorld behavior. The description adds meaningful context beyond annotations: it excludes expired and single-use codes, explains per-row verification provenance (seen_on_brand_homepage vs third_party_unverified), notes freshness stamping, and describes credit billing with no charge when no data is returned.

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 return fields, followed by filtering, provenance, freshness, and billing details. It is dense but structured, though the billing parenthetical is slightly tangential for an agent selecting the tool.

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

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

No output schema is present, so the description usefully names return fields (code, discount, terms, valid_until) and explains provenance and freshness. Annotations cover safety and idempotency, and the single parameter is fully documented by the schema; only minor domain-format and result-shape details are absent.

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

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

Schema coverage is 100% for the single domain parameter, already described as "eCommerce domain". The description does not add format details, examples, or semantics beyond what the schema provides, so the baseline 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?

The description states a specific resource and scope: active promotions/discount codes for a brand, with named fields (code, discount, terms, valid_until). It implicitly distinguishes itself from sibling analytics tools like get_discount_frequency_and_depth by focusing on live coupon codes rather than discount trends, though it does not explicitly name alternatives.

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

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

Usage is implied by "Active promotions/discount codes for a brand" and the exclusion of expired/single-use offers, but there is no explicit when-to-use guidance, no mention of when not to use it, and no named sibling alternative such as get_discount_frequency_and_depth or get_most_discounted_products.

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, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds genuinely useful context the annotations don't: credit cost for developer API keys and the 'no data = no charge' billing rule, plus a note that the data is uniquely RivalSweeper. It does not describe output shape beyond 'tier and highlights'.

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

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

Two sentences, front-loaded with the core purpose and pillar breakdown. The billing/credit clause is relevant but slightly dilutes the core message; overall it is efficient with little 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?

For a single-parameter read tool with no output schema, the description is fairly complete: it names the pillars and mentions the returned tier and highlights. It does not detail the full return structure, but annotations cover the safety profile, leaving only minor gaps.

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% with a single 'domain' parameter, so the schema already documents the input. The description adds no syntax, format, or normalization details beyond what the schema provides, matching the baseline of 3 when the schema does the heavy lifting.

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

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

States a specific verb+resource: an AI/agent-readiness score for a domain, and enumerates the six pillars (schema.org, technical access, content quality, trust, AI-specific, entity recognition). This is distinguishable from siblings like get_ai_model_citation_rate or get_how_ai_models_describe_brand, though the description never explicitly names those alternatives.

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

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

There is no when-to-use guidance or mention of alternatives among the many sibling tools. The only contextual information is plan/billing-related ('included in RivalSweeper plans', '1 credit'), which addresses cost rather than when this tool is the right choice.

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, idempotentHint, destructiveHint=false), so the bar is lower, yet the description adds real behavioral context: it discloses what is included (rate by model and platform, recent examples) and, importantly, what is excluded (own prompt-generation queries are not citation tests). That inclusion/exclusion disclosure is genuinely useful and not derivable from 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 purpose and the primary distinction are front-loaded, and every clause carries meaning. It is dense with nested parentheticals, which slightly impedes parsing, but no sentence is filler.

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

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

With no output schema, the description carries the burden of describing return content, and it does so by naming the rate, the model/platform breakdown, and recent examples. It is largely complete for a read-only metric tool; only the domains parameter behavior is left unaddressed.

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?

There is one optional parameter (domains) with 100% schema description coverage, so the schema already fully documents it. The description never mentions the domains filter or how omitting it affects results, so it adds nothing beyond the schema; baseline 3 is appropriate.

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

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

The description states a specific verb and resource: whether AI models mention each brand in answers, with a clear breakdown by question kind (brand_named vs unbranded). It clearly conveys what the tool returns, though it never names or distinguishes itself from the closely related sibling get_how_ai_models_describe_brand, leaving that differentiation to inference.

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

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

The description explains the semantics of the two question categories, which implicitly tells the agent what each slice is useful for (brand awareness vs recommendation test). However, it provides no explicit when-to-use guidance and does not route the agent toward or away from alternatives like get_how_ai_models_describe_brand.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered by structured data. The description adds real content value by enumerating what the report contains (which stores succeeded, where agents got stuck, KPIs, findings), but it says nothing about freshness guarantees, result format, or size.

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

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

A single sentence that front-loads the resource identity ('RivalSweeper's weekly race of AI shopping agents') before the colon-delimited contents list. Dense but free of filler, though the trailing list is slightly loose.

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

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

For a zero-parameter, read-only report tool with no output schema, the description does the essential job of telling the agent what the report will contain. Enough to decide whether to call it, with only minor gaps around cadence timing and result 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 tool takes zero parameters, so the baseline is 4; there is no parameter semantics for the description to clarify. No gap to compensate for.

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, distinctive resource: a weekly report of AI shopping agents attempting checkout across the user's store and rivals, covering completion, failure points, KPIs, and findings. This is clearly separable from AI-focused siblings like get_ai_agent_readiness_score or get_ai_model_citation_rate, though it never explicitly contrasts itself with them.

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 word 'weekly' implies a recurring report cadence, but there is no guidance on when to reach for this tool versus alternatives, no prerequisites, and no exclusions. The agent must infer its own selection criteria from the resource label alone.

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, so the bar is lower; the description still adds real value by defining freshness (when a price was last read), the 7-day read share, median read time, and a staleness flag for catalogs. It also discloses cost behavior (1 credit, no data = no charge), which is useful context not present in 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?

Front-loaded with the core purpose, then freshness semantics, then billing. Dense but each clause carries information; the billing aside is slightly tangential but short.

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

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

With no output schema, the description does the heavy lifting on return values and largely succeeds: it enumerates the statistics, the sample payload, and the freshness fields. Only the shape of individual product samples remains unspecified.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description reinforces that `query` is an optional product-name filter and that `limit` governs the sample, but adds no format or edge-case detail beyond the schema.

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

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

States a specific verb+resource: price statistics (min/max/avg/median) plus recent product samples for a brand, with an optional name filter. It is clearly distinguishable from price-adjacent siblings like get_most_discounted_products or get_discount_frequency_and_depth, though it never explicitly names an alternative.

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

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

'Optionally filtered by product-name query' implies use, but there is no explicit when-to-use/when-not guidance against the many other pricing and catalog siblings. The plan/credit sentence is billing context, not selection 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 readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuine context beyond them: the weekly refresh cadence, the per-brand dimensions returned, and the 'returns no data for single-brand stores' edge case, which is exactly the kind of behavior an agent cannot infer from 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?

Two sentences, front-loaded with the tool's identity and immediately followed by the eligibility constraint. The first sentence is a dense list of output dimensions, but every element is informative and nothing is redundant.

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

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

With no output schema, the description carries the return-value burden by enumerating white space, moat, depth gaps, price position and discount pressure. Parameter handling is trivial (one optional field, fully documented in schema), so the only remaining gap is not naming a fallback sibling for single-brand stores.

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?

There is one parameter (owned_domain) with 100% schema description coverage, so the schema fully documents it as 'your own store domain, if you have more than one.' The description adds nothing about when or how to supply it, so the baseline 3 applies.

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

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

States a specific resource and scope: 'Weekly Brand Radar for your store vs rivals' covering white space, moat, depth gaps, price position and discount pressure per brand. It is clearly distinct from sibling analyses like get_brand_swot_analysis or get_full_brand_snapshot, though it never names an alternative directly.

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 audience condition and a hard exclusion: 'For multi-brand retailers; returns no data for single-brand stores.' That is strong when-not guidance, but it does not point to which sibling to use when the exclusion applies.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld behavior, so the safety profile is covered. The description adds the useful behavioral detail that results reflect change over time, but it says nothing about the time window, freshness, or coverage limits of the analysis.

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

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

A single front-loaded sentence naming the source, the resource, the temporal scope, and the four output components, with no filler. Every clause earns its place.

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

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

For a simple single-parameter read tool with annotations covering safety and no output schema, the description conveys what is returned (S/W/O/T plus change over time). It could say more about the time horizon or whether the brand must be monitored, but it is otherwise sufficient.

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?

There is one parameter and schema description coverage is 100% — the schema already explains that 'domain' is a brand domain from the RivalSweeper account with an example. The description adds no format or sourcing detail beyond that, so the baseline 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?

The description names a specific resource (SWOT analysis of a brand) plus a scope qualifier ('over time') and enumerates the four dimensions returned, which distinguishes it from sibling analysis tools like get_full_brand_snapshot or get_brand_price_statistics. It never explicitly contrasts itself with a sibling, so it falls short of a 5.

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

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

There is no guidance on when to choose this tool over alternatives such as get_full_brand_snapshot, no stated preconditions (e.g. that the brand must already be tracked in the account), and no exclusions. Usage is only inferable from the resource 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context of its own — no indication of cost, latency, rate limits, or freshness of the analysis.

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

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

A single front-loaded sentence with no filler or repetition. It is appropriately sized, though it stops short of the detail a 5 would require.

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

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

With no output schema, the description does partially cover return content by naming assortment, categories, and pricing structure, which is the minimum needed to call it. However it omits when to choose it and any sense of output shape or depth, leaving real gaps.

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

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

Schema description coverage is 100% and the single required 'domain' parameter is fully documented in the schema with an example. The description contributes nothing beyond that, so the baseline 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?

The description names the specific resource (a brand's product catalog) and enumerates its scope (assortment, categories, pricing structure), which distinguishes it from siblings like get_product_page_analysis and get_homepage_analysis. It lacks an explicit verb, but the retrieved content is 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?

There is no guidance on when to use this tool versus the many adjacent catalog/price siblings such as get_brand_price_statistics, get_most_discounted_products, or get_product_page_analysis. The agent must infer the use case from the name alone.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds useful ordering ('newest first') and default timeframe context, but does not describe pagination, response shape, rate limits, or auth expectations.

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 core purpose is front-loaded and the single paragraph stays reasonably tight. The long enumeration of change types is dense but useful for scoping, though it makes the sentence harder to parse.

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 feed tool with no output schema, the description should explain the returned item structure or pagination more clearly than it does. It adequately lists covered categories but leaves response shape and sibling routing ambiguous.

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 only 33%; the description explains the default days window but says nothing about the limit parameter, and domains is already described in the schema. It does not compensate for the undocumented limit 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 clearly states that this returns a newest-first feed of what tracked rivals changed, and it enumerates the change categories covered. It does not differentiate this feed from similar siblings such as get_significant_competitor_changes or get_predicted_competitor_moves.

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 only a default lookback of 7 days and does not explain when to use this feed versus the closely related competitor-change siblings. There are no exclusions, prerequisites, or selection guidance for days, limit, or domains.

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, openWorldHint, and destructiveHint=false, so safety is covered. The description adds that the response is 'Full data, nothing trimmed' and includes prioritized insights with suggested actions, but it omits operational details such as response size caveats, auth requirements, or rate limits.

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

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

The purpose is front-loaded, but the remainder is a dense run-on list of data categories rather than structured sections. Most listed items are relevant for a no-output-schema overview, but the single long sentence and trailing 'Full data, nothing trimmed' reduce scanability.

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 annotations cover the operation profile and the schema fully documents the single optional parameter, the description's main job is to convey return scope. It does so by enumerating included ads metrics and insights, though it does not describe output organization or how brand-vs-rival comparisons are structured.

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?

There is one optional 'domains' parameter, and schema coverage is 100%; the schema already explains domain filtering and the default all tracked brands behavior. The description does not add any further meaning about the parameter, so the high-coverage baseline 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?

The description names a specific resource ('cross-channel ads picture') and enumerates its scope: live/new ads, reach, channel mix, 12-week launches, Google country matrix, Meta placement concentration. The 'cross-channel' and 'overview' framing implicitly separates it from single-channel siblings like get_google_ads_shopping_targeting_and_creatives and get_meta_ads_reach_messages_and_landing_pages, though it does not name them.

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 is provided. It does not point to the detailed Google/Meta ad tools as alternatives or clarify whether this is for a first-pass overview versus deep dives, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds only what the analysis contains, with no disclosure of data freshness, review volume, coverage window, or rate limits — useful but not rich behavioral context.

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

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

A single tight sentence with the resource and its outputs front-loaded and zero filler. It is efficient, though as a bare noun phrase it lacks the structure of an explicit 'use this to...' statement.

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 one-parameter read-only tool with full annotations and no output schema, the description is minimally sufficient: it signals the returned content (themes, sentiment, praise, complaints). It still omits any hint of output format or when the analysis is the right choice over sibling analyses, leaving a small gap given the absence of an output schema.

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

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

Schema description coverage is 100% for the single 'domain' parameter, and the schema itself gives an example (gymshark.com). The description adds no syntax, format, or constraint detail beyond that, so the schema carries the load and the baseline 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?

The description names a specific resource (a brand's customer reviews) and enumerates what the analysis covers (recurring themes, sentiment, praise, complaints), so the agent knows exactly what it gets. It does not, however, distinguish itself from adjacent siblings like get_brand_swot_analysis or get_social_media_channels_and_followers, which could also touch on customer opinion.

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

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

There is no statement of when to call this tool, what prerequisite (a tracked brand domain) is needed, or which sibling to prefer for related questions. Usage is only inferable from the name and the one-sentence content summary.

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, and open-world behavior. The description adds valuable context beyond those annotations: it discloses the 'not_measured' state when no capture exists, explains that results are limited to one store and currency per brand, and notes that homepage banners and product markdowns are independent signals. It does not cover rate limits or auth, but against the annotation baseline this is solid 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 definition is a dense but front-loaded paragraph that immediately states what the tool does, then defines the two readings. Every sentence contributes semantic content. It could be slightly more scannable with structure, but it avoids 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?

With no output schema and safety behavior covered by annotations, the description does a good job defining both output readings, the measurement caveat ('not_measured'), and the store/currency constraint. It does not explain the exact response shape or ordering, leaving a small gap, but an agent has enough 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 description coverage is 50%. The 'days' parameter has only min/max in the schema, but the description adds the default (30) and the 7–365 range, which is useful. The 'domains' parameter is documented in the schema but not mentioned in the description. The description adds some value but does not compensate fully for the half of schema coverage that is missing.

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: 'How often and how deep each brand discounts, over a window.' The two-metric framing (homepage banner vs product markdowns) makes the tool's purpose distinct. However, it does not explicitly name a sibling tool or contrast itself with one, so it falls short of the top score for sibling differentiation.

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 no guidance on when to use this tool versus alternatives. It never mentions sibling tools like get_most_discounted_products or get_active_promotions_and_coupons, nor does it state exclusions or prerequisites. The agent must infer applicability solely from the metric definitions.

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, openWorldHint and non-destructive, so the safety profile is covered structurally. The description adds useful provenance ('from RivalSweeper's newsletter tracking') and scopes the output facets, but says nothing about coverage gaps, freshness, or behavior for untracked brands.

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

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

A single efficient sentence with no filler, and the key content (what patterns are returned) is front-loaded. It is a noun phrase rather than a full declarative statement, which is slightly less clear but not wasteful.

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

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

There is no output schema, so the description carries the return-value burden; it does reasonably well by naming cadence, send times, themes and offers. However, it omits the required domain input, subscription/tracking prerequisites, and how empty results are signaled, which matters for an open-world data-lookup 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?

With a single required parameter and 100% schema description coverage, the schema already explains that 'domain' is a brand domain from the user's RivalSweeper account. The description adds nothing beyond this, so the baseline 3 applies.

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

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

The description names the resource (a brand's email newsletter) and enumerates the specific facets returned: cadence, send times, themes and offers. It is clearly distinguishable from sibling tools like get_social_media_channels_and_followers or get_upcoming_events_news_and_activity. It lacks an explicit verb, but the tool name and content make the intent 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?

There is no guidance on when to use this tool versus alternatives, no mention that a tracked brand domain is required, and no pointer to check_brand_data_coverage for brands lacking newsletter data. The agent must infer applicability entirely.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description adds genuinely new operational context not available in structured fields: the credit cost for developer API keys (15 credits) and the no-data-no-charge billing behavior. It still doesn't disclose response size or latency for what is obviously a large aggregate payload.

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

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

Two compact sentences with the bundle contents front-loaded; little waste. 'Included in RivalSweeper plans' leans commercial rather than operational, but it carries real entitlement information, so it 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?

With no output schema, the description correctly compensates by enumerating what the bundle returns (promotions, price stats with samples, AI-readiness). For a composite tool this is close to sufficient, though it doesn't indicate how broad 'all current signals' is relative to the ~30 sibling signals, leaving payload expectations somewhat open.

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 a single documented parameter, so the baseline is 3. The description adds only the framing that domain maps to a 'one brand-day' scope, which faintly implies a date dimension the schema does not actually expose, but contributes no format or validation detail beyond the schema.

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

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

The description names the resource concretely — a bundle of all current signals for one brand-day — and enumerates the contents (promotions, price stats + samples, AI-readiness). That distinguishes it from the many single-signal siblings like get_brand_price_statistics and get_active_promotions_and_coupons, though it never explicitly frames itself as the aggregate alternative to them.

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 phrase 'in one call' implies the intended use case (avoid many round-trips for a single brand), but there is no explicit when-to-use or when-not-to-use guidance relative to the individual signal tools. No prerequisites, freshness constraints, or exclusions are stated.

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, so the safety profile is covered. The description still adds real behavior: creatives are returned only when exactly one brand is named, 200 per page, creatives_offset pages forward, and `total` reports the count — useful pagination disclosure not 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 first sentence is a dense, comma-spliced inventory ('all topics, where ads show, reach, alerts, advertiser accounts') with marketing phrasing like 'untrimmed' that spends words without narrowing meaning. The second half about per-brand creatives and paging is tighter and better front-loaded by contrast.

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

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

With no output schema, the description does hint at return content (`total`, 200-item creative pages) and tells the agent the brand limit and the one-brand condition. For a read-only, zero-required-param tool this is close to complete, though it never describes the overall response shape or what happens when domains is omitted beyond 'your own store plus first tracked rivals'.

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 country, domains, and creatives_offset, including the 'name exactly one to include creatives' note. The description largely restates that conditional rather than adding syntax, ordering, or default behavior beyond it, so baseline 3 applies.

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

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

The description enumerates the specific resource scope: the Google Ads tab, your brand vs rivals, covering Shopping, targeting, freshness, reach, and creatives. It is clearly distinct from the Meta-ads and cross-channel siblings by naming the Google Ads surface, though it lacks a crisp verb and reads as a feature list rather than a single stated action.

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 implies usage ('for your brand vs rivals', 'Up to 6 brands per call') and states a conditional rule for creatives, but never says when to pick this over get_cross_channel_ads_overview or get_meta_ads_reach_messages_and_landing_pages, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, covering the safety profile. The description adds scope context (what the analysis assesses) but says nothing about data freshness, latency, or coverage requirements. With annotations carrying the behavioral load, this is adequate.

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

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

A single tight sentence that front-loads the resource and then enumerates the three analytical dimensions. No filler or redundancy, though the lack of any usage clause means it is efficient rather than maximally informative.

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 read-only, single-param tool with full annotation coverage, the description is roughly sufficient, and it indirectly hints at the return content. However, with no output schema, it could be clearer about what fields or format the analysis returns, leaving a modest gap.

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

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

There is a single parameter and schema description coverage is 100%; the schema documents 'domain' with an example ('gymshark.com'). The description adds no parameter-level detail beyond the schema, so the baseline 3 for high-coverage schemas applies.

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

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

The description names a specific verb+resource ('analysis of a brand's homepage') and enumerates the content it covers: features/emphasis, offers/messaging, and competitive comparison. This meaningfully separates it from siblings like get_homepage_top_links or get_homepage_product_shelf_and_markdowns, though it never names those siblings explicitly.

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

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

There is no when-to-use or when-not-to-use guidance. Given several homepage-scoped siblings (get_homepage_top_links, get_homepage_product_shelf_and_markdowns) and broader tools (get_full_brand_snapshot), the agent is left to infer which to pick, with no routing help provided.

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, so the safety profile is fully covered. The description adds useful domain semantics, defining persistence as share of observed days and listing the posture metrics (slots, best position). It does not address result shape, aggregation level per brand, or coverage limits beyond the schema's 'omit for all tracked brands'.

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

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

The purpose is front-loaded, but it is delivered as one long run-on sentence with nested parentheses and a trailing fragment about the window, which is harder to parse than a short structured lead plus details. Every element carries information, so nothing is wasted, but the structure could be cleaner.

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 2-parameter, no-output-schema read tool, the description conveys the metrics returned and the scoping default. Only the response granularity (one row per brand? per product per day?) and any limits/pagination remain ambiguous.

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 only 50% schema description coverage, the description compensates well by giving the default window (90 days) and reinforcing the 7-365 range for the otherwise undocumented 'days' parameter. The 'domains' behavior is already documented in the schema. Minor gap: no explanation of how the window affects the persistence calculation.

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 concretely specifies the resource and the computed metrics: homepage product persistence (share of observed days), slots, best position, price/currency/markdown and featured categories. An agent can understand what data comes back. It stops short of naming sibling tools (e.g. get_homepage_analysis, get_homepage_top_links) to differentiate scope.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no alternatives are referenced, even though several homepage-related siblings exist. Only an implicit framing ('a read on what brands are pushing') hints at the use case.

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, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the top-level 'comment' flag when pricing/stock is not captured, and the credit/charging semantics (2 credits, no data = no charge).

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-loads the purpose, then the grouping, then per-link fields, then caveats and cost. The long field enumeration is dense but earns its place because no output schema exists; no filler sentences.

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

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

With no output schema, the description carries return-value disclosure itself: group order, per-link fields (title, vendor, price, currency, stock, URL status, rating, position, anchor text, update), and the comment caveat. An agent has enough to invoke and interpret 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?

Only one parameter (domain) and schema description coverage is 100%, with the example 'connox.com' already in the schema. The description adds no syntax or format information beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('A brand's current homepage top links') and quantifies scope (up to 10) plus how results are grouped (Products, Categories, Content). An agent can tell it returns links, not an analysis. It does not explicitly distinguish itself from close siblings like get_homepage_analysis or get_homepage_product_shelf_and_markdowns, which keeps it from a 5.

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

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

The description explains what is returned and the billing model but gives no when-to-use/when-not guidance and never names an alternative tool. For a niche homepage endpoint with several homepage-adjacent siblings, the routing guidance is a clear gap.

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, so safety is covered. The description adds genuinely new context not in structured fields: the data source is sampled from Google Gemini and OpenAI's open-weight GPT-OSS models, which shapes how a consumer should interpret the results. It stops short of disclosing freshness, sampling size, or rate limits.

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?

One dense sentence plus a short sourcing sentence; front-loaded and mostly waste-free. Enumerating all seven aspect values duplicates the schema enum, which is the only mild bloat.

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

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

With no output schema, the description never indicates what the response contains (per-aspect text? scores? sources?) beyond the aspect names. For a read-only analytical tool this is acceptable but leaves a real gap in knowing what comes back.

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 aspect enum is fully documented in the schema, so the description's restatement of the seven aspect values is redundant. It adds nothing about the domain parameter or how aspect values differ semantically. Baseline 3 applies.

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

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

States a specific verb+resource: how LLMs describe a brand when asked shopping questions, broken out by aspect. The domain/aspect framing distinguishes it from near-siblings like get_ai_model_citation_rate or get_ai_agent_readiness_score, though it never names those alternatives directly.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives among the many AI-visibility tools (citation rate, readiness score, shopping agent checkout race). Usage must be inferred from the aspect list.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds genuine behavioral context by disclosing that output includes deltas versus the last check, but says nothing about freshness/lag, rate limits, or account requirements.

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

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

A single dense sentence with zero filler, front-loaded with the returned fields and ending on the interpretive payoff. It is slightly overloaded with comma-separated clauses but every clause contributes information.

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

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

There is no output schema, so the description carries the burden of describing returns and does so reasonably well: role breakdowns, change vs last check, top titles, and added/removed jobs. For a single optional-parameter read tool, that is close to complete, though it omits default time window and result limits.

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 sole parameter (domains) is already fully documented with an example and omit-for-all behavior. The description does not mention the parameter at all, so it adds nothing beyond the schema — baseline 3 applies.

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

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

The description names the resource precisely (open roles per brand, broken out by department and location, plus job-title and add/remove deltas) and frames it as a competitive-investment signal. It is clearly distinguishable from siblings, none of which cover hiring. It stops short of a clean verb-first statement like 'List job openings', but the content is 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 trailing clause 'an early read on where a rival is investing' implies when the tool is useful, but there is no explicit when-to-use/when-not guidance and no alternative sibling is named. An agent can infer intent but gets no routing instructions or prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds useful context: 'untrimmed' signals no filtering, 'UK/EU only' specifies geographic scope for reach data, and 'Up to 6 brands per call' clarifies a capacity limit. However, it omits any mention of response size or performance, which is only found in the schema.

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

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

The description is a single, massively dense run-on sentence that lists every possible data point without structure. It is not front-loaded; the core meaning is buried in a long enumeration. It would benefit greatly from bullet points or shorter sentences to improve readability and 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 (many sections, 2 parameters, no output schema), the description covers what data is returned in exhaustive detail. However, it lacks guidance on how to use the sections parameter to manage large responses (that guidance is only in the schema) and provides no structural cues. It is adequate but not fully 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?

Schema description coverage is 100%, so both parameters (domains and sections) are fully documented in the schema. The description adds little beyond reinforcing 'Up to 6 brands per call' and implying all sections are returned by default with 'untrimmed'. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description specifies a clear verb and resource: it returns everything on the app's Meta Ads tab for brands vs rivals, untrimmed. It distinguishes itself from siblings like get_cross_channel_ads_overview or get_google_ads_shopping_targeting_and_creatives by focusing exclusively on Meta Ads data with a comprehensive scope.

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 offers no explicit guidance on when to use this tool versus alternatives. It implies usage by stating 'untrimmed' and 'Up to 6 brands per call', but never says when to choose it over other ad-related tools or when to avoid it (e.g., for lighter queries).

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 read-only, idempotent, non-destructive annotations already establish the safety profile, and the description adds useful context that results are current discounts with price, full price, and discount fields. However, it does not clarify freshness/source, limits, or behavior across multiple brand domains beyond what annotations and schema imply.

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 efficiently packed sentence with the core purpose and return fields front-loaded. Every clause contributes either sorting behavior or output 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?

With no output schema, the description usefully names the returned fields: price, full price, and discount. Combined with rich schema coverage and clear read-only annotations, this is nearly complete for a simple listing tool, though it could better explain multi-domain behavior and default limits.

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 sort, limit, and domains, including defaults and bounds. The description reinforces the sort modes (percent, amount, newest) but adds no syntax or semantic detail beyond the schema.

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

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

The description gives a specific resource and operation: a brand's most-discounted products, with sort modes for percent, amount, or newest discounts. It is clear what data is returned, but it does not explicitly distinguish itself from sibling discount-analysis tools such as get_discount_frequency_and_depth.

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 implies the tool is for retrieving current top discounts but gives no explicit when-to-use guidance, prerequisites, or comparison to overlapping siblings. An agent must infer that this is the product-level listing tool rather than the discount-analysis 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, closed-world), so the description's value is in what it adds: the default pending filter and the shape of each record (priority, status, owner, due date). It does not mention pagination or the 100-item cap implied by the limit parameter, which is the main remaining gap.

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?

One front-loaded sentence names the resource, parenthetical examples clarify intent, and a short trailing clause states the default. No filler, though the examples and the field list make it slightly denser than the minimum needed.

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 read-only list tool with no output schema, the description compensates by enumerating the returned fields and the default filter. The only meaningful omission is the result-count behavior controlled by limit, which leaves an agent guessing about paging.

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 50%: the status parameter is documented with its default enum list, while limit (1-100) is undocumented in both schema and description. The description's 'Default: pending items' mostly restates the status default already in the schema and adds no syntax or cap information for 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 names a specific resource (action items RivalSweeper raised for your team) and concretizes it with two examples (fix a broken ad landing page, respond to a rival promotion). It implicitly separates itself from data-inspection siblings like get_competitor_moves_feed by framing these as assigned team to-dos, though it never names an alternative explicitly.

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?

'Default: pending items' tells the agent what it gets without arguments, which is genuine usage context, but there is no guidance on when to call this versus the many sibling analysis tools, and no stated exclusions or prerequisites.

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

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

Annotations already establish readOnly/idempotent/non-destructive/closed-world, so the bar is lower. The description adds genuine value beyond them: the tool is free, it is scoped strictly to the caller's own data ('only ever returns your own usage'), and it explains the two consumption models (plan-based vs. prepaid API credit) and the look-back window. It stops short of describing return structure or freshness, so not a 5.

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

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

Three tight sentences, front-loaded with the core purpose and scoping statement. Dense with facts and no filler, though the API-key clause is slightly compressed and could be marginally clearer with a touch more structure.

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

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

With no output schema, the description carries the return-value burden and does so fully by enumerating what the caller gets back for both signed-in and API-key modes. Combined with annotations covering the safety profile and a fully documented parameter, nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single 'days' parameter is already documented in the schema with its default (30) and bounds. The description restates the look-back window and default but adds no syntax or behavior beyond that, so baseline 3 applies.

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

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

States a specific verb+resource ('Your own account status') and enumerates exactly what it returns: plan, tool calls used vs. plan limit, queryable domains, and for API-key users the prepaid balance and per-tool call/credit consumption. Clearly distinguishes itself from the brand-analysis siblings, none of which touch account state.

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 makes the use case unmistakable (check plan, quota, and domain access) and notes it is 'Free; only ever returns your own usage,' which signals when it is appropriate. No explicit when-not or named alternative is given, but no sibling tool serves this purpose, so the guidance is effectively complete.

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 the read-only/idempotent/open-world profile, and the description still adds substantial non-obvious behavior: variant URLs are folded into their parent product, size/colour-only additions are labelled, first_seen is RivalSweeper's detection time not the brand's publish date, per-brand counts precede items, and pages from a brand's first tracking days are excluded. These are exactly the caveats 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?

One front-loaded paragraph that opens with the resource and scope before piling on caveats; almost no wasted words. It is dense, with several distinct facts compressed into semicolon-separated clauses, which slightly hurts scanability but does not waste space.

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

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

With no output schema, the description carries the return-shape burden and does so: item fields (tags as names, first_seen, sitemap_lastmod), per-brand counts appearing first, and the labelling of variant-only additions are all described. Combined with the annotations, an agent has everything needed to call and interpret 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?

Schema coverage is only 33% — only `domains` is documented in the schema — but the description compensates by supplying the default and cap behavior for the other two ('Default last 7 days, up to 50 items (max 200)'), which maps directly onto `days` and `limit`. It does not spell out the 90-day ceiling on `days` or the 50-domain cap, so it falls just short of fully covering the gap.

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

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

States a precise verb + resource + scope: products and pages RivalSweeper *first found* on tracked brands' sites within the last N days, with ordering (newest first, interleaved across brands). This is clearly distinct from siblings like get_most_discounted_products or get_significant_competitor_changes, since the novelty/recency basis of selection is explicit.

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

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

Usage context is implied rather than stated: the defaults (last 7 days, 50 items, max 200) tell the agent how to call it cheaply, but there is no explicit 'use this when…' clause and no sibling tool is named as an alternative or fallback. An agent can infer the use case from the resource definition, but must do the routing work itself.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety bar is low. The description adds real context beyond them: cards are weekly, are predictions rather than confirmed events, and each carries a rationale, a dated suggested move, and dated evidence, so the agent knows to treat output as probabilistic advice.

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

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

Two sentences, front-loaded with the resource and cadence, then the card contents. No filler, and the enumeration of card fields earns its space by describing the return shape.

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

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

With no output schema, the description carries the return-value burden and does so well by listing the card anatomy (why, suggested move with date, receipts/article links). Minor gaps remain: freshness/latency of the weekly refresh and whether predictions are scoped to any date window are unstated.

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?

Zero parameters, so the baseline is 4. The description does usefully clarify that scope is fixed to every tracked rival with no filtering, which is the only semantic question a parameterless call raises.

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

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

States a specific verb and resource: weekly prediction cards per tracked rival, explicitly forward-looking ('what is coming up', 'suggested move with its date'). An agent can distinguish it in spirit from the backward-looking get_competitor_moves_feed, but the description never names that sibling, so the differentiation is implicit rather than stated.

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

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

The reference to 'the Predictions page' and the split between what just happened versus what is coming implies when to reach for it, but there is no explicit when/when-not and no named alternative. An agent must infer that get_competitor_moves_feed covers raw recent moves while this covers predictions.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the analysis dimensions, but does not disclose depth, freshness, or whether the brand must already be tracked in the account.

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

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

A single front-loaded sentence that identifies the analysis subject first and the coverage dimensions second. No filler, though the parenthetical list is dense rather than purely economical.

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

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

There is no output schema, so the description partially compensates by naming what the analysis covers. However, it says nothing about the return structure, depth, or prerequisites for a domain, leaving an agent with an incomplete picture of what it will receive.

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

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

Only one parameter, and schema description coverage is 100% – the schema already explains that 'domain' is a brand domain from the RivalSweeper account with an example. The description adds nothing about the parameter, so baseline 3 applies.

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

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

States the resource (product pages) and enumerates the analyzed dimensions (content, imagery, trust signals, offers, cross-sell), which is far more specific than a tautology. It implicitly separates itself from get_homepage_analysis and get_catalog_analysis by scoping to product pages, but never names those siblings explicitly.

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 when-to-use guidance and no alternatives referenced. An agent choosing between this, get_homepage_analysis, and get_catalog_analysis gets no routing signal beyond the phrase 'product pages'.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds genuinely new context: the >10% threshold that defines 'significant', the chronological alert-feed shape with summary, entitlement via RivalSweeper plans, and the billing rule (2 credits, no data = no charge). Those are facts the agent cannot derive from annotations or schema. It does not mention rate limits or auth mechanics beyond plan inclusion.

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

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

Three tight sentences, front-loaded with the qualifying thresholds, then return shape, then window and billing. Nothing is redundant, though the plan/credit sentence is commercial metadata rather than invocation-relevant 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 two-parameter read tool with no output schema, the description supplies the alert-feed return shape, the significance thresholds, and the look-back window bounds. The main remaining gap is disambiguation from the near-identical moves/predictions siblings.

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 'domain' (with example) and 'days' (min 1, max 90, default 7). The description restates the window range and default without adding format or semantics beyond it. Baseline 3 applies when the schema carries the parameter burden.

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?

Names a specific resource (significant competitor changes) and enumerates exactly what qualifies: price moves >10%, new promotions, stock-status flips. That threshold specificity makes the tool's output scope unambiguous. It stops short of naming how it differs from the closely-related siblings get_competitor_moves_feed and get_predicted_competitor_moves, so it is clear but not fully 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 says what the tool surfaces but never states when to reach for it instead of get_competitor_moves_feed, get_predicted_competitor_moves, or get_discount_frequency_and_depth. The only 'guidance' is the window parameter and plan/credit notes, which are availability facts rather than usage routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the field list: no data freshness, no coverage caveats, no indication of what 'posting cadence' means operationally.

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?

One short, front-loaded sentence with zero filler. It is efficient, though the telegraphic fragment style leaves no room for the usage or behavioral cues that would make it more actionable.

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, one-optional-param tool with no output schema, the description is minimally sufficient: it enumerates the returned entity types. It stops short of explaining what the caller gets per channel (handles, counts, cadence granularity), which is the main remaining gap.

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

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

There is a single optional parameter and schema description coverage is 100%, with the schema already explaining the domain format and the omit-for-all behavior. The description contributes nothing about the parameter, so the baseline 3 applies.

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

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

The description names the resource and its fields precisely: social channels, followers, and posting cadence per brand. It is a noun phrase rather than a verb+resource statement, and it does not differentiate itself from look-alike siblings such as get_email_newsletter_insights or get_cross_channel_ads_overview, but an agent can still tell what data comes back.

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

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

There is no when-to-use or when-not-to-use guidance. Nothing tells the agent how this differs from the newsletter, cross-channel ads, or full brand snapshot tools, and the only scoping hint (omit domains for all tracked brands) lives in the schema, not the description.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world behavior. The description adds useful behavioral context beyond annotations: technology categories and ordering, separate social-profile links, default 40 per brand, max 200, and that omitted counts are reported.

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 follows with output composition and limits. The long category enumeration is dense but earns its place by clarifying coverage; minor repetition around 'per brand' keeps it from a 5.

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

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

With no output schema, the description carries the burden of explaining return structure, and it does so by listing categories, separating social links, and stating per-brand caps and omitted counts. It is nearly complete for an agent to call the tool correctly, though it could say more about domain scoping behavior.

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

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

Schema coverage is 100%, so parameter documentation is already strong. The description adds meaning to max_per_brand by stating the default 40, maximum 200, and that excess technologies are counted rather than listed, though it does not elaborate on the domains parameter 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?

States a specific verb+resource: it retrieves the technology stack each brand runs, with category ordering and social links separated. It is clear what the tool returns, though it does not explicitly differentiate itself from sibling tools such as get_full_brand_snapshot or get_homepage_analysis.

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

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

The description explains output shape and limits but gives no explicit guidance on when to use this tool versus alternatives. The schema notes that domains can be omitted for all tracked brands, but the description itself does not route the agent among siblings.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior, so the safety profile is covered. The description adds useful context beyond them — the 7-day news window and the country/per-brand scoping — but says nothing about return format, volume, or freshness of the non-news buckets.

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

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

A single sentence, front-loaded with the 'dashboard agenda' framing and then listing the three components in parallel. No wasted clauses, though the run-on structure packs three distinct features into one breath.

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

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

For a zero-required-param aggregation tool with no output schema, the description adequately conveys what content comes back. The main omission is any sense of response shape or relative freshness across the three buckets, which an agent would otherwise need to learn by calling it.

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

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

Schema coverage is 100%; the domains parameter is fully documented in the schema, including the omit-for-all-brands behavior. The description reinforces the per-brand scope but adds no syntax or format detail beyond what the schema provides, so baseline 3 applies.

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

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

Names three concrete content buckets — upcoming holidays/retail events by shipping country, news mentions (7 days), and recent catalog activity per brand — which is far more specific than the title alone. It does not, however, distinguish itself from related siblings such as get_competitor_moves_feed or get_significant_competitor_changes, so an agent must infer the boundary.

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?

'Your dashboard agenda' hints that this is an overview/aggregation call, but there is no explicit when-to-use guidance, no prerequisites, and no alternative named. With ~30 sibling analytics tools, the absence of any routing advice is a real gap.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds one genuinely useful behavioral fact: the returned brands are the domains this connector can answer for, i.e., the coverage boundary. It says nothing about ordering, pagination, or what 'status' values mean.

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

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

A single sentence that front-loads the resource and contains no filler. The trailing colon-chained clause 'with status: the domains this connector can answer for' is slightly ambiguous in what it attaches to.

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

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

With no output schema, the description carries the burden of explaining return values, and it only gestures at them: 'status' is left undefined and the shape of each entry is unstated. Adequate for a trivial zero-parameter read, but not 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?

Zero parameters, so the baseline is 4. The description adds a little about what comes back (brands, own vs rival, status, answerable domains) without any parameter semantics to clarify.

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 resource: the brands in your RivalSweeper account, split into your own site(s) and monitored rival brands. It implicitly distinguishes itself from siblings like check_brand_data_coverage and find_closest_competitor_brands by being the account-level inventory, though it never names those alternatives.

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

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

There is no explicit when-to-use guidance and no routing to alternatives among the ~36 sibling tools. The phrase 'the domains this connector can answer for' faintly implies the tool is a scope-discovery step, but the agent must infer that.

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

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

Annotations already declare this is a non-read-only, open-world, non-idempotent, but non-destructive write. The description adds useful context beyond that: the request is 'Free and non-billable' and collection is prioritized 'based on demand,' implying asynchronous handling. It does not explain what the immediate response looks like or how the agent learns when the signal becomes available.

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

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

Three short sentences, front-loaded with the core action, followed by the usage condition and the cost/prioritization note. Every sentence carries distinct information and there is 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 simple three-parameter submission tool with full schema coverage and helpful annotations, the description covers purpose, when to use it, cost, and the demand-driven collection model. It could be more complete by noting that no data is returned immediately or how the requester will be notified, but the essential calling context is present.

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 domain, signal, and note with examples. The description only restates 'exactly what signal you need for a domain' without adding format or validation guidance, so baseline 3 applies.

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

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

The description states a specific verb and resource: 'Tell RivalSweeper exactly what signal you need for a domain.' It makes clear this is a request-submission tool rather than a data-retrieval one, which distinguishes it from the many get_* siblings. It stops short of naming the most similar sibling (request_new_brand_monitoring) to sharpen the boundary.

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 an explicit when-to-use condition: 'For a signal that is missing for a domain or that RivalSweeper does not track yet.' That tells the agent to reach for it only when existing data tools cannot satisfy the need. It does not name alternatives or exclusions, so it falls short of a 5.

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

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

Annotations only tell the agent this is a non-read, non-idempotent, open-world write; the description adds the operation is asynchronous, discloses the differing latency paths (immediate/~24h vs queued/24-72h), and states permission (Admins only), quota (plan/trial limit), and billing (prepaid balance, free) preconditions. That is substantial behavior beyond the structured hints.

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 core action is front-loaded in the first sentence, and the two auth paths are packed into two dense sentences with no filler. Slightly telegraphic but every clause carries a distinct constraint.

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

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

With no output schema, the description usefully conveys the async/queued nature and timing, plus gating prerequisites. It stops short of describing what the call returns (e.g., a queued request identifier) or how to later confirm the domain was added, which is the remaining gap for a write 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?

There is a single parameter with 100% schema description coverage, so the baseline is 3. The description says 'rival domain' but adds no format guidance (subdomain, protocol, www handling), so it neither compensates for nor improves on 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 and resource ('Add a rival domain to monitoring'), which clearly separates this mutating tool from the surrounding read-only get_* siblings and from list_my_tracked_brands. An agent can identify the action without opening the schema.

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

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

It lays out the two invocation contexts explicitly: RivalSweeper sign-in (immediate add, company Admins only, plan/trial domain limit applies, ~24h to first data) versus Developer API keys (queued request, positive prepaid balance required, 24-72h). It does not name alternative tools or a when-not-to-use condition, 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.