Packrift Packaging

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

Description adds behavioral context beyond annotations: 'Never send variant_ids as numbers' and 'Live, never cached'. Annotations already declare readOnlyHint=true, so no contradiction. No mention of rate limits or auth, but sufficient for a read-only tool.

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

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

Two sentences and a brief instruction. Front-loaded with purpose, no wasted words. Every sentence adds value.

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

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

Despite no output schema, the description conveys the tool's role and data source (live, uncached). It is complete enough for the intended use case, but lacks details on return structure or error cases.

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 low (17%), but the description reinforces the required parameter format (array of string IDs). The schema already describes variant_ids similarly. Other parameters (journey_id, match_type, etc.) lack description in both schema and description, leaving gaps.

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

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

Description clearly states the tool confirms stock before recommending a SKU or building a cart. It uses a specific verb (confirm) and resource (stock). However, it does not explicitly distinguish from the sibling tool 'inventory_status', which may serve a similar purpose.

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

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

Provides clear usage context (before recommending SKU or building cart), required argument format, and data freshness ('Live, never cached'). Does not explicitly mention when not to use or alternatives, but the context implies it is for live checks.

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 include readOnlyHint=true and openWorldHint=true, indicating safe exploration and non-exhaustive results. The description adds that it is an exploration tool returning ranked candidates and a plain-language summary, which is consistent and adds 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 sentence that is front-loaded and directly communicates the tool's purpose and output without unnecessary words.

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

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

Given the tool has 4 parameters, no output schema, and annotations present, the description adequately covers the main purpose and output. It could be more specific about the comparison summary format, but overall 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 covers 50% of parameters with descriptions; the tool description does not add additional meaning to parameters beyond what is in the schema. However, it does clarify the output (ranked candidates + summary), which is not in the schema, providing some 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 it is an exploration tool for buyers comparing a packaging spec, competitor-style item, or Uline-style request against Packrift products, and specifies it returns ranked candidates and a comparison summary. This distinguishes it 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 comparing specs or competitor items, but does not explicitly state when to use this tool versus alternatives, nor does it provide when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint and openWorldHint. The description adds value by confirming it returns URLs and does not place an order, and mentions MCP attribution. No contradictions, but the description does not detail all behavioral aspects 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-load the purpose and usage. Every sentence earns its place: context, guidance, return value, and what it does not do. 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?

For a tool with 24 parameters, nested objects, and no output schema, the description is minimal. It covers the critical inputs and return value, but does not explain many optional parameters or the overall workflow. The openWorldHint suggests varied use cases not addressed.

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 low (42%). The description focuses on the two main input paths (sku+quantity vs items with variant_ids), adding context for these. However, it does not explain many other parameters (e.g., utm_term, journey_id, etc.), relying on the schema which is sparse.

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

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

The description clearly states it is the final checkout handoff after confirmation, returns a Packrift cart URL and Shopify permalink, and does not place an order. It distinguishes itself from sibling tools by specifying its role as the last step before purchase.

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

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

Provides explicit guidance: 'For most agents, use exact AI_APPROVE sku plus quantity. Use items only when you already have variant IDs as strings.' This tells when to use each parameter path, though it does not 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 the tool as read-only. The description adds that it returns 'safe next actions' and a 'tracked bulk quote URL', providing behavioral context beyond the annotations. It does not contradict the readOnlyHint.

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 primary action. It is efficient but could be slightly improved by adding more structure or clarifying what 'safe next actions' entail.

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 has 6 parameters and no output schema, the description does not fully explain the return format or the structure of 'safe next actions' and 'tracked bulk quote URL'. It is adequate but leaves some ambiguity.

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

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

The input schema has 100% description coverage, so the description adds no additional meaning to parameters. Baseline of 3 is appropriate as the schema already documents the parameters adequately.

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

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

The description clearly states the tool's purpose: to explain why a nearby product should not be presented as an exact match and then return safe next actions and a tracked bulk quote URL. This verb+resource structure distinguishes it from siblings 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 the tool is used when there is no exact match, but it does not explicitly state when to avoid using it or provide alternatives. The context is clear enough for an AI agent to infer appropriate usage.

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 that output is 'up to 5 AI_APPROVE SKUs ranked by fit' and explains free-text mapping for use_case, which 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?

