Packrift MCP

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds a key behavioral trait: 'Live, never cached,' which aligns with openWorldHint. This adds value beyond annotations but does not cover other aspects like rate limits, permissions, or side effects.

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

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

The description is concise (two sentences) with the key message front-loaded. It wastes no words but could be slightly more structured by separating the usage context from the parameter format note.

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 and low schema coverage, the description is incomplete. It fails to explain the return value (e.g., stock levels), the role of optional parameters, or how the tool integrates with the broader workflow. An agent would lack sufficient context for robust 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% (1 of 6 parameters described). The description explains that variant_ids must be strings and provides an example, which reinforces the schema. However, the other 5 parameters (journey_id, match_type, etc.) are left entirely unexplained, leaving significant ambiguity.

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 purpose: 'confirm stock before recommending a SKU or building a cart.' It includes a specific verb ('confirm') and resource ('stock'), linking to a real-world use case. However, it does not explicitly differentiate from the sibling tool 'inventory_status', which may serve a similar function.

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

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

The description explains when to use the tool (before recommending a SKU or building a cart) and provides critical formatting guidance for the required argument (variant_ids as strings). However, it does not mention when not to use it or suggest alternative tools for other scenarios.

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=true and openWorldHint=true. The description adds that the tool returns ranked candidates and a comparison summary, which is the key behavioral output. No contradictions exist, and the description effectively complements 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 single concise sentence divided into two clear clauses. It front-loads the purpose ('Exploration tool for buyers comparing...') and wastes no words. Every part 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 complexity (4 parameters, no output schema), the description covers the core purpose and outputs. It does not explain ranking criteria or differentiate from siblings, but as an exploration tool the context is sufficient for an agent to understand expected behavior.

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

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

Schema coverage is 50% (requested_spec and competitor_reference have descriptions). The tool description reinforces the meaning of requested_spec by mentioning 'packaging spec, competitor-style item, or Uline-style request', but does not cover limit or family parameters. It adds moderate value beyond the schema but does not fully compensate 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 purpose: comparing a packaging spec, competitor-style item, or Uline-style request against Packrift AI_APPROVE products, and returning ranked candidates plus a plain-language summary. It uses a specific verb ('comparing') and resource, and its purpose is distinct from sibling tools like search_products 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?

The description implies usage for buyers comparing specs but does not explicitly state when to use this tool versus alternatives. No exclusions or alternative sibling tool names are mentioned, leaving the agent to infer context. This is adequate but lacks explicit 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 declare readOnlyHint and openWorldHint. The description adds that the tool 'does not place an order', which is a key behavioral disclosure beyond the annotations. It also describes the output (a cart URL). However, it fails to mention analytics tracking implied by the 'suppress_analytics' parameter, which is a notable omission.

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

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

The description is a single, concise paragraph that front-loads the purpose, then provides usage guidance, and ends with output behavior. It is appropriately sized for the complexity, though a list format could improve scannability for agents.

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 complexity (24 params, nested objects, no output schema), the description adequately covers the core workflow (sku vs items, no order placement). However, it lacks context on when to use this tool over siblings like 'get_cart_handoff_candidates' or 'prepare_purchase_handoff', and does not explain the purpose of many 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 coverage is 42%, so the description carries burden for many parameters. It explains 'sku' and 'items' well, noting that 'sku' is a shortcut for exact SKUs and 'items' is for variant IDs. But 24 parameters exist, and the description does not clarify optional fields like 'utm_term', 'journey_id', or 'discount_code', leaving their purpose to sparse schema 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 identifies the tool as the final checkout handoff after product and buyer confirmation. It distinguishes between using sku for most agents and items for those with variant IDs, and explicitly states it returns a cart URL, not an order, which differentiates it from other tools like 'prepare_purchase_handoff'.

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 guidance: 'For most agents, use exact AI_APPROVE sku plus quantity' and 'Use items only when you already have variant IDs as strings.' This helps the agent choose parameter paths. However, it does not directly compare to sibling tools like 'get_cart_handoff_candidates' or explain when not to use this tool.

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

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

Annotations declare readOnlyHint true, but the description mentions returning a 'tracked bulk quote URL,' which may imply a side effect or mutation, contradicting the annotation. The description does not clarify whether tracking involves state changes or external calls, leaving behavioral ambiguity.

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

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

The description is a single concise sentence covering the tool's key actions without redundancy. It is front-loaded with the primary purpose, though it could be structured with more detail on outputs.

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 6 parameters including nested objects, no output schema, and no explanation of return format, the description is incomplete. It fails to clarify the structure of 'safe next actions' or the role of parameters like analytics_context and suppress_analytics.

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

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

