signals

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

Annotations already indicate a read-only, idempotent, non-destructive operation, and the description adds meaningful behavioral context: it is free and non-billable, requires the API key, returns only the caller's own data, and enumerates the exact metrics included (balance, call counts, credits, per-tool breakdown, lifetime spend). This goes well beyond the annotations.

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

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

The description is three sentences with no filler, front-loads the core purpose, and packs in the key qualifiers (free, non-billable, own usage only, default window, metric breakdown). Every sentence contributes useful information.

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

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

For a one-parameter, read-only tool with no output schema, the description is sufficiently complete: it names the returned data categories, the look-back window default, and the caller-scoping constraint. An agent can decide whether to call it and understand 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?

With schema description coverage at 100%, the schema already documents the single 'days' parameter including its range and default. The description only repeats the 30-day default without adding new semantic detail, so it meets the baseline but does not elevate it.

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 ('get') and a clear resource ('API usage & credit balance') and immediately distinguishes it from the sibling data tools by framing it as 'Your own account status' that 'only ever returns your own usage.' This leaves no ambiguity about what the tool returns.

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

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

The description makes clear the tool is for retrieving the caller's own usage and credit balance, and it adds practical guidance by noting it is free, non-billable, and requires an API key. It does not explicitly name alternative tools or state when not to use it, but the sibling pool is obviously different in subject matter, so this is a minor 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 convey readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds meaningful behavioral detail beyond annotations: the cost of 15 credits and the 'no data = no charge' policy, which clarifies what happens when the external world lacks data. This is useful context for an agent deciding to call the tool.

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, tight sentence that front-loads the core purpose ('Bundle') and enumerates contents, then appends cost and refund policy. Every clause is informative; there is no fluff or redundant phrasing. It is concise while conveying all essential information.

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

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

For a tool with one parameter and no output schema, the description lists the categories of data returned and notes the no-data charge policy, which covers a common failure scenario. However, it does not detail the response structure (e.g., whether it is a flat object or nested) or explain how the signals are organized. Given the tool's simplicity, this is a minor gap, and the description is otherwise sufficient for an agent to call it correctly.

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

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

Schema description coverage is 100% with the only parameter 'domain' described as 'eCommerce domain'. The tool description does not add any further meaning or examples for the parameter beyond what the schema already provides. Since the schema already documents the parameter, the description adds no incremental value, keeping the baseline score at 3.

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 it is a bundle of multiple signals (promotions, price stats + samples, AI-readiness) for a brand-day, distinguishing it from siblings like get_promotions and get_readiness_score which are single-purpose tools. The verb 'get' and resource 'brand snapshot' are specific and unambiguous.

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

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

The description implies this tool is used when you need all signals in one call (via the word 'Bundle'), but it does not explicitly state when to use it over individual siblings, nor does it mention any exclusions or alternative conditions. Usage context is only weakly implied, leaving the agent to infer from the word 'bundle' 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 indicate read-only, idempotent, non-destructive behavior. The description adds useful context beyond that: responses are freshness-stamped, the request costs 1 credit, and a no-result call is not charged. This goes beyond what annotations convey.

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

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

Two short sentences convey output contents, filtering, freshness, credit cost, and refund behavior. No filler or repetition; the most actionable information is front-loaded.

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

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

There is no output schema, so the description reasonably covers return content (statistics plus samples) and the freshness dimension. It does not mention ordering or sample limits, but the provided context plus schema is sufficient for typical use.

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

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

The input schema documents all parameters with 100% coverage, so the baseline is 3. The description reinforces query as product-name filtering and domain as brand context, but does not introduce significant new parameter-level meaning.

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, well-scoped function: retrieving price statistics (min/max/avg/median) and recent product samples for a brand, with an optional product-name filter. This makes the tool's purpose clear and distinguishable from siblings like get_competitor_top_urls or get_brand_snapshot.

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

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

The description provides clear context for when this tool is relevant — pricing data for a brand, optionally narrowed by product name. It does not explicitly compare against sibling tools, but the domain is specific enough that an agent can infer appropriate use.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the return composition, grouping order, the fallback comment for missing pricing/stock, per-link fields, and the no-data-no-charge billing rule. This gives the agent a very accurate model of what will happen.

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

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

