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 (readOnlyHint, openWorldHint) already indicate safety and open-world behavior. Description adds that it returns a URL and does not place an order, but does not disclose side effects of openWorldHint or explain many parameters. 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: first defines purpose, second details usage and return value. Efficient and front-loaded, though could be structured with bullet points 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?

With 24 parameters, nested objects, and no output schema, the description is too brief. It does not explain most optional parameters or provide context for sibling differentiation beyond the basic usage. An agent would need more detail for correct invocation.

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

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

Schema description coverage is low (42%) with 24 parameters. Description only explains usage of sku, quantity, and items, adding marginal value over schema. Many parameters (ref, utm_term, etc.) lack any description in the tool description, failing to compensate for the low coverage.

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

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

The description clearly states it creates a cart URL for final checkout handoff after confirmation, and distinguishes from order placement by noting it does not place an order. It also provides usage guidance (sku vs items) that differentiates from sibling tools like get_cart_handoff_candidates.

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

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

Explicitly says when to use sku plus quantity vs items, and clarifies it does not place an order. Could be more explicit about when not to use relative to siblings, but the guidance is clear enough for most agents.

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?

Description adds behavioral context beyond annotations: returns up to 5 AI_APPROVE SKUs ranked by fit, includes price, stock, URL, and cart-continuity fields. Annotations confirm read-only and open-world, 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 wasted words. Front-loaded with usage context and required arguments. 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?

Description covers the main behavior and return structure. No output schema, but it explains the return fields. Missing error cases or pagination, but adequate for a straightforward search 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%, but description adds value: clarifies use_case enum meanings and notes that item_weight_lb should be 0 when unknown. This supplements the 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's purpose: finding packaging (box or mailer) for given item dimensions. The verb 'find' and resource 'packaging for item' are specific. It distinguishes from siblings like pack_calculator by focusing on returning 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') and lists required arguments. However, it does not explicitly mention when not to use or compare with alternatives like pack_calculator.

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 that the tool returns a URL (not a direct quote) and is tracked, which is useful context. 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?

Two sentences, front-loaded with the core purpose, no fluff. Every word earns its place.

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

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

Given 7 parameters and no output schema, the description is fairly complete. It explains when to use the tool and what it returns. The lack of output schema detail is acceptable as the URL nature is implied.

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

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

Schema coverage is 100% with descriptions for all parameters. The description does not add additional parameter semantics beyond what the schema provides. Baseline score of 3 applies.

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

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

The description clearly states it returns a tracked Packrift bulk quote URL for an exact requested packaging spec or SKU. It distinguishes from siblings like get_pricing or search_products by specifying the exact 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?

The description explicitly says 'Use when there is no exact match or the buyer needs bulk/procurement review,' providing clear context. It does not list exclusions or alternatives, but the context 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 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 indicate readOnlyHint=true and openWorldHint=true, so the description does not need to repeat that. The description adds the context that shipping costs are estimates for selected variants, which aligns with the safe-read nature. However, it does not disclose potential rate limits, data source freshness, or that results may vary (open world). The description does not contradict 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 with no wasted words. The description front-loads the purpose and then gives the precise format requirement. Perfectly concise while being informative.

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

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

The description covers the core use case and required parameters, but the tool has many optional parameters (journey_id, match_type, etc.) that are not explained. There is no output schema or description of the response format (e.g., what shipping cost fields are returned). Given the tool's complexity, more detail on optional inputs and output shape would improve completeness.

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 carries the full burden. It explains required parameters (destination_postal_code, country, items) and provides a detailed example for the items array, including the crucial instruction that variant_id must be a string, not a number. Optional parameters (journey_id, etc.) are not explained, but the core required ones are well-covered.

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

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

The description explicitly states the tool's purpose: 'Use when the buyer asks shipping cost for selected AI_APPROVE variants.' It clearly identifies the action (get shipping estimate) and the context (AI_APPROVE variants), distinguishing it from siblings like get_pricing that handle product prices.

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 when-to-use guidance: 'Use when the buyer asks shipping cost for selected AI_APPROVE variants.' It also specifies required arguments and format (e.g., variant_id as string). While it doesn't explicitly mention when not to use or list all siblings, the context is sufficient for most cases.

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.