Packrift MCP

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

Annotations already provide readOnlyHint and openWorldHint. The description adds valuable behavioral context with 'Live, never cached,' which is not in the annotations. It also warns against sending variant_ids as numbers, which is a behavioral constraint beyond the schema. 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 concise and well-structured: it starts with the use case, then the required argument with an example, then a critical warning, and finally the live behavior. Every sentence earns its place and there is no fluff.

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 that there is no output schema and multiple optional parameters, the description adequately covers the primary usage with the required variant_ids and the live data behavior. It does not explain what the tool returns (e.g., stock status format) or the purpose of optional parameters, but the core scenario is sufficiently specified 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 only 17%, so the description must compensate. It does explain variant_ids format and strongly warns against sending numbers, which matches the schema description but adds emphasis. However, the other 5 optional parameters (journey_id, match_type, etc.) are completely unmentioned, leaving the agent without guidance on their semantics.

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

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

The description clearly states the tool's purpose: 'confirm stock before recommending a SKU or building a cart.' This is a specific verb+resource with a concrete use case. However, it does not explicitly differentiate from the sibling tool 'inventory_status', which likely has similar functionality.

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 clear context for when to use the tool ('before recommending a SKU or building a cart') and provides a critical usage requirement for variant_ids. It does not mention when not to use it or name alternative tools, so it misses the full 'when/when-not' guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the tool returns ranked candidates and a plain-language summary, which is useful behavioral information. However, it does not disclose potential no-match behavior or limitations beyond the schema's own note on competitor_reference, so it provides moderate extra value.

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 purpose and then output. Every word earns its place, with no redundant information. It is appropriately sized for the tool's clarity.

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 4 parameters and no output schema, the description covers core purpose, input types, and output format. However, given the large sibling list, it lacks comparative context to guide tool selection, and it does not specify edge-case behaviors (e.g., no matches, pagination). The presence of annotations and schema partially compensates, but the description isn't fully self-sufficient.

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

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

Schema description coverage is 50%, with requested_spec and competitor_reference described. The description adds context about what requested_spec can contain (packaging spec, competitor-style item, catalog-number), which enriches the primary parameter. Limit and family remain self-explanatory by name and enum, so overall the parameter meaning is adequate without further elaboration.

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 curated catalog, and returning ranked candidates plus a comparison summary. This is a specific verb+resource pairing, but it does not explicitly differentiate from sibling tools like search_products or explain_no_exact_match, so it misses the top score.

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 exploration and comparison but provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives or exclusions, leaving the agent to infer when to choose this tool over siblings such as find_packaging_for_item or search_products.

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

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

The description adds contextual behavior beyond annotations: 'never places an order' aligns with readOnlyHint and is a key behavioral trait. It also discloses the output (tracked packrift.com URL plus Shopify cart permalink) and the input preference. Annotations already cover readOnly/openWorld/idempotent, so the description adds non-redundant detail.

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 concise sentences: purpose, usage guidance, and output/behavior. Each sentence contributes distinct value with no redundancy. 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?

For a tool with 10 parameters and an anyOf constraint, the description provides the core mental model: two input paths, output format, and no order placement. It doesn't explicitly differentiate from similar siblings like prepare_purchase_handoff, but the schema covers parameter details and the description gives sufficient overall context.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema by explaining when to use sku vs items, that sku resolves the variant automatically, and that the tool returns a specific URL. This enriches the parameter understanding without merely repeating schema text.

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 specifically states 'Build the checkout handoff URL' with the exact context (confirmed product, quantity, live price, stock). It distinguishes from siblings by noting it never places an order and returns specific URL types. The input paths (sku vs items) are also clarified.

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?

Explicit guidance is given for when to use sku plus quantity versus items ('Preferred input is sku plus quantity; use items only when you already hold variant IDs as strings'). The prerequisite of buyer confirmation sets a clear usage window, though it doesn't explicitly name alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavioral context about the response (explanation, safe next actions, quote-request URL), which goes beyond the structured 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 entire description is a single front-loaded sentence that clearly states the action, purpose, and expected outputs. Every phrase earns its place without unnecessary detail.

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

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

With no output schema, the description adequately explains the return value (safe next actions and a quote-request URL). The tool's purpose and input context are clear, though optional fields like 'reason' and 'family' are not elaborated in the 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?

Schema description coverage is 100%, with all four parameters documented. The description adds context about 'requested_spec' and 'missing_or_mismatched_fields' but does not meaningfully extend beyond the schema definitions. 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 why... should not be presented') and identifies a clear resource (nearby product vs. buyer's spec) and output (safe next actions and quote-request URL). This distinguishes it from sibling tools like compare_alternatives or find_packaging_for_item, which have different goals.

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

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