Three sentences: usage condition, required arguments, return details. No filler; every sentence adds value. Front-loaded with key 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?

Covers purpose, required params, return format (up to 5 SKUs with specific fields). Lacks explanation of 'cart-continuity fields' and potential edge cases, but overall complete given no output schema.

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

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

All 5 parameters have schema descriptions (100% coverage). Description reinforces required arguments and details use_case, including canonical values and free-text mapping, adding value over 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?

Tool name and description clearly state verb (find) and resource (packaging for item). Sibling tools like pack_calculator or search_products serve different purposes, making this tool distinct.

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?

Description opens with 'Use when the buyer has item dimensions and needs a fitting box or mailer,' providing clear context. It does not explicitly list when not to use or compare to siblings, 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 declare readOnlyHint true and openWorldHint true. The description adds that the URL is 'tracked', which implies logging, but does not elaborate on side effects or permissions. With annotations present, the description provides marginal additional transparency.

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

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

Two sentences, no wasted words. The first states what it does, the second clarifies when to use. Very 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?

For a tool with 7 parameters and no output schema, the description is brief but covers the essential purpose and usage. Could elaborate on the return format or parameter interactions, but the high schema coverage mitigates this.

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 significantly add parameter semantics beyond stating the core purpose which aligns with the required parameter 'requested_spec'.

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 tracked bulk quote URL for a packaging spec or SKU. It distinguishes from siblings by specifying the use case: when there is no exact match or for 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?

Explicitly gives a clear context for use: 'when there is no exact match or the buyer needs bulk/procurement review.' Does not explicitly list alternatives but the context sufficiently guides selection 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?

Annotations indicate read-only and open-world behavior, and the description adds context about the output structure and required confirmation sequence, providing valuable behavioral insight 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 efficient sentence that conveys all key output components without redundancy, though it could be slightly restructured for 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?

Despite lacking an output schema, the description thoroughly explains the return structure and logic, covering all relevant aspects for a read-only tool with three 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 covers 67% of parameters with descriptions; the tool description does not add significant extra meaning to parameters beyond the schema, but it hints at usage via output context.

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 priority AI-approved SKUs for cart handoff, listing specific output components and distinguishing itself from sibling tools 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 implies this tool is a precursor to create_cart_url by mentioning it returns create_cart_url arguments, but it lacks explicit when-to-use or when-not-to-use guidance relative to siblings.

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

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

Annotations already indicate read-only (readOnlyHint: true) and open-world behavior. The description adds valuable behavioral context such as 'Never cached' and the requirement to encode variant IDs as strings, which are not captured in annotations.

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

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

The description is extremely concise, using four sentences that front-load the purpose and immediate guidance. Every sentence adds value, with zero redundancy or filler.

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

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

Given the tool's complexity (7 parameters, no output schema), the description covers the core goal and key constraints. It implies the response includes price and total, but omits details about other optional parameters and output structure, leaving minor gaps.

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

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

With only 29% schema description coverage, the description compensates by explaining the required 'variant_ids' format (example provided) and the optional 'quantity' default. However, five other parameters (journey_id, match_type, etc.) are left unexplained, reducing overall semantic clarity.

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 uses a specific verb ('confirm'), identifies the resource ('unit price and line total'), and distinguishes itself from sibling tools like get_product or check_inventory by emphasizing its role in the cart handoff flow.

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 on when to use the tool ('before cart handoff') and includes critical instructions like 'Never send variant_ids as numbers' and 'Never cached.' However, it does not mention when not to use it or suggest alternative tools for similar tasks.

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 description's addition of specific data fields (variants, SKUs, dimensions, etc.) adds transparency beyond annotations. No contradictions; behavior is well disclosed.

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

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

Three sentences, front-loaded with purpose, then usage. Every sentence provides value; no fluff. Efficient and clear.

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

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

