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

No annotations provided, so description bears full weight. It discloses append behavior (reads current note, concatenates with two newlines) and replace behavior (overwrites), plus the extra read query for append. Lacks info on auth or rate limits, but core mutation behavior is well covered.

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 short (three sentences) but lacks parameter details, leaving gaps. It could be more concise by including param info without adding length. Every sentence earns its place but doesn't cover all necessary info.

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 3 parameters, 0% schema coverage, and no output schema, the description is incomplete. It does not specify return values (e.g., does it return the updated customer?), nor validate id format. A mutation tool needs 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 coverage is 0% (no param descriptions in schema). Description only explains 'mode' parameter (enum values behavior). Does not describe 'id' (presumably customer ID) or 'note' (text to add). Agents get no extra meaning for these critical parameters beyond schema field names.

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 'Add a note to a customer' with specific verb and resource. It distinguishes from sibling 'shopify_add_order_note' by targeting customers, and explains two modes (append, replace) with concrete behavior.

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 on when to use append vs replace, including performance implication (extra read query). Does not compare with alternative tools like update_customer, but context from sibling names makes usage 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?

No annotations provided, so description carries full burden. It discloses append behavior (reads current note, concatenates) and extra query cost. Lacks details on permissions or idempotency, but adequate for the action.

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 purpose, then details. Every sentence earns its place.

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

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

Adequately covers purpose, modes, and effects for a simple tool. No output schema, so return value not described, but not critical. Could mention expected response.

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%, but description adds meaning: explains mode values (append/replace) and behavior. Does not elaborate on id or note format, but clarifies their roles.

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 adds a note to an order, specifies two modes (append/replace), and lists required params. It distinguishes from siblings like shopify_add_customer_note by focusing on orders.

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?

Explains when to use append vs replace, and notes that append makes an extra read query. Does not explicitly exclude alternatives, but context is clear.

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

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

No annotations provided, but description discloses idempotency and return value (updated product + userErrors). Does not cover permissions or error handling beyond userErrors, but adequate for a simple mutation.

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; first sentence gives purpose, second adds constraints and return info.

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 2-param tool with no annotations, description covers action, idempotency, and return type. Lacks output schema but returns are described. Adequate for context.

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

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

Schema coverage is 0%, but description adds that tags must be a non-empty array and productId required. Provides basic meaning but no 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?

Clearly states 'Add one or more tags to a product' with specific verb and resource, distinguishing from sibling tools like shopify_remove_product_tag.

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?

Implies usage for adding tags, but lacks explicit when-not-to-use or alternatives. However, the purpose is self-evident given the name and 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?

No annotations are provided, so the description must cover behavioral traits. It mentions defaults and optional parameters, but does not disclose potential side effects, rate limits, or authentication needs. Basic transparency but not comprehensive.

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 concise sentences, front-loaded with purpose, then details. No extraneous 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 6 parameters and no output schema, the description covers the operation well, including defaults and optional fields. Missing return value or error conditions, but adequate given 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?

The schema has 0% description coverage, so the description adds meaning for all 6 parameters: explains delta constraints (positive/negative integer non-zero), defaults (name=available, reason=correction), and optional referenceDocumentUri. This compensates fully for missing schema documentation.

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

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

The description clearly states the action ('Adjust') and the resource ('available or on_hand quantity at a location'), and specifies the delta parameter. It distinguishes from sibling tools like shopify_get_inventory_level by focusing on mutation.

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 does not explicitly state when to use this tool vs alternatives, but the purpose is clear enough that an agent can infer usage. No 'when not to use' or comparison to read tools is provided.

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

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

With no annotations, the description discloses key behaviors: the action is reversible, destructive, and requires confirm=true; without confirm, it returns a simulated response. It does not cover error states or idempotency.

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 with two sentences that convey essential information: purpose, effect, reversibility, destructiveness, and confirm behavior. No redundancy.

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

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

