Packrift Packaging

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

The description adds valuable behavior beyond the provided annotations (readOnlyHint, openWorldHint) by stating 'Live, never cached,' which informs the agent about data freshness. It also warns about the correct encoding of variant_ids, which is a behavioral constraint. No contradictions with annotations exist.

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, with every sentence serving a purpose. It front-loads the main use case and includes essential operational details (array of strings, live data) without redundancy. It is well-structured and easy to parse.

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

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

The tool has moderate complexity with 6 parameters, and while the core required parameter is well explained, the optional parameters are not addressed. There is also no output schema, and the description does not mention what the tool returns. However, for a simple read-only inventory check, the essential context is covered, but gaps remain for a fully self-sufficient description.

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 description significantly clarifies the required parameter variant_ids with a precise type, example, and a warning ('Never send variant_ids as numbers'). However, the schema description coverage is only 17%, and the description does not compensate for the other five parameters (journey_id, match_type, selected_sku, result_set_id, selected_handle), leaving their semantics unclear.

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: 'confirm stock before recommending a SKU or building a cart.' This specifies a verb, resource, and use context. However, it does not explicitly distinguish itself from the sibling tool 'inventory_status', which may serve a similar function, so it does not fully meet the top criterion for sibling differentiation.

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

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

It provides clear context for when to use the tool: 'before recommending a SKU or building a cart.' It also specifies a key requirement ('Required argument'). However, it does not mention any exclusions or alternative tools, so it stops short of full guideline completeness.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description adds value by disclosing the output format (ranked candidates plus plain-language comparison summary). It does not add deeper behavioral details like data freshness or limits, so a mid-range score is appropriate.

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 clear, front-loaded sentences. Every phrase adds value: the tool's role, inputs, and output are concise without 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, but the description covers the high-level return. However, it omits how 'family' filters results and how 'limit' behaves, which are present in the schema but under-described. Overall, the description gives adequate context for the main use case but leaves ambiguity for optional parameters.

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 only 50%, and the description does not compensate. It restates the purpose of requested_spec as in the schema but provides no meaning for the 'limit' and 'family' parameters, which lack schema descriptions. The enum values for family are present but their functional role as a filter is not explained.

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: comparing a packaging spec, competitor-style item, or catalog-number request against Packrift's catalog. It returns ranked candidates and a summary, which is specific and distinguishes it from sibling tools like search_products or find_packaging_for_item.

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 when to use it (buyers comparing specs/items/catalog numbers) but does not explicitly exclude other tools or name alternatives. Context is clear, but no direct 'when not to use' guidance is provided.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds that the tool 'never places an order' and returns 'a tracked packrift.com cart URL plus a Shopify cart permalink', which gives concrete behavioral context beyond the annotations.

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

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

Three sentences, each with a distinct purpose: purpose/precondition, input guidance, and output/side-effect. No filler. Front-loaded with the action.

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

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

With 10 parameters fully described in the schema and annotations covering safety, the description supplies the missing context about when to invoke and what to expect. It doesn't describe return format details, but output schema is absent anyway; the mention of the two URLs suffices.

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 baseline is 3. The description adds value by recommending 'sku plus quantity' over 'items' and clarifying that items are for when variant IDs are known. This guidance is not in the schema.

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

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

The description clearly states the tool's verb and resource: 'Build the checkout handoff URL' and gives the precondition 'once the buyer has confirmed an exact product, quantity, live price, and stock.' It distinguishes the operation from sibling tools like get_bulk_quote_link and get_reorder_link by focusing on the checkout handoff context, 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?

Provides clear guidance: 'Preferred input is sku plus quantity; use items only when you already hold variant IDs as strings.' Also conditions usage on buyer confirmation. It does not explicitly enumerate when-not-to-use relative to sibling tools, but the 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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the agent knows it is safe and side-effect-free. The description adds value by disclosing that it returns safe next actions and a quote-request URL, which is not captured in annotations. No contradictions.

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, efficient sentence that states the purpose and expected outputs without wasted words. It is front-loaded with the primary action and includes a logical sequence ('then').

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 no output schema, the description clearly enumerates what is returned: an explanation, safe next actions, and a quote-request URL. Combined with the well-documented input schema, this provides sufficient context for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description adds minimal extra meaning beyond mapping 'buyer's spec' to requested_spec, but it does not explain family or reason usage. 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 uses a specific verb ('explain') and clearly identifies the resource (why a nearby product is not an exact match) and the outcome (safe next actions and a quote-request URL). This distinguishes it from sibling tools like compare_alternatives or get_pricing.

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 a clear usage context: when there is a nearby product that should not be presented as an exact match. It does not explicitly name alternatives or exclusions, but the context is unambiguous and the tool's niche is clear relative to siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the bar for additional context is lower. The description adds valuable behavioral detail: returns up to 5 curated SKUs ranked by fit, with price, stock, URL, and cart-continuity fields, and explains free-text mapping for use_case. This goes beyond structured data and informs expected output and flexibility.

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 long, front-loaded with the trigger condition and required arguments, followed by the output specifics. Every sentence adds functional value; there is no fluff or redundant 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?