The description is dense but every sentence conveys a distinct fact: scope, grouping order, output fields, caveat, and cost. It is front-loaded with the core purpose and avoids 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 one-parameter read-only tool with no output schema, the description supplies enough detail for an agent to invoke it correctly and interpret the returned data. It also covers edge cases such as missing fields and no-result charging.

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 single parameter, domain, is already fully described in the schema with an example. The tool description does not add additional parameter semantics, 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 clearly states the tool's function: retrieving a brand's homepage top links and grouping them into Products, Categories, and Content. It adds distinctive detail (up to 10 links, per-link fields) but does not explicitly contrast itself with siblings like get_competitor_price or get_brand_snapshot.

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 can be inferred from the name and content: an agent would call this when it needs a brand's homepage link structure rather than raw competitor prices or promotions. However, the description never explicitly says when to choose this tool over the available siblings or when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable behavioral context: it's free and non-billable, and it recommends a specific ordering (before billable tools) to avoid unnecessary costs. This goes beyond the annotations by surfacing cost and workflow implications, while remaining consistent with them.

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

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

Two sentences with no wasted words. The primary purpose is front-loaded in the first sentence, and the second sentence adds a clear directive for usage before billable tools. Every sentence earns its place, and the structure is immediately scannable.

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 tool with one parameter and no output schema, the description is quite complete: it covers what it checks (signals + freshness), cost implications, and recommended usage order. The only minor gap is that it doesn't enumerate which signals are returned, but that could vary per domain and is not essential for calling the tool correctly. Given the simplicity, the description provides sufficient context.

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

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

Schema description coverage is 100%—the schema defines 'domain' as 'eCommerce domain, e.g. gymshark.com'. The description reinforces this by saying 'for an eCommerce domain' but adds no new parameter-level details. Since the schema fully documents the parameter, a baseline score of 3 is appropriate; the description doesn't need to compensate.

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

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

The description clearly states the tool checks which competitive signals RivalSweeper has for an eCommerce domain, including per-signal freshness. This distinguishes it from sibling tools that return actual signal data (e.g., get_competitor_price, get_promotions) by focusing on coverage rather than content. The verb 'check' and specific resource 'competitive signals...for an eCommerce domain' make the purpose unambiguous.

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

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

The description explicitly instructs to 'call this before any billable tool so you never pay for a domain we do not cover.' This gives clear when-to-use guidance and implies when not to use billable alternatives (when coverage is absent). It also contrasts with billable siblings, effectively routing the agent to this free preflight check.

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 provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description goes beyond annotations by adding 'Freshness-stamped', disclosing the data may be the last known set, that no-data results in no charge, and that consuming this tool costs 2 credits. This is useful behavioral context without contradicting any annotation.

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 about three sentences, front-loading the core output, then listing fields, then the freshness/pricing note. The phrase '2 credits' repeats the tile, which is slight redundancy, but overall there is no wasted detail. It is efficient and well ordered.

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

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

With a single parameter and no output schema, the description carries most of the responsibility for return semantics. It lists every category of returned data and mentions the no-charge/no-data outcome. It does not define domain terms like 'DNA profile' or 'match tier', but they are not essential for selecting or invoking the tool.

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

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