Given no output schema, the description explains the primary behavior and confirm flag. However, it lacks details on response format or status codes, which would enhance completeness for a destructive action.

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 the confirm parameter's role but does not clarify the id parameter (e.g., product ID expected). Since schema coverage is 0%, the description provides some value but not fully compensating.

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 archives a product and specifies the action: sets status to ARCHIVED, hiding it from sale. It distinguishes from sibling tools like update or delete.

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 guidance on when to use the tool (archiving) and notes the confirm parameter requirement for destructive operations. However, it does not explicitly mention when not to use it or suggest alternatives.

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

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

The description discloses key behavioral traits: asynchronous (returns a job), destructive, requires confirm=true, and provides default values for reason, restock, refund, and notifyCustomer. Since no annotations are provided, the description carries full burden and does well.

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, dense sentence that front-loads the main action and includes critical details without extraneous words. Every part 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?

Given the complexity (7 parameters, async, destructive), the description covers the main purpose, async nature, destructive flag, and defaults. It could benefit from mentioning the job return format or how to verify completion, but overall it is fairly 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?

The description adds meaning for some parameters (reason default, restock default, refund default, notifyClient omitted, confirm required) but does not describe id or staffNote. With 0% schema coverage, the description partially compensates but is incomplete for all 7 parameters.

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

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

The description clearly states the tool cancels an order asynchronously. It uses a specific verb 'cancel' and resource 'order'. Among sibling tools, there is no other cancel tool, so it is well-distinguished.

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 canceling orders but does not explicitly state when not to use it or suggest alternatives. It mentions the destructive nature and requirement for confirm=true, but lacks explicit guidance on 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?

With no annotations, the description carries full burden. It discloses that the tool is destructive and requires confirmation, and explains the effect of paymentPending. However, it doesn't detail side effects like inventory changes or email notifications.

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 one sentence and two short statements. All information is relevant and front-loaded.

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

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

For a tool with 3 simple parameters and no output schema, the description covers the core action, destructive nature, and parameter effects. It could mention the return value or that id must be a valid draft order, but overall it's quite 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%, but the description adds meaning for two of three parameters. It explains that paymentPending=true marks the order as payment pending, and confirm=true is required for destructive action. The id parameter, though obvious, is not described.

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

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

The description uses a specific verb ('Complete') and resource ('draft order'), clearly stating the action of converting it into a real order. It distinguishes from sibling tools like shopify_create_draft_order.

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 lacks explicit when-to-use or when-not-to-use guidance. It mentions a requirement ('requires confirm=true') but does not compare with alternatives or state prerequisites like having a valid draft order ID.

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?

No annotations provided, so description carries full burden. It discloses the core action and constraints, but lacks details on permissions, side effects, or return values.

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 front-loaded sentences with no fluff. Includes mutation name, requirement, and list of optional fields.

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?

No output schema or annotations, but description covers purpose, required fields, and optional parameters. Could mention return value but not essential for selection.

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

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

Schema description coverage is 0%. Description lists optional fields and adds the requirement constraint, but does not explain the meaning or format of each parameter beyond their names.

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: 'Create a customer'. Specifies mutation name 'customerCreate'. Distinct from sibling tools like update, get, list.

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?

States when to use (customer creation) and critical requirement: 'At least one of email/phone is required'. No explicit exclusions or alternatives, but siblings make it 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?

No annotations provided, so description carries full burden. Only describes required and optional fields, not behavioral traits like side effects, rate limits, or whether the draft order is returned. Lacks depth.

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?

Extremely concise: two sentences, front-loaded with purpose and requirements. Every sentence adds value. No redundancy.

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

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

