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

With no annotations provided, the description carries the full burden of disclosing behavior. 'Register' implies mutation but does not explain side effects, reversibility, permissions, return values, or error conditions. The description only gives examples of promo types, not operational specifics.

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, front-loaded sentence with exactly one verb and resource. It is efficient, concise, and free of filler 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?

Given 6 parameters, 3 required, no output schema, and no annotations, the description is too minimal. It does not explain the return behavior, validation rules, idempotency, or how this tool fits into the promo workflow (e.g., relation to keepa_list_promos or keepa_analyze_promo_impact).

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 parameters. The description's examples of promo types (coupon, deal, Lightning Deal) are redundant with the schema's own examples. The description adds no meaningful new parameter 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 uses a specific verb 'Register' and resource 'promotional event for an ASIN', with examples like coupon, Lightning Deal. This clearly distinguishes it from sibling tools such as keepa_list_promos (listing) and keepa_analyze_promo_impact (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 provides no guidance on when to use this tool versus alternatives, no prerequisites, exclusions, or mention of related tools. It is a bare statement of action without contextual usage instructions.

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?

With no annotations provided, the description must fully disclose behavior. It states that the tool 'flags deterioration patterns' but does not explain what this means in practice—whether it returns a list, a boolean, or modifies state. It also does not clarify if the operation is read-only or if any prerequisites (e.g., tracking) are required.

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 sentences, front-loaded with the core purpose and a succinct note about the deterioration flagging. Every word earns its place, with no fluff or redundancy.

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

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

There is no output schema, so the description must explain return values. The phrase 'flags deterioration patterns' is vague and does not specify what the tool actually returns or how the flags are presented. Given the moderate complexity of trend analysis, this is insufficient for an agent to fully anticipate the tool's 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?

All three parameters (asins, domain, period_days) have descriptions in the schema, giving 100% coverage. The description adds minimal extra meaning by mentioning 'ASINs' and 'period', which loosely map to asins and period_days, but provides no additional 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 clearly states the tool analyzes BSR trends for ASINs over a period and specifically flags deterioration patterns. This distinguishes it from siblings like get_price_history (price trends) and get_best_sellers (best seller lists), making the purpose 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 usage for BSR trend analysis but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The clear subject matter gives context, but there is no comparative or conditional information.

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?

No annotations are provided, so the description carries the burden. It discloses the behavior of comparing time periods and measuring lift, but it does not explicitly state whether the operation is read-only or if any side effects exist. Since 'analyze' implies a safe read, the description adds some context but lacks full behavioral 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?

Two concise sentences that front-load the action and metric. Every word earns its place without filler or repetition. The structure is clean and easily 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?

The tool has 5 optional parameters, two modes (promo_id vs. ASIN/domain/date range), and no output schema. The description does not explain the output format, how lift is calculated, or which parameter combination should be used. This is incomplete given the tool's analytical complexity and lack of structured output reference.

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 five parameters. The description does not add new parameter-specific meaning, but it does mention 'promo period' which relates to start_date/end_date and promo_id. This aligns with the baseline score of 3 for high schema coverage.

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

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

The description clearly states the tool's purpose: 'Overlay a promo with rank/price data to measure lift' and specifies the comparative method. This distinguishes it from siblings like keepa_list_promos or keepa_get_price_history, as it focuses on analyzing promo impact rather than listing or fetching raw data.

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: analyze a promo by comparing before, during, and after periods. However, it does not explicitly state when to use this tool over alternatives or provide exclusions, such as 'use keepa_get_price_history for raw price data instead.'

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?

No annotations are provided, so the description must carry the behavioral burden. It does not disclose key traits such as whether checking tokens itself consumes tokens, whether it requires authentication, or the format of the response. For a token-checking tool, this is a significant 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?

The description is one sentence, directly front-loaded with the action and resource. No filler or redundant content, every word 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 status tool with no output schema, the description implies the return values (remaining tokens and refresh rate), but it omits whether the call itself consumes tokens or any context on how to interpret the refresh rate. Given the lack of annotations, this is a noticeable 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?

The tool has zero parameters and the input schema is empty, so the baseline is 4. The description adds no misleading parameter information, and there are no parameters to explain.

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

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

The description clearly states the specific action ('Check remaining Keepa API tokens and refresh rate') and the resource (tokens and refresh rate). It distinguishes itself from sibling tools, which all focus on product data or tracking, whereas this is a utility/status check.

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 guidance is provided on when to use this tool, such as checking tokens before API calls, or any exclusions. Sibling tools are not referenced. The usage is only implied by the tool name, 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?

No annotations are provided, so the description carries the full burden. The verb 'check' strongly implies a read-only operation with no side effects, which is useful. However, it does not disclose what the response format is, whether it makes live calls, or any rate limits. It adds some context beyond the name by naming the specific checks, but minimal depth.

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

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

The description is a single sentence of 12 words, extremely concise and front-loaded. There is zero wasted text; every word contributes to the purpose. It is as short as possible while making sense.

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

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

The tool has no output schema and no annotations, so the description should compensate by explaining the return value and any important details. It does not. The agent may not know what the check produces, what 'orphans', 'attribute drift', or 'child changes' mean in the context, or how to interpret the result. This makes the description incomplete for a tool with no structured output metadata.

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% (both asins and domain have descriptions). The description does not add any extra meaning to the parameters; it only describes the overall purpose. Baseline score of 3 applies because the schema already documents the parameters fully.

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

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

The description uses a specific verb 'check' with a clear resource 'variation family' and names specific scopes: orphans, attribute drift, and child changes. This distinguishes it from sibling keepa_get_variations, which likely just retrieves variation data, but it does not explicitly name alternatives or contrast 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 phrasing 'check variation family for...' implies it is used for validating variation family health, but it does not explicitly state when to use it vs. alternatives like keepa_get_variations or keepa_get_changes. There is no mention of 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic action and does not disclose response format, sorting order, rate limits, errors, or whether the list is live or historical. This is minimal behavioral information.

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, concise sentence with no fluff. It is front-loaded with the action and resource, making it easy to parse. There are 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 schema covers parameters fully, but with no output schema, the description should clarify return semantics. It states 'ASIN list' which implies the core output, but does not specify structure, limits, or potential edge cases. It is adequate for a simple tool but has clear 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?

The input schema already describes both parameters: 'domain' with a default and 'category' as an ID. Since schema coverage is 100%, the description adds no value beyond the schema, warranting the baseline score of 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 uses a specific verb 'Get' with a clear resource 'best seller ASIN list' and scope 'for a category'. It clearly distinguishes from sibling tools like keepa_get_product and keepa_get_price_history.

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, no exclusions, and no prerequisites such as how to obtain a valid category ID. Users are left without contextual direction.

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

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

With no annotations provided, the description must disclose behavioral context. It partially does by specifying the output fields ('current seller, FBA status, and offers'), but it does not mention whether this is a pure read operation, any rate limits, or what happens when no buy box exists. The read-only nature is implied by 'Get' but not explicitly stated.

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, well-structured sentence conveys the tool's purpose and main output attributes without any filler or repetition. Every word adds value, making it easy 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?

The tool is relatively simple (2 params, no output schema), and the description covers the core purpose and primary output fields. However, it lacks behavioral details such as whether multiple ASINs are processed individually or as a batch, and any edge-case behavior. Given no annotations or output schema, the description is adequate but not comprehensive.

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 both parameters, so the description adds little beyond the schema. It explicitly mentions 'for ASINs' but does not elaborate on the 'domain' parameter, which the schema already describes as having a default. The description's value is in explaining return content, not parameter 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 uses a specific verb ('Get') and identifies a distinct resource ('buy box ownership info') with immediate context (current seller, FBA status, offers). This clearly differentiates it from sibling tools focused on price history, product details, or variations.

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 (checking buy box ownership for ASINs) but provides no explicit guidance on when to choose this tool over siblings or any exclusions. It does not state conditions like requiring a domain or number of ASINs, leaving the agent to infer from the schema.

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 lists what the tool returns (name, parent, children, product count) but provides no additional behavioral context such as read-only nature, rate limits, authentication requirements, or error handling. Since no annotations are provided, the description carries the full burden, and while it is not misleading, it is minimal.

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, concise sentence that states the purpose and expected output elements without any redundant words or filler. It is front-loaded and 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 lookup tool, the description covers the key output details and the parameter semantics are fully in the schema. However, the lack of an output schema means the description should ideally clarify whether the response is a single object, how missing categories are handled, or whether the hierarchy is full or partial. It is nearly complete but leaves a small gap.

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

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

Schema description coverage is 100% for both parameters (domain and category). The description adds no extra meaning beyond what the schema already provides, such as the format or constraints of the category ID or how domain affects results. Baseline 3 is appropriate since schema handles 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 uses a specific verb ('Look up') and resource ('category details'), with concrete attributes (name, parent, children, product count). This clearly distinguishes it from sibling tools like keepa_get_product or keepa_get_price_history, which serve different purposes.

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

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

The description gives no indication of when to use this tool versus alternatives. It does not mention exclusions or when a different keepa tool would be more appropriate, leaving the agent without guidance for tool selection among many similar lookup tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Query' which implies read-only, but it does not state side effects, rate limits, pagination, output format, or the nature of 'changes' (e.g., price, offer, review). For a tool with no output schema, this is a significant 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?

The description is a single sentence with no filler words. It is front-loaded with the action ('Query') and directly states the resource and time scope. Every word 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?

The tool has 4 parameters, no output schema, and no annotations, yet the description provides only a minimal purpose statement. It does not explain what 'changes' refers to, the shape of the response, how filtering interacts with the severity parameter, or when to prefer this tool over siblings like get_price_history or get_buy_box. This is insufficient for a user to invoke 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%, and every parameter (days, asins, domain, severity) has a description. The tool description adds no extra meaning beyond the schema—'over a given period' merely echoes the 'days' parameter. Per the baseline rule, a 3 is appropriate when the schema already documents all parameters.

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

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

The description clearly states the tool's function: 'Query detected changes for ASINs over a given period.' It uses a specific verb ('Query') and resource ('changes for ASINs'), and the period scoping distinguishes it from related getter tools like get_product or get_price_history. Though it doesn't name siblings, the concept of 'detected changes' is distinct enough.

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 primary use case—retrieving change data for ASINs over a time window. It clearly communicates when to use the tool (when you need detected changes) but provides no exclusions or alternative tool references. This matches 'clear context, no exclusions' rather than explicit when/when-not 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It indicates a read operation ('Get') but does not mention side effects, authorization requirements, rate limits, or any other behavioral nuances beyond the basic action.

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, front-loaded sentence that directly states the tool's purpose with no filler or redundant details. Every word 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 get-by-ASIN tool, the description is adequate but leaves gaps. There is no output schema, so the description should hint at return structure, and the 'domain' parameter behavior is not explained. However, the tool itself is relatively straightforward, so it is minimally 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 the baseline is 3. The description adds no additional semantics beyond what the schema already states, such as that 'asins' are the target identifiers and 'domain' is optional with a default. It does not enrich parameter understanding.

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

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

The description uses the specific verb 'Get' and explicitly names the resources: coupon history, active promotions, and lightning deal data for ASINs. This clearly distinguishes it from sibling tools like get_product or get_price_history, which target different data.

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 when deal-related data is needed, but provides no explicit alternatives or exclusions. It does not mention when to prefer other tools or any prerequisites, so guidance is only implicit.

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?

With no annotations, the description carries full behavioral disclosure burden. It only mentions that the tool returns time series data, which is minimal. It does not disclose data granularity, response size, limits, or any operational traits.

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 and front-loaded with the verb 'Get'. It uses two short sentences with no filler, though it could be structured to include more useful detail without losing brevity.

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?

Since there is no output schema, the description should explain the return structure but only says 'time series data,' which is vague. Inputs are covered by schema, but the output format, units, and organization are left unclear, making the description incomplete for an agent.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description adds no additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool gets price, rank, rating, and review history for ASINs, using a specific verb and resource. It differentiates itself from siblings by mentioning time series data, 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?

No guidance is given on when to use this tool versus siblings like keepa_get_product or keepa_get_changes. The description only states functionality without context or exclusions.

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?

No annotations are provided, so the description carries the full burden. It clearly indicates a read-only operation with 'Fetch' and enumerates the return fields, which is helpful. However, it does not disclose any potential side effects, authorization needs, rate limits, or token usage, which could be relevant for a Keepa API 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?

Two sentences with the action and purpose front-loaded. The list of return fields is a concise enumeration without unnecessary detail. Every word 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 tool with 3 parameters and no output schema, the description is fairly complete: it states what it does, the range of ASINs, and the key return fields. However, it does not explain the effect of optional parameters like domain or stats_days, and the variations field could be complex without an output schema, leaving some ambiguity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema; it mentions '1-100 ASINs' which is already encoded in minItems/maxItems, but does not elaborate on domain or stats_days parameters. The schema already handles parameter semantics adequately.

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

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

The description clearly states the tool fetches current product data for 1-100 ASINs, which is a specific verb+resource. It lists the returned data fields (title, brand, prices, BSR, rating, buy box, images, features, variations), distinguishing it from sibling tools like keepa_get_price_history or keepa_get_buy_box that focus on specific subsets.

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 for current product data lookups, but does not explicitly say when to use this tool over alternatives. It doesn't mention exclusions or provide guidance such as 'for historical data use keepa_get_price_history'. The context is adequate but not explicit.

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

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

No annotations are provided, so the description carries the burden. It discloses that the tool retrieves time-series data and specifies the metric (units sold per month), which conveys a read-only behavior. However, it does not mention any limitations such as token costs, data availability, or that some ASINs may lack sales history. Basic transparency is present but not comprehensive.

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 exactly two short sentences with no fluff. It front-loads the primary purpose and immediately clarifies the output unit. Every word earns its place, making it concise and well-structured.

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

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

Given the moderate complexity (2 well-described parameters, no output schema), the description adequately explains the return value: monthly units sold over time. It covers the core function without extraneous detail. However, it could mention the historical range or note that data is aggregated monthly, but the description already says 'monthly' and 'over time,' so it is sufficiently complete for this simple 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 description coverage is 100%, with both 'asins' and 'domain' already documented. The description adds no new parameter-level semantics beyond reinforcing that the output is monthly sales volume. The baseline of 3 applies because the schema does the heavy lifting, and the description does not significantly enhance parameter understanding.

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

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

The description uses a specific verb and resource: 'Get monthly sales volume time series for ASINs.' This clearly distinguishes it from sibling tools like keepa_get_price_history or keepa_get_buy_box by focusing on sales volume over time. It is immediately evident what the tool does.

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

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

The description implies usage for sales volume data but offers no explicit guidance on when to choose this tool over alternatives. Sibling tools exist for price history, best sellers, etc., but no exclusions or comparisons are provided. This is an implied-use case rather than clear contextual 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?

With no annotations, the description carries the full burden of behavioral disclosure. It does not mention any potential side effects, authentication requirements, rate limits, data freshness, or limitations. While 'Get' suggests read-only, important behavioral context is missing.

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, focused sentence that immediately states the core purpose and includes valuable details about the output. There is no redundant or filler content, making it highly efficient.

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

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

The tool has 2 parameters, no output schema, and no annotations. The description lists key return elements but leaves ambiguity about time range, grouping, and how sellers are identified. It is adequate for a simple tool but lacks some contextual details that would make it fully self-contained.

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

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

Schema coverage is 100% and each parameter already has a description. The tool description adds some semantic context by mentioning the output (win percentage, average price, FBA status) but does not provide additional parameter-level meaning beyond what the schema already offers.

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

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

The description clearly states the tool fetches buy box statistics per seller for ASINs, specifically listing win percentage, average price, and FBA status. This is a specific verb+resource+scope that distinguishes it from siblings like keepa_get_buy_box or keepa_get_price_history.

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 obtaining per-seller buy box stats but does not explicitly state when it should be used over alternatives or when not to use it. No sibling comparisons or exclusions are provided, leaving usage guidance implied rather than explicit.

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

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

There are no annotations, so the description must carry the full behavioral burden. It only describes the output content but does not disclose whether the operation is read-only, any limitations, or potential side effects. For a data-retrieval tool this is minimal.

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, front-loaded sentence that conveys the core purpose and key output details without any wasted words. It is an excellent example of concise, readable documentation.

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-like lookup with only two parameters and no output schema, the description adequately explains the tool's core function. It could be slightly more complete by clarifying the domain default or return structure, but overall it satisfies the primary need.

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%: both 'asin' and 'domain' are described in the schema. The tool description adds no extra parameter meaning beyond what the schema already provides, placing it at the baseline of 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 the verb 'Get' and the specific resource 'variation family tree for an ASIN', and elaborates with 'parent/child relationships and attributes' which distinguishes it from siblings like keepa_get_product or keepa_check_variations.

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 guidance is provided on when to use this tool versus the similar sibling keepa_check_variations or when not to use it. The description only states what it does without any context or alternative recommendations.

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?

With no annotations, the description must disclose behavioral traits, but it only states the action. It does not confirm read-only behavior, auth needs, data scope, or return format. The minimal wording gives no additional 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?

The description is a single, well-structured sentence that front-loads the verb and resource. Every word contributes value, with no redundancy or filler.

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

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

Given the absence of an output schema and annotations, the description is too thin. It does not mention what constitutes a promotional event, potential result size, pagination, or any limitations. For a listing tool with three optional parameters, more context is needed to fully guide an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a slight nuance by clarifying that omitting 'asin' means 'all tracked ASINs', which goes beyond the schema's 'Filter by ASIN'. However, it does not elaborate on domain or active_only, so it stays at the baseline.

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

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

The description uses a specific verb 'List' and names the resource 'promotional events' with scope ('for an ASIN or all tracked ASINs'). It clearly distinguishes from mutating siblings like keepa_add_promo and keepa_analyze_promo_impact, though it doesn't explicitly differentiate from keepa_get_deals.

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 guidance is provided on when to use this tool versus alternatives. There is no mention of conditions, exclusions, or preferred scenarios, leaving the agent without contextual decision support.

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?

No annotations are provided, so the description carries the full burden. It does disclose that the tool stores state and compares to a previous snapshot, which is useful. However, it omits side effects (e.g., whether the previous snapshot is overwritten), permissions required, or behavior when no previous snapshot exists. For a state-changing tool, this is a significant 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?

The description is a single sentence that efficiently conveys the core action and key return behavior. It is front-loaded and contains no filler, making it well-structured for quick comprehension.

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 moderate complexity (stateful snapshot, comparison) and lack of output schema, the description provides a general sense of return value ('detected changes') but omits the return format and edge cases (e.g., first snapshot, no tracked ASINs). It is adequate but leaves room for clarification.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific meaning beyond what the schema already provides. The phrase 'for tracked ASINs' mirrors the schema's default value description for the 'asins' parameter, so no additional value is added.

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 action: 'Fetch and store a snapshot for tracked ASINs.' This distinguishes it from siblings like keepa_get_product (which reads current data) and keepa_get_changes (which may only retrieve changes without storing a snapshot). The verb+resource combination is 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 usage for tracked ASINs and says it returns changes vs the previous snapshot, giving context. However, it does not explicitly state when to use this over keepa_get_changes or other siblings, nor mention any exclusions or prerequisites beyond 'tracked.' The guidance is implicit rather than explicit.

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

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

No annotations are provided, so the description carries the full burden. It accurately states that the tool adds ASINs to a monitoring list and indicates the consequence (daily snapshot collection and change detection). However, it does not disclose potential side effects such as whether duplicates are allowed, if there is a limit, or how the list is persisted. This is adequate but not rich.

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 sentence, front-loaded with the action and resource, and contains no redundant or filler words. Every word 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?

Given the tool's moderate complexity (4 parameters, no output schema, no annotations) and the 100% schema coverage, the description is mostly complete. It explains the primary purpose and the monitoring context. Additional details such as return value or constraints would improve completeness, but the current description is sufficient for an agent to understand the tool's role.

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 covers all parameters with descriptions (100% coverage), so the baseline is 3. The description does not add any parameter-specific meaning; it only describes the overall action. All required and optional parameters are already explained in the schema, so no additional value is provided here.

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

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

The description uses the specific verb 'Add' with the resource 'ASINs to the monitoring list', clearly stating the tool's function. It also includes the purpose 'for daily snapshot collection and change detection', distinguishing it from siblings like keepa_get_changes (which retrieves changes) and keepa_take_snapshot (which collects a snapshot at a specific time).

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: this tool is for initiating ongoing monitoring of ASINs. It implies a use case distinct from one-time lookups or immediate snapshots, but it does not explicitly name alternative tools or state when not to use it. This is clear context without explicit exclusions.

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