Schema coverage is 100%, so parameters are well-documented in the schema. The description does not add any additional meaning or usage hints beyond what the schema provides, meeting the baseline for high 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 explains why a nearby product is not an exact match and returns safe next actions and a tracked bulk quote URL. It distinguishes itself from sibling tools like get_bulk_quote_link by including explanation and next actions, though the purpose could be more specific.

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

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

The description implies usage when there is no exact match, but it does not explicitly state when to or not to use this tool, nor does it mention alternatives like search_products or get_bulk_quote_link. The context is clear but lacks exclusionary 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 provide readOnlyHint and openWorldHint. Description adds behavior: 'Returns up to 5 AI_APPROVE SKUs ranked by fit with price, stock, URL, and cart-continuity fields.' This goes beyond 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 two sentences, front-loaded with the usage scenario and followed by required arguments and output. Efficient and clear, though could be slightly more structured.

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

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

Given 5 required parameters, no output schema, and annotations, the description is fairly complete. It explains the return value (up to 5 SKUs, specific fields). It does not explain ranking criteria, but that may be acceptable.

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%; all parameters have descriptions in the schema. The description restates required parameters and adds context for use_case. Compared to siblings, it does not add significant new meaning beyond the schema.

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

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

The description clearly states the purpose: 'Use when the buyer has item dimensions and needs a fitting box or mailer.' It specifies the verb 'find' and the resource 'packaging for item'. It distinguishes from siblings by focusing on dimensional fit and returning AI-ranked SKUs.

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 states when to use: 'when the buyer has item dimensions and needs a fitting box or mailer.' Lists required arguments and use_case enum. Does not explicitly contrast with sibling 'pack_calculator', 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 indicate readOnlyHint=true and openWorldHint=true, so the description is consistent. It adds value by noting the tool 'returns a tracked URL', which is behavioral context not in annotations. No contradiction.

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, directly stating what the tool does and when to use it. No extraneous words; each sentence serves a purpose.

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 7 parameters and no output schema, the description provides essential context: purpose, condition, and output type. The schema handles parameter details. It is complete enough for an agent to understand when to invoke this tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description does not add additional meaning beyond mentioning 'exact requested packaging spec or SKU', which maps to existing schema descriptions. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Return' and the resource 'tracked Packrift bulk quote URL', and specifies the condition 'for an exact requested packaging spec or SKU'. It also distinguishes from siblings by mentioning 'bulk/procurement review'.

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 this tool: 'Use when there is no exact match or the buyer needs bulk/procurement review.' This provides clear context and implies when not to use (e.g., when an exact match exists).

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

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

Annotations already declare readOnly and openWorld hints. Description adds significant behavioral context: what the response contains (arguments, records, links, live-confirmation sequence) and that it's AI-filtered and priority-based.

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?

Single sentence packs all essential information, but could benefit from structured breakdown for easier parsing by an AI agent. No wasted words.

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

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

Covers purpose, input options, and output contents, including the live-confirmation sequence. Slightly incomplete regarding limit behavior and pagination, but adequate for the tool's complexity.

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

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

Schema coverage is high (67%), so baseline is 3. Description does not add additional meaning or constraints beyond the schema for parameters like sku, limit, or family.

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?

Clearly states it returns priority AI-approved SKUs ready for handoff, including specific elements like create_cart_url arguments and links, distinguishing it from sibling tools like check_inventory or create_cart_url.

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?

Implied usage for selecting SKUs ready for cart handoff exploration, but lacks explicit alternatives or when-not-to-use guidance. Context is clear enough.

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

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

Annotations already declare readOnlyHint and openWorldHint, indicating safe reads and variable results. The description adds 'Never cached,' which is important for agents to know that each call fetches fresh data. This adds behavioral context beyond annotations. No contradiction with annotations is present.

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 at three sentences. The first sentence states purpose, the second specifies the required argument and format, and the third mentions optional quantity and a key behavioral note ('Never cached'). It is front-loaded with the most important information and contains no superfluous text.

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 but only 1 required; the description adequately covers the essential ones for usage. There is no output schema, so the description does not explain return values, but it implies what is returned ('live unit price and line total'). Additional details on the five unused parameters would enhance completeness, but the core functionality is sufficiently covered.

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 low (29%), so the description must explain parameters. It covers two key ones: variant_ids (required string array with example) and quantity (optional integer, default 1). However, five other parameters (journey_id, match_type, selected_sku, result_set_id, selected_handle) are not described at all, leaving gaps. The description adds value for critical parameters but is incomplete.

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 live unit price and line total before cart handoff.' It specifies the verb 'confirm' and the resource 'live unit price and line total,' and the context 'before cart handoff' differentiates it from sibling tools like 'prepare_purchase_handoff'.

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 usage guidance: 'Required argument: variant_ids as an array of numeric Shopify variant IDs encoded as strings' and 'Optional quantity defaults to 1.' It also gives a usage scenario ('before cart handoff') and a constraint ('Never cached'). However, it does not indicate when not to use this tool or mention alternatives, slightly reducing 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 indicate readOnlyHint and openWorldHint. The description adds value by specifying the returned data (variants, SKUs, dimensions, weight, stock), enhancing transparency beyond annotations. No contradiction.

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 with no wasted words. The first sentence defines action and output, the second provides usage context. Perfectly front-loaded and 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?