The description implies the precise scenario (when a nearby product is not an exact match), giving clear context for use. However, it does not explicitly name alternative tools or provide when-not-to-use guidance, so it lacks full exclusion 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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral context by specifying the output: 'Returns up to 5 curated SKUs ranked by fit with price, stock, URL, and cart-continuity fields.' It also clarifies free-text use_case handling. No contradictions with 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 use case, then details requirements and output. Every sentence adds functional information with no redundancy or fluff.

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 compensates by naming the return fields (price, stock, URL, cart-continuity) and the result limit of 5 SKUs. It also explains input requirements and use_case mapping. It does not cover edge cases like no-match behavior, but sibling tools (explain_no_exact_match) suggest that gap is intentionally handled 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?

Schema description coverage is 100% for all five parameters, so the baseline is 3. The description lists required arguments and reiterates use_case canonical values, but adds little beyond the schema's existing parameter descriptions. It does not introduce any new parameter-level semantics.

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

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

The description clearly states the tool's purpose: finding packaging (box or mailer) for an item based on dimensions. It uses a specific verb ('find') and resource ('packaging'), and distinguishes it from siblings like search_products or pack_calculator by focusing on the buyer's dimensions and need.

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 opening phrase 'Use when the buyer has item dimensions and needs a fitting box or mailer' explicitly defines the trigger condition. It also explains how use_case values are canonicalized, giving the agent clear guidance on input preparation.

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

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

Annotations already declare the operation read-only, idempotent, and open-world. The description adds that it returns a URL, which is useful, but does not disclose additional behavioral details such as response format or external dependencies beyond what annotations already provide.

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 action ('Return a quote-request URL...'), and contains no filler. The use-case sentence earns its place by providing when-to-use guidance.

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

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