For a simple, read-only tool with one parameter and no output schema, the description covers purpose, usage order, and behavioral details. It is complete enough for an agent to select and invoke correctly. Could mention expected output structure, but not required.

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%, yet the description only says 'Input: handle' without explaining what handle is (e.g., product handle format, required pattern). While it implies handle is a product identifier, it does not add meaningful parameter detail beyond the schema's bare minimum.

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: 'pull full detail for a handle: all variants, SKUs, dimensions, weight, stock.' It uses a specific verb and resource, distinguishing it from sibling tools like search_products and find_packaging_for_item.

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

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

The description explicitly says 'Use after find_packaging_for_item or search_products' and 'Call before building a cart to map qty to the right variant,' providing clear when-to-use and contextual ordering. It does not mention when not to use, but the guidance is strong.

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 and openWorldHint. The description adds that it returns three pieces of data (URLs and text) but does not elaborate on side effects, authorization needs, or external dependencies 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 concise sentences: the first states what the tool returns, the second specifies its usage. No extraneous information.

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 adequately lists the returned items. It lacks guidance on choosing between SKU and handle and does not mention authentication, but overall it is sufficient for a straightforward retrieval 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 coverage is 100%, so baseline is 3. The description does not add meaningful detail beyond the schema; it merely restates that the tool operates on SKU or handle. No explanation is given for source_context, analytics_context, or suppress_analytics.

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

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

The description clearly states the tool returns a reorder URL, product URL, and copy-procurement-spec text for a given SKU or handle. It uses specific verbs and resources, though it does not explicitly differentiate from sibling tools like get_product 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?

The description explicitly states 'Use for repeat-buy and procurement handoff workflows,' providing clear context. However, it does not mention when not to use or provide 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=true and openWorldHint=true, indicating a read-only operation with external dependencies. The description adds minimal behavioral context beyond this, such as not mentioning that it queries external carriers or returns real-time estimates. With annotations, a score of 3 is appropriate as the description does not contradict but adds little extra.

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 plus an example, front-loaded with usage condition and critical details. Every word is necessary and efficiently imparts key information without verbosity.

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, no output schema, and no description of what the response contains (e.g., estimate amount, carrier details). Optional parameters are completely ignored. For an agent to reliably use this tool, more context about the output and less critical parameters is needed.

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 coverage, the description compensates well for required parameters: it explains destination_postal_code, country, and items, including a warning about variant_id type. However, it does not explain optional parameters like journey_id or match_type, leaving gaps for non-required fields.

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: getting shipping cost for selected AI_APPROVE variants. The verb 'get' and noun 'shipping estimate' are specific, and this purpose distinguishes it from sibling tools like get_pricing or get_product.

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 the buyer asks shipping cost for selected AI_APPROVE variants') and provides required arguments with a concrete example. However, it does not mention when not to use the tool 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 provide readOnlyHint and openWorldHint. The description adds value by explaining the AI_APPROVE gating and attribution recording behavior. However, 'records low-cap test attribution' might imply a side effect, potentially contradicting readOnlyHint, but overall the behavioral context is strong.

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

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

The description is three sentences, front-loaded with purpose and usage guidance. Every sentence adds value without unnecessary detail. Highly concise and structured.

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

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

Given the tool has 6 parameters, no output schema, and many siblings, the description covers essential aspects: purpose, when to use, what it returns (AI_APPROVE candidates), and attribution recording. It could potentially explain the return format more, but for a test tool it's sufficiently 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?

All parameters have schema descriptions (100% coverage), so the baseline is 3. The description does not add new parameter semantics beyond what the schema already provides. The schema descriptions are clear, and the description doesn't need to repeat them.

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: it's a controlled test for Google Retail/AI Commerce search, finds buyer matches, returns AI_APPROVE-gated cart-handoff candidates, and records test attribution. It distinguishes from sibling 'search_products' by specifying this is for pilot testing before normal search.

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 to use this for the Gemini/Retail pilot before normal search_products when testing Google Retail search quality. This provides clear context for when to use and implies that search_products is the alternative for production use.

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 indicate readOnlyHint=true and openWorldHint=true, which align with the description's mention of 'live' exploration. The description adds valuable behavioral details beyond annotations, such as specific data returned (location-level BOX quantities, fulfillment summary). No contradictory 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, front-loaded with the tool's purpose and output. It is concise and to the point, with no unnecessary details. Slightly more action-oriented language could improve it.

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 4 parameters, no output schema, and no nested objects, the description provides a reasonable overview of return values. However, it lacks details on how parameters interact (e.g., multiple variant_ids) and does not mention error cases or optionality. Adequate but not fully complete.

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

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