Given there is no output schema, the description compensates by explaining the return shape (up to 5 curated SKUs with price, stock, URL, and cart-continuity fields) and the free-text use_case behavior. It does not address no-match scenarios, but the sibling tool explain_no_exact_match likely covers that, making this sufficiently complete for a read-style 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 baseline is 3. The description repeats the use_case canonical values and free-text mapping exactly as in the schema, and lists all parameter names, but adds no new semantics beyond the schema. The parameters are self-explanatory, so this is adequate but not enhanced.

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 identifies the tool's purpose: find packaging for an item based on dimensions. It uses a specific verb ('find') and resource ('packaging for an item'), and distinguishes itself from siblings like check_inventory or get_pricing by focusing on dimension-based fit ranking. The title and first sentence together make the scope unambiguous.

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

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

The description explicitly states when to use the tool: when the buyer has item dimensions and needs a fitting box or mailer. It does not name alternative tools or exclusions, but the condition is clear and practical. A stronger version would contrast with pack_calculator or search_products, but the given guidance is sufficient for a competent agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds the context that it returns a URL and is intended for bulk/procurement review, but no additional behavioral details such as authentication or rate limits. This is adequate given the annotations.

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

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

Two sentences, direct and front-loaded. The first sentence states the action and resource, the second gives the usage context. 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?

Given the tool's simplicity, a 5-parameter schema with no output schema, the description sufficiently explains what it returns (a URL) and when to use it. It could mention how the URL should be used, but the purpose and usage are clear enough to invoke correctly.

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

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

Schema description coverage is 100%, so every parameter is already well-documented. The description adds only marginal meaning by tying the purpose to 'exact packaging spec or SKU,' but it does not explain any parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns a quote-request URL for a packaging spec or SKU, and explicitly notes it is for cases with no exact match or bulk/procurement needs. This distinguishes it from sibling tools like get_product or search_products.

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 a clear 'when to use' condition: 'Use when no exact match exists or the buyer needs bulk or procurement review.' It does not explicitly name alternatives or provide a 'when not' clause, but the condition implies when not to use it.

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

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

The description adds value beyond the readOnlyHint and openWorldHint annotations by detailing the response contents: create_cart_url arguments, SKU records, links, and a live-confirmation sequence. This gives useful behavioral context not present in annotations.

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

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

The description is a single, focused sentence that front-loads the core purpose ('Returns curated Packrift SKUs') and packs in meaningful details without fluff. Every phrase 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?

Despite lacking an output schema, the description enumerates the key return elements (URL arguments, SKU records, links, confirmation sequence), providing sufficient context for a read-only list tool with only optional parameters. It could mention pagination or list behavior, but the current detail is adequate.

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 67%, so the schema already explains sku and family. The description adds no parameter-specific meaning. The limit parameter lacks a schema description, but its type/default/range partially cover its semantics. With no param info added, the 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 clearly states the tool returns curated Packrift SKUs ready for cart handoff, with a specific verb ('returns') and resource. It distinguishes itself from siblings like create_cart_url by focusing on candidate selection rather than URL creation.

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 preparing cart handoff, but does not explicitly state when to use this tool versus alternatives like create_cart_url or get_product. No exclusions or alternative mentions are provided, leaving the usage context somewhat 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?

Annotations already flag readOnlyHint and openWorldHint; the description adds 'Never cached', clarifies the result is not the final payable amount, and notes checkout determines the true total. This goes beyond the structured annotations, though it does not address rate limits or response format.

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

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

Four sentences, front-loaded with purpose, and all information is relevant. It is compact but slightly dense with warnings at the end.

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

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

Given no output schema, the description could do more to explain what the response contains, and five optional parameters are unexplained. But the core call path (variant_ids + quantity) is clear enough to be minimally viable.

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

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

Schema coverage is only 29%, and the description only explains variant_ids and quantity, which the schema already documents. The remaining five parameters (journey_id, match_type, selected_sku, result_set_id, selected_handle) are left unexplained in both schema and description.

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

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