The only parameter, domain, is documented with 100% schema coverage ('eCommerce domain, e.g. gymshark.com'). The description merely repeats 'for a domain' without adding new syntax, format constraints, or examples beyond what the schema already says. With full schema coverage, 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 the tool returns the 'last-known DNA competitor set' for a domain, specifying the source (RivalSweeper) and the exact fields returned (name, website, country, home-market flag, match tier, and the brand's own DNA profile). This clearly differentiates it from sibling tools like get_competitor_price or get_competitor_top_urls, which address different data types.

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 does not state when to use this tool versus alternatives, nor does it include any 'use X instead' guidance. It mentions 'last-known' and 'freshness-stamped', but that is about data from freshness policy, not about selecting it. Without any textual pointer to siblings, an agent may not know when this 'DNA competitor set' is the right call versus get_brand_snapshot or get_competitor_top_urls.

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, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the credit cost tiers (5/8/13 credits by depth) and the 'No data = no charge' policy. It also clarifies the output is monthly time-series data. This goes beyond the annotations and helps the agent understand cost implications.

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

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

Three sentences with zero waste. The core purpose is front-loaded, the credit tiers are compactly stated, and the 'No data = no charge' policy is a single short sentence. Every sentence earns its place.

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

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

For a read-only, idempotent tool with a fully documented schema, the description is nearly complete. It covers the data type, the depth tiers, and the cost policy. The only minor gap is that it doesn't describe the exact return shape (e.g., array of monthly objects), but since there is no output schema and the tool is simple, this is a small omission.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (domain, months, signal) with descriptions and constraints. The description adds the credit-tier meaning of the 'months' parameter and the two signal enum values, but it doesn't add syntax or format details beyond what the schema provides. 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 ('get'), a resource ('monthly time-series of price changes or stock-status flips'), and a scope ('for a brand'). It also distinguishes the two signal types and the depth tiers, so an agent can tell it apart from siblings like get_brand_snapshot or get_competitor_price 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?

The description clearly implies when to use this tool: when a brand's historical price or stock-status signal is needed. It does not explicitly name alternatives or exclusions, but the sibling list and the specific signal types provide enough context. A clear 'use this for time-series history' statement is present, though it lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: data is 'freshness-stamped' and costs 1 credit with no charge if no data is returned. This goes beyond the annotations without contradicting them.

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

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

The description is two concise sentences with no fluff. It front-loads the core purpose and then adds brief, relevant billing/freshness details. No unnecessary words.

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

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

The description covers enough for a single-parameter tool: what is returned (fields), cost, and freshness. The lack of an output schema is partially mitigated by listing fields, but error handling, pagination, or edge-case behavior are not mentioned. Still adequate for most agents.

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

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

The schema fully documents the only parameter 'domain' as 'eCommerce domain' (100% coverage). The description complements this by linking it to 'a brand', clarifying how the parameter is interpreted. This adds semantic value beyond the schema alone.

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

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

The description clearly states the tool retrieves active promotions/discount codes for a brand, listing specific fields (code, discount type/value, min order, validity window). This is a specific verb-resource pairing that naturally distinguishes it from sibling tools like get_competitor_price or get_brand_snapshot.

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 context: when you need promotion details for a domain. It does not explicitly mention alternatives or exclusions, but the focused purpose makes the right scenario obvious. No contradictory guidance is present.

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

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

The description adds valuable behavioral context beyond the annotations: it discloses the credit cost (1 credit) and the condition 'no data = no charge', which likely means if no data is available for the domain, there is no charge. This is extra context that is not in the readOnly/idempotent hintsforth and helps the agent understand the transactional implications.

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 concise (two sentences), front-loaded with the core outcome (6-pillar readiness score), and includes key operational details (uniqueness, credit cost, no data/no charge). No waste.

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

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

The description covers the purpose, output (tier and highlights), and operational constraint (credit). Given the tool has only one parameter and no output schema, the description is adequate. Minor gap: it does not specify what 'no data' means or how the credit is charged in detail, but the nuance 'no data = no charge' is captured.

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

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

The schema defines 'domain' with 100% coverage, and the description mentions 'a domain' and 'domain to score' in the parameter description. The description adds a bit of context (readiness score) but does not provide deeper meaning beyond 'domain to score'. Since schema coverage is high, a baseline of 3 is appropriate.

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

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

The description clearly states the tool computes a '6-pillar AI/agent-readiness score' for a domain)Skip and highlights that it is uniquely RivalSweeper data. It is specific in what it measures (schema.org, technical access, content quality, trust, AI-specific, entity recognition) and notes the output includes tier and highlights. It does not explicitly distinguish itself from siblings, but the unique nature of the data implies 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 indicates it can be used to score a domain's readiness and mentions a credit cost, but does not provide explicit when-to-use or when-not-to-use guidance or alternatives. The uniqueness of the data serves as a subtle implication that it is the only tool for this purpose, but that is not directly 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 readOnlyHint=false (mutation) and destructiveHint=false. The description adds valuable context: it requires a positive prepaid balance and that first data lands within 24-72h, implying asynchronous processing. It does not contradict annotations and provides a behavioral expectation beyond the flags.

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

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

The description is three tight sentences with zero fluff. The core purpose is front-loaded, and the prerequisite and latency are provided in subsequent sentences. Every sentence earns its place, making it easy for an agent to parse quickly.

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 write tool with no output schema, the description covers the essential context: what it does, the prerequisite (balance), and the expected delay. It does not mention error handling or what happens if the domain is already monitored, but these are minor gaps given the tool's simplicity and the annotations already 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?

The schema fully describes the single parameter 'domain' with 'Domain to start monitoring' (100% coverage). The description adds no additional detail about format, validity constraints, or examples. Since the schema carries the burden, a baseline of 3 is appropriate.

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

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

The description clearly states the action: 'add a domain to monitoring' with a specific resource (domain) and a distinct verb (add/request). It distinguishes itself from the sibling read-only get_* tools by framing this as a write/request operation. The purpose is unambiguous and immediately actionable.

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 prerequisites (account with positive prepaid balance) and gives a latency expectation, but it does not explicitly say when to use this tool versus alternatives or when not to use it. The sibling tools are all read operations, so the context implies this is the write path, but no explicit routing guidance is provided.

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