Given no output schema, the description covers return fields and usage sequence. It doesn't discuss limits or edge cases, but for a simple read tool with annotations, 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 coverage is 0% (no description for 'handle'), but the description explains 'Input: handle' and implies it's the product handle from prior tools. This partially compensates, though lacks format details.

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

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

The description clearly states the tool retrieves full detail for a handle, listing specific attributes (variants, SKUs, dimensions, weight, stock). It distinguishes its role by referencing sibling tools as prerequisites, making the purpose unambiguous.

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

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

The description explicitly instructs to use this tool after find_packaging_for_item or search_products and before building a cart. While it doesn't list alternatives or exclusions, the context is clear and actionable.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, so the description is not required to disclose safety. The description adds that it returns URLs and text, which is consistent with read-only. No behavioral traits beyond what annotations imply are described, but 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 two sentences, front-loaded with the primary action and result. No redundant words; every sentence adds value for the agent.

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 presence of 5 optional parameters and no output schema, the description provides enough context for the intended use case. However, it lacks details on parameter precedence (sku vs handle) and the exact structure of the returned data, which could be helpful.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description does not add further meaning to parameters, so baseline score of 3 is appropriate.

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

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

The description clearly states it returns a reorder URL, product URL, and procurement spec text for a PKU or handle. It specifies the context of AI_APPROVE and workflows (repeat-buy, procurement handoff), distinguishing it from siblings like get_product 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 explicitly says 'Use for repeat-buy and procurement handoff workflows,' which provides clear context for when to use the tool. However, it does not mention when not to use it or name alternative tools for different scenarios.

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. The description adds no behavioral context beyond input format warnings (e.g., variant_id as string). It does not explain that the estimate may come from an external carrier API, any latency, or failure modes. With annotations present, the description could have added useful context but fails to do so.

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 with no wasted words. The first sentence states the use case, and the second covers required arguments and a critical caution ('never send variant_id as a number'). It is front-loaded and 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?

Given 8 parameters, no output schema, and 0% schema coverage, the description is inadequate. It does not describe the return value, error conditions, or optional parameters. Users are left without information on how to set optional fields or interpret results. Only the core required parameters are covered.

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 thoroughly explains the required parameters (destination_postal_code, country, items) including type constraints and an example. However, it ignores 5 optional parameters (journey_id, match_type, etc.), leaving their purpose unclear. The description adds value for required params but is incomplete for optional ones.

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 get a shipping cost estimate when a buyer asks. It specifies the condition 'for selected AI_APPROVE variants,' making the context precise. However, it does not explicitly differentiate from sibling tools like check_inventory or compare_alternatives, which could also be related to product selection.

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 a clear usage scenario ('when the buyer asks shipping cost') and lists required arguments, but it does not mention when not to use this tool or compare it to alternatives. The sibling list is large, and no guidance is given for choosing this tool over others like pack_calculator or get_pricing.

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. The description adds behavioral context beyond annotations: 'returns AI_APPROVE-gated cart-handoff candidates' and 'records low-cap test attribution', disclosing filtering and recording behavior. No contradiction 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?

Description is two sentences, front-loaded with purpose. Could be slightly more concise, but overall efficient with no wasted words.

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

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

Given 6 parameters (1 required, no output schema), the description covers purpose, context, and references sibling tool. Schema descriptions are comprehensive. The description is complete enough for an agent to understand scope and 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 100% with detailed parameter descriptions (e.g., 'Buyer search such as 22x20x14 corrugated boxes'). The tool description adds little beyond schema examples (query examples). Baseline 3 is appropriate as schema carries the weight, and description provides minimal extra value.

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 ('finds', 'returns', 'records'), resource ('Google Retail catalog', 'AI_APPROVE-gated cart-handoff candidates'), and distinguishes it from sibling tool 'search_products' via 'before normal 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?