Adequate for a create tool with no output schema, but missing return value details. Describes input semantics well but lacks explanation of outcome (e.g., created draft order ID). 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 has 0% description coverage. Description adds meaning by specifying line item requirements (quantity plus variantId or title+originalUnitPrice) and listing optional fields. However, nested object fields (e.g., address details) are not explained beyond names.

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 'Create a draft order' with specific verb and resource. Distinguishes from siblings like shopify_complete_draft_order that complete existing drafts.

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 creating draft orders but no explicit when-to-use or alternatives provided. No comparison to other create tools or guidance on when not to 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?

No annotations provided, so the description carries full burden. It states 'Returns product + userErrors', indicating the return structure. It also notes the default status is ACTIVE, providing transparency on default behavior. However, it does not mention idempotency or side effects like publishing, but these are reasonable for a creation 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?

Very concise: two short sentences. Each piece of information is essential – the action, required/optional parameters, status enum with default, and return value. 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 no output schema, the description outlines return (product + userErrors) adequately. It covers all input parameters listed in the schema. For a simple creation tool, this is mostly complete, but it lacks guidance on relationships with other tools (e.g., after creation, use shopify_update_product to modify).

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 lists the required ('title') and optional fields with the status enum values and default. However, it does not explain the meaning of 'handle', 'productType', 'vendor', or 'tags', leaving ambiguity. Adds value over bare schema but insufficient for full understanding.

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 starts with 'Create a new product', a clear verb+resource pair. It lists required and optional fields, distinguishing it from siblings like shopify_archive_product or shopify_update_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?

No explicit guidance on when to use this tool versus alternatives such as shopify_update_product or shopify_archive_product. The context is implied by the name 'create', but the description does not state 'use this for new products' or exclude other use 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?

No annotations are provided, so the description carries the full burden. It discloses that addresses include a truncation marker and lists key returned fields, but does not address error handling (e.g., if ID not found) or performance behavior. Adequate for a simple get tool but lacks completeness.

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 short sentences with no redundant words. The first sentence states action and parameter, the second lists return contents. Highly 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 simple single-parameter tool with no output schema and no annotations, the description covers purpose, parameter meaning, and return details. It lacks mention of read-only behavior or error cases, but these are not critical for a straightforward get operation.

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

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

The schema has 0% description coverage, and the description adds value by explaining that 'id' can be a GID or numeric ID. This compensates for the bare schema. However, it does not specify the exact format for GID or numeric ID constraints, leaving some 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 clearly states the tool gets a single customer by GID or numeric ID, distinguishing it from sibling tools like shopify_list_customers (list many) or shopify_search_customers (search/filter). The verb 'Get' and resource 'single customer' specify the exact 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?

The description does not explicitly state when to use this tool vs alternatives, e.g., list or search tools. While it logically implies use when you have a specific ID, no when-not or alternative guidance is provided.

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

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

No annotations present; description does not disclose behavioral traits like read-only nature, rate limits, or authentication requirements beyond the implied get operation.

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 extraneous words; first sentence defines purpose and return fields, second sentence states requirements.

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 basic functionality but lacks detail on parameter sources and output structure; would benefit from mentioning typical usage or example values.

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% with no parameter descriptions; the description only restates the required parameters without explaining their meaning or how to obtain values.

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 verb 'Get' and resource 'inventory level', specifies the fields returned (available, on_hand, committed, incoming, reserved), and distinguishes from sibling tools like 'shopify_adjust_inventory_level'.

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?

Lists required parameters but provides no guidance on when to use this tool versus alternatives such as 'shopify_list_locations' or other retrieval 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?

With no annotations, the description carries the burden for transparency. It discloses the return content comprehensively (line items with truncation marker, customer, addresses, financial totals), which goes beyond the typical schema. It does not mention side effects, but for a read operation this is acceptable.

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

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

The description is extremely concise: two sentences that front-load the action and immediately follow with the return details. Every word adds value, with no filler or repetition.

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 simplicity of the tool (single parameter, no output schema), the description is largely complete. It covers the purpose, input format, and return details. It could be improved by noting error handling or null results, but for a straightforward get operation this is 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 input schema provides only a 'id' string parameter with no description. The description adds critical semantic meaning by specifying that the ID can be a GID or a numeric ID, compensating fully for the 0% schema description coverage.

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

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