The description states a specific verb ('confirm'), a clear resource ('live base catalog unit price and merchandise line total'), and a usage stage ('before cart handoff'). It distinguishes itself from shipping/cart-finalization tools by explicitly excluding discounts, shipping, and tax, though it does not name sibling tools.

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

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

It tells the agent when to use the tool ('Use to confirm ... before cart handoff') and what it is not for (discounts, shipping, and tax are not evaluated). Missing explicit alternatives, so not a 5.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful return-content context (all variants, SKUs, dimensions, weight, stock). It does not mention error cases or rate limits, but for a read-only detail retrieval the provided transparency is 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?

Three concise, front-loaded sentences convey purpose, workflow position, and input without wasted words. Every sentence adds operational value.

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 simple single-parameter schema and no output schema, the description adequately covers intended usage and return contents. It could be more complete by defining 'handle,' but overall it provides sufficient context for an agent to invoke the tool effectively.

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 has 0% description coverage, and the description only says 'Input: handle.' It implies handle is an identifier but does not explain what constitutes a handle (e.g., slug, SKU, internal ID) or provide format examples. This leaves the agent to infer the 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 clearly states it pulls full product detail for a handle, listing variants, SKUs, dimensions, weight, and stock. This distinguishes it from sibling tools like search_products and find_packaging_for_item, which are preliminary lookup steps.

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 places the tool in a workflow: 'Use after find_packaging_for_item or search_products' and 'Call before building a cart to map qty to the right variant.' This provides clear when-to-use context and sequencing relative to alternatives.

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

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

Annotations already indicate readOnly, idempotent, and openWorld hints. The description adds value by detailing the exact output (reorder URL, product URL, copyable procurement spec) and the one-item scope, without contradicting the annotations.

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

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

The description is two sentences, front-loaded with the primary function, and includes only relevant usage guidance. 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 tool with 3 optional parameters and no output schema, the description provides a good overview of returned data and use cases. It does not cover edge cases like missing SKU/handle, but the annotations and schema fill in most gaps. Overall, reasonably 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 coverage is 100% with parameter descriptions, providing a baseline of 3. The description adds meaning by implying that sku and handle are alternative identifiers for a single item, which is not explicitly stated in the schema. It also clarifies the tool operates on one SKU or handle.

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 returns a reorder URL, product URL, and procurement spec for a single SKU or handle. It uses a specific verb and resource, and the mention of 'one catalog SKU or handle' distinguishes it from sibling tools like create_cart_url or get_bulk_quote_link.

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

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

The description explicitly says 'Use for repeat-buy and procurement handoff workflows,' providing clear context. However, it does not specify when not to use the tool or mention alternatives, so it falls short of a 5.

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

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

Annotations already mark it read-only, and the description adds important behavioral details: addresses are not validated, cart discounts and tax are not evaluated, and the estimate may be approximate when using placeholders. It also warns about variant_id type. This goes beyond the annotations and helps the agent set expectations.

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

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

The description is a single, information-dense paragraph that front-loads the usage condition and then covers key behaviors and requirements. Every sentence adds value; there is no filler. It could be slightly more structured, but it's 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 description covers the core functionality, required parameters, address behavior, and limitations. Since there is no output schema, it would be helpful to state the return format (e.g., a numeric estimate or object), but this is a minor gap. The description is largely sufficient for an agent to call 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?

With only 11% schema coverage, the description compensates by explaining the required arguments and the behavior of the destination_address object. It clarifies the variant_id string requirement and provides an example. Optional parameters like journey_id are not explained, but they are likely secondary. The description covers the critical parameters.

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

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

The description opens with a clear trigger condition ('Use when the buyer asks shipping cost for selected catalog variants') and specifies the resource (shipping estimate). It clearly distinguishes from pricing or inventory tools by focusing on shipping cost. The scope is well-defined.

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 (buyer asks shipping cost for selected variants) and provides conditional guidance on providing destination_address. It also sets expectations that the estimate is approximate without full address and that Shopify cart/checkout are authoritative, implying when not to rely solely on this tool. It doesn't name alternative tools explicitly but gives sufficient 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?

Beyond the readOnlyHint and openWorldHint annotations, the description adds useful context: 'live' indicates real-time data, and 'plain-language fulfillment summary' explains the output style. The caveat 'where available' is an honest disclosure of potential data gaps, which is valuable.

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

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