With no output schema, the description's mention of returning a URL partially covers the response. The use case and optional parameter roles are reasonably complete for a simple link generator, though it does not specify the URL format or how optional prefills (sku, family, etc.) affect the generated link.

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 covers 100% of parameters with descriptions, so the baseline is 3. The description does not add parameter-specific detail beyond referencing the spec/SKU concept already captured 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 identifies the tool as returning a quote-request URL for a packaging spec or SKU, and adds a use-case context ('Use when no exact match exists or the buyer needs bulk or procurement review'). The phrase 'exact packaging spec or SKU' is slightly ambiguous, but the verb and resource are specific enough to distinguish it from sibling handoff 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 explicitly states when to use the tool ('Use when no exact match exists or the buyer needs bulk or procurement review'), giving clear context. It does not name alternative tools, but the conditional phrasing implies the negative case (when an exact match exists, this tool is not 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 only say readOnlyHint and openWorldHint, so the description adds valuable context: the output includes a 'required live-confirmation sequence' and curated SKUs with specific link types. This goes beyond what annotations convey and describes the return content and selection criteria.

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

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

A single sentence that is information-dense and front-loaded with the main purpose, then lists the key output components without wasted words. Every clause earns its place.

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

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

With no output schema and moderate complexity, the description covers the main returned elements and the sequence requirement. It lacks details on interpreting the live-confirmation sequence or how the output integrates with create_cart_url, but for a read-only list tool it is 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 has 67% description coverage; limit lacks a description but has bounds. The description mentions 'SKU filter' indirectly but does not explain parameters like limit or family. It adds some context about output structure but not parameter-specific semantics, so it only partially compensates for the missing descriptions.

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 ('Returns') and resource ('curated Packrift SKUs that are ready for cart handoff'), and details what is included (create_cart_url arguments, SKU records, links, live-confirmation sequence). This clearly distinguishes it from siblings like get_product or check_inventory.

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 conveys the intended use case: obtaining candidates that are ready for cart handoff, implying this precedes create_cart_url. However, it does not explicitly name alternatives or state when not to use it, so it lacks exclusions but provides clear context.

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

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

Annotations already declare readOnlyHint=true, and the description adds the important behavioral trait that the tool is 'Never cached' and returns 'live' pricing. This goes beyond the annotations by explaining freshness semantics, which is valuable. No contradiction exists.

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 extremely concise—two sentences that front-load the primary purpose and critical usage constraints. Every sentence adds value, with no filler or repetition of obvious 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?

The tool has no output schema, and the description only partially explains what the response contains (unit price and line total). It omits any detail about response structure, error handling, or the roles of the five undocumented parameters. This is adequate for a simple pricing check but leaves clear gaps.

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

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

Schema description coverage is only 29%, and the description only discusses variant_ids and quantity, which are already well-described in the schema. It adds no new meaning for the other five parameters (journey_id, match_type, selected_sku, result_set_id, selected_handle), failing to compensate for the low coverage.

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

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

The description clearly states the tool's purpose: to confirm live unit price and line total before cart handoff. This is a specific verb+resource combination, and it distinguishes from sibling tools like check_inventory or create_cart_url by focusing on pricing confirmation.

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 clear context for when to use the tool ('before cart handoff'), which is a strong usage signal. It also provides a critical constraint ('Never send variant_ids as numbers'), but it does not explicitly enumerate when not to use it or name alternative tools, so it misses the top tier.

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 openWorldHint=true, so the safety profile is known. The description builds on this by specifying the data returned (all variants, SKUs, dimensions, weight, stock) and how to use the result (map qty to variant), which adds valuable 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?

The description is a concise two-sentence structure. The first sentence states the purpose and data returned, the second provides input and usage scenario. No filler words; 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?

Given the tool's simplicity (one param, no output schema, annotations covering read-only), the description is fairly complete. It covers when to use, what it returns, and how to apply it. It does not discuss error cases or the openWorldHint implications, but for a lightweight read operation these are acceptable omissions.

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 0% for the single required parameter 'handle'. The description only says 'Input: handle', which essentially repeats the schema. The context implies handle comes from search_products or find_packaging_for_item, but it does not explain what a handle is or its format, so the description fails to compensate for the lack of schema documentation.

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

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

The description clearly states the tool pulls full detail for a handle, listing specific fields (variants, SKUs, dimensions, weight, stock). It distinguishes itself from siblings by positioning itself as a follow-up to find_packaging_for_item or search_products, making its purpose unambiguous.

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

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

Explicit usage guidance is provided: 'Use after find_packaging_for_item or search_products' and 'Call before building a cart to map qty to the right variant.' This gives clear when-to-use context and implies the alternative (search tools are for discovery, this is for detailed retrieval).

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 safety profile is covered. The description adds the detail that the output includes a 'copyable procurement spec' and the exact URL types, but does not discuss edge cases or additional behavior beyond what annotations imply.

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

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

Two sentences, front-loaded with the output and use case; 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 read-only tool with rich annotations, the description provides the essential return types and usage context. It lacks output format details, but the absence of an output schema is mitigated by listing the key returned components.

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 descriptions for all three parameters (100% coverage). The description's phrase 'one catalog SKU or handle' reinforces the alternation but adds little beyond schema descriptions, so a 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 the specific verb 'Return' and names the exact outputs (reorder URL, product URL, procurement spec) scoped to 'one catalog SKU or handle', clearly distinguishing 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?

It explicitly states 'Use for repeat-buy and procurement handoff workflows', giving clear context for when to invoke. However, it does not name alternative tools or exclusion criteria, so it stops short of full when-to-use 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?

The annotations already declare readOnlyHint=true, so the agent knows it's safe. The description adds a valuable behavioral nuance: 'Never send variant_id as a number,' which prevents a common type error. It doesn't cover rate limits or failure modes, but with annotations present, this 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?

The description is two sentences, front-loaded with the trigger condition, and every sentence adds value. The example is compact and informative. No fluff.

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 8 parameters, but only 3 are required and the description covers those well, including a type warning. It does not detail optional parameters or return value, but the name and context make the output obvious (a shipping estimate). Given the moderate complexity and absence of an output schema, this is reasonably complete but not exhaustive, so a 4.

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 0%, so the description must compensate. It explains the key parameters: destination_postal_code, country (with US|CA), items, and the critical variant_id-as-string rule with an example. However, it does not describe optional parameters like journey_id, selected_sku, or match_type, leaving those undocumented. This is a partial compensation, earning a 3.

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

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

The description states a clear, specific use case: 'Use when the buyer asks shipping cost for selected catalog variants.' This includes a verb ('get shipping estimate'), a resource ('shipping cost'), and a scope ('selected catalog variants'), which distinguishes it from sibling tools like 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?

It explicitly states when to use ('Use when the buyer asks shipping cost...') and enumerates the required arguments. It lacks explicit when-not-to-use or alternatives, but the trigger condition is clear and the context is well defined, earning a 4 rather than 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 openWorldHint=true, covering the safety profile. The description adds useful context about the live nature of the data and the 'plain-language fulfillment summary' behavior. However, it doesn't disclose potential edge cases like what happens when inventory is unavailable or how the tool behaves with multiple variant_ids.

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

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

Two concise sentences front-load the core purpose and output. Every word adds value, and the description is appropriately sized for the tool's complexity.

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

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

The tool has no output schema and four optional parameters, but the description does not state that at least one identifier is required or how to choose among sku, handle, and variant_ids. It explains return values but not the invocation contract, making it incomplete 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?

Schema description coverage is 50% (sku and handle have descriptions; quantity and variant_ids do not). The description mentions 'one or more catalog variants' which partially relates to variant_ids, but it does not explain the role of 'quantity' or how the parameters interact. This is insufficient compensation for the missing parameter descriptions.

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: 'Live inventory exploration' with specific outputs (total quantity, available-for-sale state, warehouse-level quantities, fulfillment summary). The scope 'for one or more catalog variants' adds specificity, but it does not explicitly differentiate from the sibling tool 'check_inventory'.

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

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

No guidance is provided on when to use this tool vs alternatives. It does not mention any prerequisites, exclusions, or cases where another tool like 'check_inventory' would be more appropriate. The description implies general inventory exploration but lacks explicit usage direction.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, which inform the agent about safety and open-world behavior. The description adds context that the tool is exploratory and provides 'guidance' rather than final confirmed pricing, which is useful. However, it does not disclose details about return format, pagination, or any limitations beyond what annotations imply. This adds some value but not rich behavioral context, consistent with a mid-level score.

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 well-structured, with the primary action front-loaded in the first sentence ('Exploration tool for item dimensions and weight') followed by specific details. It contains no redundant or filler language, and every sentence contributes to understanding the tool's purpose and scope.

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 7 parameters, no output schema, and only basic annotations. The description explains the tool's purpose and workflow context but does not describe return values or how parameters affect results. Since there is no output schema, the description should provide more detail about what the agent can expect. It is adequate but leaves significant gaps for a complex 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 0%, so the description must compensate for the lack of parameter documentation. It mentions 'item dimensions and weight,' covering four of seven parameters, but does not explain limit, use_case, or padding_in. These are left entirely to the schema names and enum values. The description provides minimal additional meaning over the schema, insufficient for the number of parameters and zero coverage.

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

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

The description clearly states the tool's purpose with specific actions: 'Calculates required inside dimensions, ranks Packrift box/mailer candidates, and gives void-fill guidance.' It distinguishes itself from sibling tools by positioning as an exploration tool used 'before live price/inventory confirmation,' differentiating it from pricing and inventory 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 clear context on when to use the tool: as an exploration step before live price/inventory confirmation. It does not explicitly name alternatives or exclusions, but the phrase 'before live price/inventory confirmation' implies a specific workflow phase. This is clear context without explicit alternatives, matching the 'clear context, no exclusions' level.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds the critical two-step workflow and the requirement for buyer confirmation, which is not inferable from annotations alone.

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

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

Two sentences, front-loaded with the core purpose and flow. No superfluous content; 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?

Despite no output schema, the description states the final output (tracked handoff URL). The two-step protocol is fully described, and with complete schema coverage and annotations, the tool is sufficiently specified.

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

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

With 100% schema coverage, the baseline is 3. The description adds context around buyer_confirmed (set only after approval) and explains the overall flow, which helps parameter understanding beyond the schema.

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

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

The description clearly states a two-step exact-SKU purchase preparation tool, explaining both calls and that it never places an order. This distinguishes it from sibling tools like create_cart_url and get_cart_handoff_candidates.

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?

Explicit instructions: call first with buyer_confirmed=false to confirm details, then again with buyer_confirmed=true to get the handoff URL. It also clarifies it never places an order, providing a clear boundary. Alternatives are not explicitly named, 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 indicate readOnlyHint and openWorldHint, so the safety profile is covered. The description adds behavioral context by specifying that the result includes products with price, stock, and URL, which is useful since no output schema exists. It does not over-explain but provides relevant return information.

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

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

The description is two sentences: the first front-loads the desired usage scenario, the second succinctly states the return contents. Every sentence earns its place without redundancy or fluff.

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 search tool with readOnly/openWorld annotations and no output schema, the description covers the key aspects: when to use, what results include, and a sibling alternative. It could mention that results might be empty or paginated, but those are minor gaps given the tool's simplicity.

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 describes 'query' ('Free-text search; matches title, vendor, type, tags') and 'limit' constraints (default, min, max). The description reinforces that query is for category keywords but adds little extra meaning about parameters. With 50% schema description coverage, the description is not needed to compensate fully, and it does not mislead.

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 ('Search'), a resource ('products'), and the scope ('when the user names a category by keyword...'). It clearly distinguishes itself from sibling find_packaging_for_item by specifying 'with no dimensions' and pointing to that alternative for dimension-based fit.

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 declares when to use the tool ('Use when the user names a category by keyword... with no dimensions') and names the alternative for other cases ('For dimension-based fit, prefer find_packaging_for_item'). This is direct, actionable guidance.

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