Explicitly says 'Use this for the Gemini/Retail pilot before normal search_products when testing Google Retail search quality', providing clear context for when to prefer this tool over alternatives. Does not explicitly list when not to use, but the guidance is sufficient.

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. The description adds valuable detail on return fields (Shopify total, available-for-sale, warehouse quantities, fulfillment summary). This provides sufficient behavioral context beyond 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, concise sentence that front-loads the core purpose ('Live inventory exploration'). It packs multiple return elements without being verbose, earning its length.

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?

While output details are well-covered, input specification is incomplete. The description does not explain how to use the four parameters together, nor does it note that 'quantity' is optional with a default. No output schema is provided, but the description compensates partially.

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 50% schema coverage, the description does not clarify parameter semantics. It does not explain the role of 'sku', 'handle', 'quantity', or 'variant_ids' in specifying inventory scope, leaving the agent to rely solely on the limited schema 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 is for live inventory exploration of AI_APPROVE variants, listing specific return data. However, it does not differentiate from similar sibling tool 'check_inventory', so it lacks sibling distinction.

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 on when to use this tool versus alternatives like 'check_inventory'. The description does not mention use cases, prerequisites, or exclusions.

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

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

The description adds value beyond the annotations (readOnlyHint, openWorldHint) by explaining the operational behavior: it calculates dimensions, ranks candidates, and gives guidance. This gives the agent context that the tool is exploratory and not final, which aligns with the annotations indicating safe, open-world results.

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, consisting of two sentences that front-load the primary function. However, it could be slightly more structured (e.g., bullet points) to improve readability, though it remains 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 is incomplete given the tool's complexity (7 params, no output schema). It does not describe the return value structure, leaving the agent unsure what to expect. The omission of output details and parameter semantics hinders effective 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?

With 0% schema description coverage, the description should compensate by explaining the parameters' roles. It mentions 'item dimensions and weight' but does not describe individual parameters like 'limit', 'use_case', or 'padding_in'. The agent lacks guidance on how these parameters affect the calculation or ranking.

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 that the tool is an exploration tool for item dimensions and weight, calculating inside dimensions, ranking Packrift box/mailer candidates, and providing void-fill guidance. It distinguishes itself from sibling tools by specifying it is used 'before live price/inventory confirmation', setting it apart 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 this tool ('before live price/inventory confirmation' and as an 'exploration tool'), implying it should be used to assess packaging options before committing to a final selection. However, it does not explicitly state when not to use it or name specific alternatives among 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?

The description adds behavioral context beyond annotations: it explains the two-step process, the condition for returning a cart URL (only when buyer_confirmed=true), and explicitly states it does not place an order. Annotations are readOnlyHint and openWorldHint, which are consistent with not modifying state.

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 clear, front-loaded sentences with no wasted words. It efficiently conveys purpose, usage flow, and a key constraint.

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 main workflow but lacks details on error handling, prerequisites, or what other parameters do. Given the complexity (15 params, no output schema), it is adequate but has gaps.

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

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

The description explains key parameters (sku, quantity, buyer_confirmed) and their roles in the workflow, adding meaning beyond schema. However, with 53% schema coverage and 15 parameters, many (like journey_id, mcp_source) are not covered, so the description does not 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 is for purchase preparation with a two-step process: first call with buyer_confirmed=false to confirm product and pricing, then with buyer_confirmed=true to get a cart URL. It specifies it does not place an order, distinguishing it from siblings like create_cart_url.

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 instructions on when to call with false vs true, and that it is the preferred method for exact-SKU purchases. However, it does not mention when not to use this tool or list alternatives, though siblings provide 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 openWorldHint=true, covering safety and non-exhaustiveness. The description adds that it returns products with price, stock, URL, which is helpful but does not disclose additional behavioral traits. No contradiction 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?

Two sentences, front-loaded with usage and alternative, and includes return fields. Every sentence adds value with no wasted words.

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

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

Given the tool's simplicity (two params, no output schema), the description is fairly complete: it states the search scope, return fields, and key differentiator. It could mention ordering or empty results, but with openWorldHint and sibling tools, it 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 50%: 'query' has a description, 'limit' does not. The description does not add any parameter-specific information beyond what the schema provides for 'query', and does not mention 'limit' at all. Baseline for 50% coverage is 3, and without compensatory details, it stays at 3.

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

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

The description clearly states it searches products by keyword category with no dimensions, and explicitly distinguishes from find_packaging_for_item. It specifies the verb 'search' and resource 'products', and what it returns.

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

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

The description explicitly says 'Use when the user names a category by keyword... with no dimensions' and provides an alternative: 'For dimension-based fit, prefer find_packaging_for_item.' This gives clear when-to-use and when-not-to-use guidance.

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