The description clearly states the tool's function with a specific verb ('Get') and resource ('single order'), and mentions the accepted ID types (GID or numeric). It distinguishes the tool from siblings like shopify_list_orders and shopify_search_orders by focusing on a single order retrieval with full details.

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

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

The description implies when to use this tool (when needing a specific order's full details) and accepts both GID and numeric IDs. However, it does not explicitly state when not to use it or mention alternative tools for other purposes, though the context from sibling names provides implicit differentiation.

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?

With no annotations, the description carries full burden. It discloses that the tool returns 'full product detail including variants and images' and mentions 'truncation markers when capped', which informs the agent about potential output limits. However, it does not specify error handling or permission requirements.

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

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

The description is extremely concise: two sentences with no extraneous words. The first sentence states purpose and parameter format; the second describes output. 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?

Given the tool has a single parameter, no output schema, and no annotations, the description covers purpose, parameter format, and return content. It could be improved by mentioning error scenarios or access prerequisites, but it provides a solid baseline for a simple retrieval operation.

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 clearly explains the parameter 'id' accepts two formats (GID or numeric ID) with examples, which is essential for correct invocation. This fully addresses the missing schema documentation.

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

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

The description clearly states the tool retrieves a product by GID or numeric ID. The verb 'Get' and resource 'product' are unambiguous. It distinguishes itself from sibling tools like shopify_get_customer or shopify_get_order by specifying the resource type.

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 explicit guidance on when to use this tool versus alternatives like shopify_search_products or shopify_list_products. The context of having a specific ID is implied but not stated, and no exclusions or conditions are provided.

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

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

The description lists the returned metadata but does not explicitly state that the operation is read-only or has no side effects. Since no annotations are provided, this is a minor gap, though the name implies a safe read operation.

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 with 14 words, front-loading the purpose ('Get shop-level metadata') and efficiently enumerating key fields.

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 provides a clear list of returned fields. It is self-contained for a simple info retrieval tool, though it could mention that the data is static and immediately available.

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?

There are no parameters, and the schema coverage is trivially 100%. The description adds value by listing the fields returned, which is useful context beyond the empty 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 verb 'Get' and the resource 'shop-level metadata', listing specific fields. It distinguishes well from sibling tools which focus on customers, orders, products, etc.

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 retrieving shop metadata but does not explicitly mention when not to use it or alternatives. However, the tool is unique among siblings, making the context 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?

Without annotations, the description carries full burden. It lists return fields (id, title, etc.) but fails to disclose pagination behavior (first, after) or side effects. As a read operation, it's likely safe, but not explicitly stated.

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

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

The description is concise with one sentence and a clear list of return fields. It is front-loaded, but could benefit from structured parameter hints.

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 4 parameters, no output schema, and no annotations. The description is incomplete, missing pagination and sorting details. Return fields are partially listed, but overall completeness is low.

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%. The description only explains the 'query' parameter as optional Shopify search. Parameters 'first', 'after', and 'reverse' are not explained, leaving a 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 action 'List collections' and specifies the resource. It mentions optional search query, but doesn't differentiate from sibling list tools like shopify_list_customers or shopify_list_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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or limitations.

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?

Discloses default and maximum for 'first' parameter, and search query format. No annotations provided, so description carries burden. Does not mention rate limits, ordering, or read-only nature beyond implication.

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, front-loaded with verb and resource. 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 5 parameters with no schema descriptions, no output schema, and no annotations, the description is too brief. Lacks details on pagination cursor, sorting, and return format.

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%, so description must compensate. Adds meaning for 'query' (with example) and 'first' (default/max), but 'after', 'sortKey', and 'reverse' are not described. Partial but insufficient.

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 it lists customers and mentions optional search query with example. However, it does not distinguish from sibling tool 'shopify_search_customers', which likely has similar functionality.

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

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

No guidance on when to use this vs. alternatives like shopify_search_customers. Provides example of search query but lacks context for selection.

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?

No annotations are provided, so the description must disclose behavior. It explains that by default inactive and legacy locations are excluded, and how to include them. This is sufficient for a read-only operation, though no mention is made of authentication or rate limits.

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 concise sentences with front-loaded information. 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?

The tool has no output schema and moderate complexity. The description covers purpose and filter behavior, but omits pagination details and return value format. This leaves the agent uncertain about handling paginated results.

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 4 parameters with 0% description coverage. The description explains includeInactive and includeLegacy, but does not mention first and after (pagination). While pagination parameters are common, the description should ideally clarify them given the lack of schema help.

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 'List' and resource 'shop locations (warehouses, retail stores)', and the tool is distinct from all siblings which deal with other entities like orders, customers, and products.

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

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

The description explains the default filtering behavior (excludes inactive/legacy) and how to override with includeInactive/includeLegacy. While no explicit alternatives are given, it is the sole location listing tool so no confusion arises.

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?

No annotations exist, so the description must disclose behavioral traits. It does not mention pagination (first, after), rate limits, or the read-only nature of the operation, leaving gaps in 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 concise sentences, front-loaded with the core purpose. Efficient use of words, though could optionally mention pagination.

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 5 parameters, no output schema, and no annotation, the description fails to cover pagination behavior or return format, leaving the tool underspecified for an agent to fully understand its 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 0%, and description only explains ownerId, ownerType, and namespace. It omits first and after parameters, which manage pagination, and does not clarify that namespace is optional but others are not required.

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 action 'List metafields on any HasMetafields resource' and enumerates the supported resource types, making the tool's purpose unambiguous and distinct from sibling list 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?

Mentions required parameters (ownerId, ownerType) and optional namespace filter, providing basic guidance. However, lacks explicit when-to-use or alternatives, leaving the agent to infer context from sibling 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?

No annotations are provided, so the description should disclose behavioral traits like read-only safety. It only mentions defaults and query syntax but does not state that the tool does not modify data, nor does it discuss rate limits or pagination cursor behavior. The read-only nature is implied but not explicit.

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 very concise (one sentence) and front-loaded with the primary action and an example. However, the structure could be improved by separating the query example from default info.

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 5 parameters, no required ones, and no output schema. The description only covers query and first defaults, leaving 'after', 'sortKey', and 'reverse' unexplained. Pagination and sorting details are missing, making it incomplete for an AI agent to use effectively.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'query' parameter with an example and mentions 'first' default/max, but does not explain 'after' (pagination cursor), 'sortKey' values, or 'reverse'. The added value over the schema is minimal.

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 lists orders and mentions the optional search query with an example. It distinguishes the resource (orders) and verb (list), but does not explicitly differentiate from the sibling tool 'shopify_search_orders', which could cause confusion.

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 an example query and default pagination values, but offers no guidance on when to use this tool versus alternatives like 'shopify_search_orders' or 'shopify_get_order'. It lacks when-not-to-use and exclusion criteria.

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?

Discloses pagination behavior and default/max 'first' values, but does not mention read-only nature, authentication needs, rate limits, or possible side effects. No annotations are provided to fill gaps.

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 critical information front-loaded. Every sentence adds value without redundancy.

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

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

Covers basic usage for a list tool but lacks details about default sort order, return format, and error handling. With no annotations or output schema, it is minimally adequate.

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

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

Adds meaning to 'first' (default=50, max=250), 'after' (pagination via cursor), and 'query' (example syntax), but 'sortKey' and 'reverse' lack any description beyond schema enums and types. Schema description coverage is 0%, so description partially compensates.

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 lists products with optional query syntax. While it distinguishes from siblings like 'shopify_get_product' by being a list operation, it does not differentiate from 'shopify_search_products', which may cause confusion.

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 example query syntax and mentions pagination with default and max values, but lacks explicit guidance on when to use this tool vs alternatives like 'shopify_search_products'.

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

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

No annotations are provided, so the description carries the full burden. It mentions that the operation marks an order as paid and returns an updated order plus userErrors, but does not disclose idempotency, mutability, or what happens if the order is already paid or does not exist.

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

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

Two concise sentences with no redundancies. The first sentence states the action and API name; the second provides use case and return information. All content is essential and well-structured.

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

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

Despite no output schema, the description adequately covers the tool's action, intended use, and return values (updated order + userErrors). For a single-parameter tool, this is fairly complete, though it could include error handling details.

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 must explain parameters. It does not elaborate on the 'id' parameter beyond its existence, leaving the agent to infer that it is the order ID. This lack of explicit clarification is a significant 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's action (mark an order as paid), the API function name, and the specific use case (offline payments captured outside Shopify). It distinguishes itself from siblings by focusing on a unique payment operation not covered by other tools.

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

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

The description explicitly states when to use the tool (offline payments where funds were captured outside Shopify). It implicitly excludes online payments, but does not name alternative tools or explicitly state when not to use it.

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

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

With no annotations, the description must carry the behavioral burden. It states 'Returns the updated product node + userErrors', which is useful but does not disclose potential side effects, permission needs, or the behavior if tags don't exist. Adequate but not comprehensive.

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 unnecessary words. It front-loads the action and required fields, making it efficient and scannable.

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 simplicity of the tool (2 required params, no nested objects) and no output schema, the description adequately covers the action, requirements, and return value. However, it could mention error handling or edge cases for 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 coverage is 0%, so the description must compensate. It repeats that tags must be non-empty, but adds no extra semantics like the format of productId or tag string. Basic repetition of schema constraints with minimal added 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 'Remove one or more tags from a product.' It uses a specific verb (remove) and resource (product tags), and implicitly distinguishes from siblings like 'shopify_add_product_tag' by focusing on removal.

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 mentions required parameters but lacks explicit guidance on when to use this tool versus alternatives (e.g., comparing to add/update operations). It does not provide context for when removal is appropriate or any prerequisites.

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?

With no annotations provided, the description carries the full burden. It only states 'Search customers' and gives a query example, but does not disclose behavior such as read-only nature, pagination behavior, rate limits, or whether the search is full-text or exact match.

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 very short, one sentence plus an example, which is appropriately front-loaded. However, it could be slightly expanded to cover other key parameters without being verbose.

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 5 parameters, no output schema, and no annotations, the description is too minimal. It does not explain pagination, sorting, result format, or prerequisites, leaving the agent without enough context for effective use.

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%. The description adds meaning only to the 'query' parameter by showing its format. The other four parameters (first, after, sortKey, reverse) are not mentioned, leaving them fully undocumented in terms of usage.

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

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

The description clearly states the tool searches customers by a Shopify search query, with a specific example. It distinguishes from siblings like shopify_get_customer (single customer by ID) and shopify_list_customers (no query filter).

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 indicates the query parameter is required and provides an example of its format, but it does not explicitly state when to use this tool over alternatives like shopify_list_customers or shopify_get_customer, nor does it mention any 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?

No annotations are provided, and the description does not disclose return structure, rate limits, or whether the operation is read-only. It only states the basic action.

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 very concise at one sentence plus example. It could be slightly more structured, but it is not verbose.

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 complexity of 5 parameters, no output schema, and no annotations, the description is incomplete. It does not cover pagination, sorting, or return values.

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 adds little beyond the schema. Only the 'query' parameter is given an example; 'first', 'after', 'sortKey', and 'reverse' are not explained at all.

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

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

The description clearly states the tool searches orders using a Shopify search query, with an example. However, it does not explicitly differentiate from 'shopify_list_orders', which likely lists orders without 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?

Only notes that the query parameter is required. No guidance on when to use this tool versus alternatives like 'shopify_list_orders', or how to handle pagination or sorting.

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?

No annotations are provided, so the description carries the full burden. It discloses that it is a search operation, but does not mention that it is read-only, whether it is idempotent, or any side effects. The description is minimal and does not convey behavioral traits beyond the basic search functionality.

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 concisely communicates the purpose and critical parameters. It is front-loaded and efficient, though it could be slightly expanded without losing conciseness.

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 complexity of the tool (5 parameters, no output schema, no annotations), the description is incomplete. It does not explain the return format, pagination details, error handling, or provide enough context for an agent to use the tool effectively without additional knowledge.

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%, meaning no parameter descriptions in the schema. The description mentions 'Required: query. Optional pagination + sort' but does not explain the individual parameters like 'first', 'after', 'sortKey', 'reverse', or the query format in detail. The example given is helpful but insufficient to fully understand all parameters.

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

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

The description clearly states the verb 'search', the resource 'products', and the method 'Shopify search query (full-text + filters)'. It provides a specific example of filter syntax, which distinguishes this tool from siblings like shopify_list_products that likely just list products without advanced filtering.

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 searching with filters but does not explicitly state when to use this tool vs shopify_list_products or other search tools. It provides a hint with the example but lacks explicit when-to-use or 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?

No annotations provided, so description carries full burden. It correctly indicates a mutation ('update') and notes that only provided fields are applied. However, it does not disclose idempotency, side effects, authorization needs, or return data. Basic transparency but lacks depth.

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 with clear front-loading: action and required parameter. No filler or redundant information. Every word is purposeful.

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 mutation tool with 8 parameters, no output schema, and no annotations, the description covers essential information (update, required id, optional fields) but misses details like return value, error handling, or field-specific notes. Adequate for simple use but not comprehensive.

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

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

Schema has 8 parameters with 0% description coverage. The description only clarifies that 'id' is required and all others are optional, and that only provided fields are updated. It adds no semantics about field formats, constraints, or behavior (e.g., what 'locale' expects, if 'tags' replaces or appends). Insufficient compensation for lack of 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?

Clearly states the action 'Update a customer' with the specific Shopify API call 'customerUpdate'. Distinguishes from sibling tools like 'shopify_create_customer' and 'shopify_get_customer' by focusing on update. The required 'id' and optional fields are specified.

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 the requirement for 'id' and that other fields are optional. While it doesn't provide when-not-to-use or alternatives, the context of sibling tools (create, get, search) makes the usage clear. Lacks explicit exclusions but is sufficient for basic 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?

The description discloses that the tool performs an update (mutation) and returns 'product + userErrors', indicating both success and error responses. It notes that only provided optional fields are applied, informing the agent of idempotent-like behavior per field. Since no annotations are provided, the description carries the full burden and meets it adequately.

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, consisting of just two sentences. The first sentence immediately states the action and identifier, front-loading the key information. Every sentence earns its place without any 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 absence of an output schema and annotations, the description reasonably covers the tool's usage: required vs optional fields, identifier format, and return type. It could mention potential errors or side effects (e.g., status enum values), but overall it provides sufficient context for an update operation.

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 clarifies that 'id' is required and all other parameters are optional and only applied if provided. It also specifies that id can be a GID or numeric ID, adding meaning beyond the schema. While individual parameter descriptions are missing, the high parameter count (8) and self-explanatory names make this acceptable.

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: 'Update fields on an existing product by GID or numeric ID.' It identifies the specific action (update), the resource (product), and the identifier format. This clearly distinguishes it from sibling tools like shopify_create_product or shopify_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 implies that this tool is for modifying existing products, as it requires an id and states all other fields are optional. It mentions the identifier can be GID or numeric ID, guiding the agent on input format. However, it does not explicitly state when not to use it (e.g., for creating products) or provide alternative tool names.

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