One sentence with a clear list of return values. No redundant phrasing and each clause adds information. Extremely 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 no output schema, so the return description is helpful. However, it omits guidance on how the four optional parameters relate (e.g., sku vs. variant_ids) and what quantity represents in an inventory query. Adequate but with clear gaps around parameter usage.

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 only 50%; the description does not explain the meaning or usage of quantity or variant_ids. It refers to variants collectively but not how to pass identifiers or how quantity is interpreted. It fails to compensate for the undocumented 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 it is for inventory exploration and lists specific return data (total quantity, available-for-sale state, warehouse-level quantities, fulfillment summary). This differentiates it from a generic inventory check via the 'warehouse-level' and 'plain-language' aspects, though 'exploration' is a somewhat imprecise verb.

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

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

Usage is implied (when you need inventory quantities for variants), but there is no explicit 'when not to use' or mention of alternatives like check_inventory. The phrase 'for one or more catalog variants' gives context but no exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, and the description adds context that this is an exploration tool, not for final confirmation. It does not contradict annotations and provides useful extra context about the tool's role in the workflow.

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 front-loads the tool's purpose and includes all key behavioral points without unnecessary words. It is 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?

The description provides a good high-level context but lacks detail on output format and specific parameter semantics. Given the tool has 7 parameters and no output schema, the description is somewhat incomplete for full decision-making, though it is adequate for basic selection.

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

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

With zero schema description coverage, the description must compensate but only mentions item dimensions and weight. It does not explain the roles of limit, use_case, or padding_in, leaving some parameters under-specified, though the core inputs are covered.

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 calculates required inside dimensions, ranks Packrift box/mailer candidates, and provides void-fill guidance. It distinguishes itself from siblings by positioning as an exploratory pre-confirmation tool, with a specific verb+resource structure.

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

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

The description clearly indicates when to use this tool ('before live price/inventory confirmation') and its exploratory nature, but it does not explicitly mention alternatives or when not to use it, so it falls short of full guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses key behavioral traits: it never places an order, it confirms live price and stock, and it requires a two-step confirmation process. This adds meaningful context that is not captured by annotations alone, helping the agent understand the side effects and state involved.

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 core purpose ('Two-step exact-SKU purchase prep'). It then explains the two-step flow in two clear sentences and ends with a boundary condition ('It never places an order'). Every sentence earns its place without redundancy.

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

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

The tool has moderate complexity with a two-step flow and no output schema, so the description carries the burden of explaining return behavior. It mentions the outcome ('tracked checkout handoff URL') and implies the first response includes product, live price, and stock. However, it doesn't explicitly describe the exact structure of the first response or possible error conditions, leaving a slight gap. Still, it is sufficiently complete for an agent to use 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 input schema already provides 100% coverage with descriptions for all six parameters, so the baseline is 3. The description adds a bit of context by explaining the role of buyer_confirmed in the two-step flow, but it does not add significant new semantics beyond what the schema already states. It reinforces the purpose of key parameters but does not compensate for any gaps.

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: 'Two-step exact-SKU purchase prep.' It specifies the verb ('prepare') and the resource ('purchase handoff'), and distinguishes itself from siblings by emphasizing the exact-SKU and two-step nature. The explicit statement 'It never places an order' further clarifies its scope, separating it from order-placing tools.

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

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

The description provides explicit step-by-step usage instructions: call first with buyer_confirmed=false to confirm product/price/stock, then call again with buyer_confirmed=true to receive the handoff URL. It also clarifies that no order is placed. While it doesn't explicitly name alternative tools, the two-step flow and confirmation requirement give clear context for when this tool is appropriate.

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

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

Annotations already indicate readOnly and openWorld hints. The description adds the return payload (price, stock, URL), which is useful behavioral info absent from the schema. It doesn't mention sorting or edge cases, but the annotation coverage lowers the burden.

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

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

Two sentences, front-loaded with the core use case, then the alternative, then return info. No filler 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?

For a simple 2-param tool with no output schema, the description covers when to use, what to expect, and an alternative. It lacks limit details and any mention of result ordering or no-match behavior, but is otherwise complete enough 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 coverage is 50% (query described, limit not). The description clarifies that query takes a category keyword, aligning with the schema. However, limit's meaning and behavior are not explained anywhere, so the description doesn't fully compensate for the gap.

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

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

The description clearly states the tool searches products by keyword/category, with concrete examples ('kraft tape', 'bubble mailer'). It explicitly distinguishes from find_packaging_for_item, making the scope 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?

Provides explicit when-to-use guidance: when user names a category by keyword with no dimensions. Also gives a direct alternative: 'For dimension-based fit, prefer find_packaging_for_item.' This is textbook usage guidance.

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