Schema description coverage is 50%, so the baseline is 3. The tool description does not elaborate on parameters like 'quantity' or 'variant_ids' beyond what the schema provides. It mentions 'one or more variants', implying variant_ids usage, but adds no further semantic meaning.

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

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

The description specifies the tool is for inventory exploration of 'AI_APPROVE variants' and lists what it returns (Shopify total quantity, available-for-sale, etc.). It provides a clear resource and action, though the verb 'exploration' is less direct than 'get' or 'check'. It distinguishes from the sibling 'check_inventory' by mentioning specific return fields.

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

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

The description implies the tool is for AI_APPROVE variants, providing some context, but it does not explicitly state when to use this tool over siblings like 'check_inventory' or 'search_products'. No exclusions or prerequisites are mentioned.

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 and open-world. The description adds that it calculates dimensions, ranks box/mailer candidates, and provides void-fill guidance, clarifying the tool's exploratory nature. 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 sentences with no redundancy. Front-loaded with the core purpose, followed by specific outputs. Every word adds value.

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

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

For a tool with 7 parameters (3 required) and no output schema, the description gives a high-level overview but lacks details on return values, ranking criteria, or error conditions. Adequate for basic selection but incomplete for full understanding.

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%, and the description provides no explanation of any parameter, such as 'limit', 'use_case', or 'padding_in'. The agent must infer meaning from parameter names alone.

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

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

The description clearly states it is an exploration tool for item dimensions and weight, calculating inside dimensions and ranking candidates. It differentiates itself from purchase/confirmation tools by mentioning 'before live price/inventory confirmation'. However, it does not explicitly distinguish from the sibling tool 'find_packaging_for_item'.

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

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

The description implies it's for initial exploration before price/inventory confirmation, but does not specify when not to use it or mention alternatives like 'find_packaging_for_item' or 'check_inventory'.

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 context by explaining the two-phase behavior and that it returns a cart URL, not an order placement. It could be more explicit about what happens internally (e.g., live fetches) but overall good.

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

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

Three sentences, front-loaded with purpose, then process. No unnecessary words. Efficient and clear.

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?

Considering the tool's complexity (15 params, two-phase workflow, no output schema), the description covers the core workflow and return value. It could mention what the first call returns (e.g., price/inventory confirmation) for completeness, but overall 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?

The description adds meaning for key parameters: sku, quantity, and especially buyer_confirmed with its condition. Schema coverage is 53%, so many parameters are not explained, but the description focuses on the critical ones. A bit more detail on other params would push to 5.

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 'exact-SKU purchase prep' and explains the two-call pattern. It distinguishes itself from siblings by being the 'preferred' prep tool and explicitly stating it does not place an order, contrasting with order placement tools.

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

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

The description provides explicit guidance on when to call: first with buyer_confirmed=false to confirm product, price, inventory; then with buyer_confirmed=true only after buyer approval. It does not explicitly name alternatives or when not to use, but the process 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 provide readOnlyHint and openWorldHint, so description doesn't need to restate. It adds return fields but no behavioral details beyond that. 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, front-loaded with usage condition, no filler.

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

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

Given low complexity (2 params, no output schema), description covers purpose, usage, and return value adequately.

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 describes query and limit partially. Description adds that search is by keyword for categories, but doesn't enhance param meaning beyond schema. 50% coverage baseline 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?

Clear verb and resource: 'search products' and explicitly states it returns products with price, stock, URL. Distinguishes from sibling find_packaging_for_item by scope.

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 (keyword category search with no dimensions) and when to prefer alternative (find_packaging_for_item for dimension-based fit).

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