marketbasketanalysis-mcp

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

With no annotations carrying the burden, the description clearly discloses the key behavioral trait: it returns a numeric cohesion score between 0 and 1 based on merchant order data. It also communicates the statistical-signal framing and the decision-oriented purpose. It could go further by noting any caveats, edge cases, or failure behavior, but for a read-only scoring tool the core behavior is well explained.

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 efficiently structured: first sentence states the core action and output, second sentence gives the primary use case, third sentence adds query paraphrases. Every sentence earns its place and there is no redundant or vague 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?

The tool is simple (one parameter, no output schema), and the description covers all an agent needs: what the tool does, what input it expects, what the output represents, when to use it, and example user-phrasing signals. It is sufficiently complete for both selection and invocation.

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

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

The schema already fully describes product_ids as 'The products in the proposed basket (2-6)' with min/max constraints at 100% coverage. The description adds slight framing ('Given 2+ products', 'proposed basket/bundle') but does not meaningfully extend the semantics beyond what the schema already states. 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 names a specific verb ('Run market-basket analysis'), resource ('proposed basket / bundle'), and outcome ('cohesion score 0..1'). It also distinguishes itself from sibling generation tools by framing itself as a vetting step 'BEFORE recommending' a bundle, making it clear this is an evaluation tool rather than a recommendation or forecasting tool.

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

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

It gives explicit usage context: use to vet a proposed bundle before recommending it and to avoid plausible-but-unsupported bundles. It also lists natural-language triggers ('is this a good bundle?', 'do these products go together?'). It stops short of naming sibling alternatives or stating when not to use the tool, so it earns a 4 rather than 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the operation is idempotent by action_id and safe to retry, which is valuable behavioral context for a mutation tool. It does not detail side effects or reversibility, but the retry-safety and explicit confirmation guard meaningfully reduce the agent's uncertainty.

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 contain the essential information: what the tool does, its idempotency for safe retries, and the exact triggering condition. There is no filler and the most important usage constraint is clearly stated.

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 mutation tool with no annotations and no output schema, the description covers the key invocation concerns: what to pass, the source of action_id, the confirmation requirement, and retry safety. It does not describe the return value or error behavior, but those are less critical for selecting and safely invoking 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?

The schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds value by specifying that action_id comes from get_weekly_plan and that confirm is a guard against accidental dispatch, reinforcing the schema's meaning beyond raw field definitions.

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 ('execute'), a clear resource ('specific action from the merchant's weekly plan'), and gives concrete examples such as publish bundle, run mining job, and archive rule. It is easily distinguished from sibling tools like get_weekly_plan, which is about reading the plan rather than acting on it.

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

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

Explicitly tells the agent when to use it: AFTER the merchant confirms which action from get_weekly_plan they want to run. It also gives a direct exclusion: 'do not call preemptively.' This is clear, actionable guidance with no ambiguity.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals conditional return content (support, lift, and order sample count only when the rule is still live), graceful handling of disappeared pairs, and the BigCommerce-only platform limitation. It does not explicitly state read-only/idempotent behavior, but the return-oriented wording makes the tool's non-mutating intent clear.

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 appropriately sized at three sentences and front-loads the core purpose before covering usage context, sibling distinction, and edge-case behavior. Every sentence contributes non-redundant value, including the platform limitation.

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 a single required parameter and no output schema, the description gives an agent everything needed to call the tool correctly: what to pass, what will be returned, when to use it, which sibling it differs from, and how a missing pair is handled. No critical operational detail appears to be 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 description coverage is 100%, and the alert_id parameter is already documented as coming from get_drift_alerts. The description reinforces this source and uses alert_id contextually, but it adds no new format, type, or validation details beyond what the input schema already provides.

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

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

The description states a specific verb and resource: 'Explain ONE drift alert' and enumerates what it returns. It also explicitly differentiates itself from get_drift_alerts by noting that the sibling lists the feed while this tool drills into a single alert_id.

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 triggering scenarios with exact merchant phrasings like 'why did this pair drift?' and says to use it after seeing an alert in get_drift_alerts. It also names the alternative get_drift_alerts and explains the difference, which helps an agent select the correct sibling.

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 behavioral disclosure burden. It clearly discloses the return content (statistics plus plain-language narrative) and scopes the tool to BigCommerce today. It does not explicitly state read-only behavior, but 'explain' and the return description imply no mutation.

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 output, then gives usage triggers and sibling differentiations. Every sentence earns its place; the comparison sentences are compact and high-value rather than 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?

Although there is no output schema, the description enumerates the return fields and narrative style, so an agent knows what to expect. It covers the single parameter, the intended usage context, platform scope, and relationships to sibling tools, making the description complete for this low-complexity 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%, so the schema already documents opportunity_id and its source. The description reinforces that the id comes from get_opportunities and refers to a single opportunity, but it adds little meaning 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 verb ('Explain'), a specific resource ('ONE mined opportunity'), and the concrete outputs (support, confidence, lift, order sample count, narrative). It explicitly differentiates itself from get_opportunities and get_rationale, so an agent can distinguish it from siblings without inspecting schemas.

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

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

The description gives explicit trigger phrases ('why is this a good cross-sell?', 'explain this opportunity', 'why should I bundle these?') and the context of use ('after seeing it in get_opportunities'). It also names the alternatives it is not, making the when-to-use decision unambiguous.

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

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

With no annotations, the description carries the behavioral burden. It discloses that the tool returns a ranked list with a similarity score and a reason (context_similar / category_match / vendor_match), plus supported platforms. It doesn't mention read-only status or error behavior, but it adds substantial behavioral context beyond a bare description.

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 then covers usage, return behavior, and supported platforms. Every sentence adds value, though 'REPLACE it (not complement it)' and 'inverse of cross-sell' are slightly 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?

For a simple 2-parameter tool with no output schema, the description is complete: it states when to use it, what it returns, the reason categories, and platform support. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100% for both parameters, so the schema already fully documents product_id and limit. The description adds little parameter-level detail beyond restating that product_id identifies the item to replace, which is already in 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 names a specific verb and resource: 'recommend the top substitute items that could REPLACE it'. It explicitly contrasts with complement/cross-sell, which clearly separates it from related siblings like score_cross_sell and get_recommendations.

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

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

Provides explicit usage triggers with concrete query examples ('what's a substitute for X?', 'out of stock', 'find an equivalent product') and states the when-not case ('not complement it', 'inverse of cross-sell'). This is strong routing guidance for an agent.

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

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

With no annotations provided, the description carries the burden, and it does well: it discloses the algorithm (additive Holt-Winters), the data source (stored historical sales), and the advisory nature ('recommend'), implying no order execution. It could be more explicit about side effects or output shape, but the key behavior is clear.

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

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

The description is compact and front-loaded: purpose first, method second, usage triggers third. The four example queries are somewhat repetitive but still useful for agent routing, so it earns a 4 rather than 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?

For a simple two-parameter tool with no output schema, the description gives enough context to select and call it correctly: it names the inputs, the method, the data source, and the intended output (forecast plus recommended buy quantity). Exact return structure is unspecified, but not critical for invocation.

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

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

Input schema coverage is 100%, with strong descriptions for both bundle_id and horizon_weeks, including default, range, and week-vs-day conversion. The description adds only generic 'configurable horizon' context, so it does not need to compensate further.

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

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

The description names a specific verb and resource: forecast weekly sales and recommend a buy quantity for a specific bundle. It also gives concrete user-query examples, making the tool's scope unmistakable and distinguishing it from alert/opportunity siblings.

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

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

The description explicitly provides 'Use this when...' triggers and targets inventory/purchasing/merchant-ops agents. It does not name alternatives or give explicit when-not-to-use guidance, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the analytical behavior (multi-item basket analysis for cart completion, whole-cart pairing) and implies a non-mutating read operation, but it does not explicitly state that nothing is modified, how results are scored, or what happens with invalid product IDs. This is acceptable but leaves some behavioral details implicit.

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, then gives concrete usage signals, then differentiates from a sibling tool. No sentence is wasted, and the structure makes it easy for an agent to process 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 tool with only two parameters and no output schema, the description covers the essential invocation context: what input is expected, when to use it, and how it differs from the closest sibling. It does not describe the return structure, but the absence of an output schema makes that a minor gap rather than a critical one.

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

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

The input schema already documents both parameters with 100% coverage, including defaults, ranges, and accepted formats. The description adds useful context that the cart must contain MULTIPLE products and that pairing is whole-cart, but it does not significantly deepen the parameter 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 uses a specific verb ('recommend') and resource ('products that frequently bundle with the cart'), and clearly frames this as multi-item basket analysis for cart completion. It explicitly distinguishes itself from get_recommendations by emphasizing MULTIPLE products and whole-cart pairing, so an agent can tell them apart.

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

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

The description gives explicit trigger phrases ('what else do I need?', 'what completes this set?', etc.) and states when it should be used: when a user describes a multi-item cart. It also provides a when-not/alternative point by explaining the difference from get_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?

No annotations are present, so the description must carry the full behavioral burden. It implies a read-only operation by saying 'list', and it adds useful context by explaining the comparison baseline ('versus the prior mining job'). However, it does not disclose ordering, empty-return behavior, or authorization requirements, leaving modest gaps in behavioral transparency.

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 filler. The first sentence front-loads the verb, resource, and definition; the second gives concrete usage triggers. 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 list tool with two optional, well-documented parameters and no output schema, the description provides the core facts: what is listed, what qualifies as drift, and when to call it. A minor gap is the absence of a note about the alert object's shape, but sibling tools like explain_drift suggest that detail is available elsewhere.

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

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

The input schema already documents both parameters (limit and severity) with defaults, ranges, and enums, giving 100% schema description coverage. The tool description adds no additional parameter-level meaning 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 states a specific verb ('list') and a precise resource ('active drift alerts'), and then defines what those alerts are: recommendation rules whose confidence has materially changed versus the prior mining job. This clearly distinguishes it from siblings like get_forecast_alerts and get_opportunities by naming the exact object type and comparison baseline.

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

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

The description gives explicit use-case triggers ('what's changed?', 'is my model still accurate?', 'are any rules drifting?', SKU swap / seasonal shift). It does not name sibling alternatives or state when not to use them, but the trigger phrases make the intended invocation context clear.

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

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

With no annotations, the description carries the behavioral burden. It states 'list', implying a read-only operation, and clarifies the data source is forecast-based, but it does not explicitly say there are no side effects, describe output shape, or mention ordering/pagination behavior. It is safe but not deeply transparent.

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, front-loaded with purpose, followed by use cases and a drill-down suggestion. Every sentence earns its place; no filler or repetition of schema details.

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 moderate-complexity list tool with 3 optional parameters and no output schema, the description gives enough context to select and invoke it correctly: alert kinds, merchant intents, and a companion tool. It does not describe the return shape or alert fields, but that is not strictly required for invocation and no output schema exists to contradict 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%, so parameters are already documented, but the description adds value by mapping the kind enum to plain-language alert categories (stockout risk, demand drop, demand spike, unreliable forecast curve) and linking them to merchant questions. Severity and limit are left to the schema, which is sufficient.

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

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

The description opens with a specific verb and resource: 'list forecast-based alerts', and enumerates the alert kinds (stockout risk, demand drop, demand spike, unreliable forecast curve). This clearly distinguishes it from sibling tools like get_drift_alerts or get_recommendations by emphasizing 'forecast-based' alerts for bundles.

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 explicit merchant-question triggers ('what's at risk of stockout?', 'which bundles are losing demand?', 'do I need to reorder anything?', 'what should I restock?') and names a complementary tool, forecast_bundle, for drilling in. This is direct, actionable guidance for when to use the 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?

No annotations are provided, so the description carries the burden. It clearly signals a read-only 'List' operation, states the data source (order history), and reveals that results are ranked by support/confidence/lift/revenue-weighted score. It does not mention pagination or response envelope, but for a simple list tool 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?

Three sentences, each with a job: state the action and output, give usage triggers, and point to the companion tool. No redundancy or filler; the most important 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?

The schema covers both optional parameters, and the description explains the output's key metrics and provides usage guidance. It doesn't define the exact return object structure, but no output schema exists and the missing detail is unlikely to block a correct call. Overall adequate for the tool's complexity.

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?

Both parameters (limit, status) are fully described in the schema (100% coverage), including defaults and constraints. The description itself adds no extra parameter detail, 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 opens with a specific verb ('List') and a concrete resource ('ranked bundle / cross-sell opportunities mined from order history'), and it names the scoring dimensions. It does not explicitly contrast with sibling tools like get_recommendations, but the example merchant questions frame the intended use. This is a clear purpose, with only partial 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 gives explicit when-to-use triggers via merchant question examples ('what are my top opportunities?') and advises pairing with triage_opportunity to act on a specific item. It implies triage_opportunity is the alternative when action is needed, though it does not enumerate exclusions for other siblings. This is clear context with a partial alternative.

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 present, the description carries the behavioral disclosure burden. It clearly discloses the output type, length, tone, and example content ('short merchandiser-grade explanation'), which goes beyond the schema. It does not discuss failure modes or edge cases, but for a simple fetch-style tool this is largely sufficient.

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 tightly written sentences with no filler. It front-loads the core purpose, then gives the return format and the invocation guidance. 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?

Given the tool's simplicity, no output schema, and two fully documented parameters, the description covers the essential context: what the explanation looks like, where it fits in a recommendation flow, and when to call it. Slightly more detail about output formatting or error behavior could push it higher, but nothing critical is missing.

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

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

The schema already provides 100% coverage for both parameters, including their roles as antecedent and consequent. The description adds the product A/product B framing, which is helpful but largely restates what the schema already communicates, so it does not significantly raise the value above the schema 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 names a specific verb ('Fetch'), a specific resource ('the one-sentence rationale for why product B is recommended alongside product A'), and clearly distinguishes this from related sibling tools like get_recommendations and get_bundle_for_cart by focusing on the explanation step rather than the recommendation construction step.

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

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

It explicitly states when to use this tool ('after get_recommendations / get_bundle_for_cart') and gives concrete trigger phrasings ('why are these recommended together?' or 'explain this pairing'), leaving no ambiguity about the intended invocation 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?

No annotations are provided, so the description carries the behavioral disclosure burden. It clearly discloses that recommendations are based on mined order-history association rules, which implies the behavior is data-driven rather than manual or arbitrary. It also communicates it returns 'top complementary, frequently-bought-together products' but doesn't detail the output shape, pagination, or what happens if no associations exist. This is a modest gap but not critical for a read-style recommendation tool with a clear data source.

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 zero waste. The first sentence defines the core function and method, the second positions it against its single-product cross-sell scope, and the third lists supported platforms. It is front-loaded with the most important information, then adds routing and compatibility context. 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 2-parameter read-style tool with a 100% parameter-documented schema, the description is largely complete. It explains the tool's purpose, method, scope, and supported platforms, and the schema covers parameter semantics. Minor gaps: no explicit mention of the return shape (e.g., list of product IDs with scores) and no guidance on edge cases like empty results. Given the tool's simplicity and the strong schema coverage, these are 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%, so the schema already fully documents both parameters. The description adds value by framing the product_id as the 'given product' and clarifying the semantic context of 'frequently-bought-together' (mined order-history association rules). It also reinforces the limit's purpose implicitly through 'top complementary... products'. Since the schema already handles parameter semantics, and the description adds contextual flavor without redundancy, a 4 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 ('recommend'), a specific resource (complementary/frequently-bought-together products for a given product), and the underlying method (mined order-history association rules). It explicitly identifies itself as the single-product cross-sell tool, distinguishing it from siblings like get_bundle_for_cart, analyze_basket, find_substitutes, and score_cross_sell without needing to inspect their schemas.

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

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

The description provides explicit when-to-use guidance with concrete example user queries ('what goes with X?', 'what should I bundle with X?', etc.) and states the scope ('single-product co-purchase questions'). It also names the platform coverage (Shopify, Magento, WooCommerce), giving clear context for when this tool is applicable. While it doesn't explicitly name alternatives to exclude, the phrase 'single-product cross-sell tool' combined with example queries gives strong routing guidance among the 19 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?

With no annotations present, the description carries the behavioral disclosure burden. It conveys a read-only fetch action and describes the output as a ranked, typed action list. It does not discuss authentication, errors, or freshness details, but for a zero-parameter read tool the behavioral profile is sufficiently transparent.

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

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

The description is compact and front-loaded: the first sentence defines what the tool returns, and the second gives concrete invocation triggers. There is no redundant or filler 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 simple, zero-parameter read tool without an output schema, the description fully explains what the agent gets (a ranked list of typed actions) and when to use it. Nothing essential is missing for correct selection and invocation.

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

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

The tool has zero parameters and schema description coverage is 100%, so the description does not need to explain parameter meanings. Baseline for zero-parameter tools is 4, and no further parameter detail is required.

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 ('Fetch') and a clear resource ('current weekly action plan'), then elaborates with a ranked list of typed actions. This makes the tool's purpose unmistakable and differentiates it from siblings like execute_weekly_plan_action or get_opportunities.

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

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

The description provides explicit user-phrase triggers ('what should I work on this week?', 'what's on my plate?', 'show me my weekly plan') and a concrete scenario (summary before opening the admin). It does not explicitly state when not to use it or name alternatives, but the usage context is clear.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It mentions the Plus or Enterprise tier requirement and the ranked-output behavior, but does not explicitly state whether the operation is read-only, how empty or malformed orders are handled, or how top_k and min_utility interact.

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 written sentences with no filler. The core operation is front-loaded, followed by the output contract, then the appropriate usage context.

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 an analytics tool with a detailed input schema, the description covers the core contract: input payload, profit metric, ranking, and tier requirement. However, there is no output schema and the description does not specify the result shape or edge-case behavior, leaving some ambiguity for an agent deciding how to handle the response.

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

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

The input schema already covers 100% of parameters with descriptions, so the baseline is 3. The description adds useful context that utility is the sum of per-line profit and that top-K controls output size, but it does not add meaning for min_utility beyond what the schema already provides.

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

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

Opens with a specific verb and resource: 'Run high-utility itemset (HUI) mining' on a caller-supplied payload. It also states the output, top-K itemsets ranked by aggregate utility, and explicitly differentiates from frequency-based analysis with 'not just frequency', which helps distinguish it from sibling analytics tools.

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

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

Gives an explicit use condition: evaluate which item combinations drive the most profit for a specific time window or product subset. It provides a negative cue ('not just frequency'), but it does not name sibling alternatives or state when those would be preferred.

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 available, the description carries the behavioral disclosure burden and does so well: it reveals that only SKUs ordered >=2 times are considered, that confidence derives from cadence regularity, and that results are bucketed into four categories. It also discloses backend availability. However, it does not explicitly state that the call is read-only or describe behavior for unknown customers or customers with no eligible SKU history.

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

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

Though longer than a typical description, every sentence serves a distinct purpose: audience, core action, output behavior, bucket labels, example queries, backend support, and a platform exclusion. It is front-loaded with the essential action and contains no filler or repetition.

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

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

Given the absence of an output schema, the description sufficiently explains the return value shape (predicted next-order dates, confidence, buckets) and provides usage triggers. It also covers optional filtering and backend constraints. Minor gaps remain: no explicit read-only declaration, no error-handling notes for missing customers, and no handling of customers with fewer than two ordered SKUs.

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 provides 100% parameter description coverage, including customer_id format variants (numeric vs. GID) and product_id's optional filtering purpose. The tool description reinforces the product_id usage with a query example but does not add new parameter-level semantics beyond what the schema already gives.

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

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

The description opens with a specific verb and resource: 'predict when a B2B customer / account is due to reorder.' It goes further to specify output granularity (per-SKU next-order dates), confidence based on cadence regularity, and concrete bucket labels ('overdue' / 'due_soon' / 'on_track' / 'not_predictable'), which clearly distinguishes it from sibling forecasting and recommendation tools like forecast_bundle or score_cross_sell.

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 supplies explicit trigger queries ('what's Acme Corp due to reorder?', 'when will customer X need more of Y?') and a broader use case ('show me stockout risks for my B2B accounts'), plus proactive replenishment. It also states supported backends and an explicit exclusion ('Not available on OroCommerce'), giving an agent clear when-to-use and when-not-to-use guidance.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It does this well by explaining that the tool returns a 3-6 item bundle, a median reorder cadence, a 0..1 confidence score, and a monthly_value only when prices are known, plus the fallback behavior when no customer_id is supplied. The main omission is that it never explicitly states whether this tool has side effects (e.g., whether it actually creates a subscription), though the word 'propose' plus 'returns' strongly implies a read-only recommendation.

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 four sentences, each with a distinct purpose: core function and outputs, when to use with example queries, customer_id behavior and fallback, and platform coverage. It is front-loaded, dense with useful information, and contains no filler or repetition.

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

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

Because there is no output schema, the description's explicit disclosure of return fields (bundle size, cadence, confidence, monthly_value conditionality) is essential and well provided. It also covers input constraints, fallback behavior, platform compatibility, and typical intents, leaving little for an agent to infer.

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 meaning beyond the schema by clarifying that seed_product_ids come from a first-order purchase, and by explaining that customer_id causes the tool to blend per-SKU reorder cadence versus falling back to seed-only catalog cohesion. It doesn't discuss kit_size or cadence_days in the prose, but those are already well-described in the schema, so the added context pushes this above baseline.

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

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

The description opens with a specific verb and resource: 'Propose a recurring subscription bundle for a customer based on their first-order items.' It clearly states the inputs, outputs, and example merchant intents, making the tool's function unambiguous. However, it never explicitly distinguishes itself from sibling tools like forecast_bundle or get_bundle_for_cart, so it relies on semantic differences rather than direct 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 gives explicit when-to-use guidance through example queries ('what should they subscribe to?', 'build a monthly subscription bundle from this order') and explains the behavioral difference when customer_id is supplied vs omitted. It does not, however, provide any when-not-to-use guidance or point to alternative sibling tools, stopping short of full routing clarity.

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 and delivers key behavioral detail: it returns confidence backed by real co-purchase data, and it returns a 'clear no signal' result when no qualifying rule exists. It doesn't discuss read-only guarantees or confidence scale, but the described fallback and data source cover the most important behavioral nuances for a scoring 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 front-loaded sentences with no waste: the first states the operation and output, the second gives usage and example questions. Every phrase earns its place, and the most important information appears immediately.

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 behavior—it does, by promising either a confidence value or a no-signal result. It also covers usage scenarios. It doesn't specify the confidence format or scale, but for a simple two-parameter tool this is a minor gap rather than a completeness failure.

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 product_a and product_b clearly described as antecedent and consequent. The tool description adds little beyond that, only framing them as 'two specific products.' Baseline 3 is appropriate since 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 names a specific verb ('score'), resource ('cross-sell strength between two specific products'), and explicitly distinguishes this pairwise scoring from other tasks by giving example questions ('is X a good cross-sell for Y?'). It clearly differentiates from siblings like find_substitutes or get_recommendations without needing to inspect their schemas.

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

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

It provides concrete usage context: 'Use this to validate a proposed pair before recommending it,' plus example queries that map to user intents. It doesn't explicitly mention when not to use it or name alternative tools, but the guidance is clear enough for an agent to select it for pair-level validation.

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 and does so well: it discloses that the composite rate is the max of item rates, that each item's historical return rate is included, that a low/medium/high recommendation is produced, and that it is backed by the merchant's real order and refund history. This goes well beyond a generic prediction description.

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 efficient and front-loaded: purpose, output, trigger phrases, and backing data each earn their place in three compact sentences. No filler or redundancy is present.

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, but the description fully covers what the agent should expect: composite bundle return rate, per-item historical rates, and a low/medium/high recommendation. Combined with the complete parameter schema and clear trigger examples, nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already fully documents product_ids and threshold, including the fixed low/medium/high bands and threshold override behavior. The description adds only contextual phrasing like 'candidate bundle' and '2-6 products', which does not meaningfully extend 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 opens with a specific verb and resource: 'Predict return risk for a candidate bundle of 2-6 products.' It further distinguishes itself from siblings by focusing on return risk and bundle-level return rate, which is clearly different from forecast_bundle, score_cross_sell, or predict_reorder.

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 lists natural-language triggers and an agentic use case: verifying a bundle won't hurt return KPIs. It gives clear positive guidance but does not state when not to use the tool or name alternatives/exclusions, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden and does well: it labels the tool as state-mutating, mentions the confirm=true guard, and discloses that archive permanently retires an opportunity. It could add more about reversibility or failure modes, but the essential behavioral traits are covered.

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

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

The description is compact and front-loaded: it leads with the three operations, immediately states the mutating nature, and then provides action-level guidance. Every sentence contributes useful information with no filler.

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

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

For a small three-parameter mutation tool, the description covers the core scenario, the guard, and the action outcomes. However, since there is no output schema, it does not describe what a successful response looks like or how errors surface, which would make it 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 the schema already documents all parameters. The description adds value by explaining the semantic meaning of each action value, including the nuance that activate publishes a proposed rule and archive permanently retires it, going beyond the bare enum labels.

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

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

The description states a specific verb-resource pairing: 'Pause, activate, or archive a specific opportunity from get_opportunities.' It clearly identifies the exact actions and the source list, distinguishing it from read-only siblings like get_opportunities and explain_opportunity.

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

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

The description gives an explicit usage trigger: 'Use this after the merchant has explicitly picked an opportunity to act on.' It also explains what each action does, which helps the agent choose between activate, pause, and archive. It does not explicitly name alternatives to avoid, but the context is clear enough.

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