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

Since no annotations are provided, the description fully covers behavioral traits: Shopify limit of 3 options, auto-assignment of first value to existing variants, and the inability to remove options. This is comprehensive for a mutation 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?

Four sentences, each essential: purpose, constraint, side effect, and guidance. No redundancy or fluff.

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

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

Given no output schema and no annotations, the description covers purpose, constraints, side effects, and next steps completely. An agent can safely invoke this tool with the provided information.

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

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

With 100% schema coverage, baseline is 3. The description adds value by explaining the Shopify cap (maxItems) and the auto-assignment behavior, but the schema already documents name, values, and position 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 verb 'Add' and the resource 'options (like Size, Color, Material) to an existing product'. It also distinguishes from sibling tool 'create_variants' by noting the appropriate sequence.

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 when-to-use (adding options), when-not-to (cannot remove options, exceeding 3 options rejected), and alternatives (re-create product for removal, use create_variants for SKUs).

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 the async nature (background job on Shopify's side), the response structure (job ID and done flag), and that very large batches may be queued. Duplicates being silently ignored is also transparent. No behavior is hidden.

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 extraneous words. It is front-loaded with the core purpose and then adds critical behavioral 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?

Given the tool's simplicity (2 parameters, no output schema), the description is complete. It covers behavior, response structure, constraints, and exceptions. No missing elements.

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

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

The input schema covers both parameters with 100% description, so the baseline is 3. The description adds no new semantic information beyond the schema—it reiterates the manual collection constraint and async behavior, but those are behavioral, not parameter-level semantics. Thus, a score of 3 is appropriate.

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

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

The description clearly states the action 'Add one or more products to a manual collection.' It specifies the resource (products), action (add), and target (collection). It distinguishes from sibling tools like remove_products_from_collection by focusing on adding. The exclusion of smart collections is also explicitly stated.

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

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

The description provides clear context on when to use: for manual collections only, and warns that smart collections reject manual additions. It also notes that duplicates are silently ignored. While no explicit alternative tool is named, the guidance is strong and sufficient for correct 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?

Discloses key behavior: tags are a unique set per resource, adding existing tag is a no-op. No annotations, so description carries full burden; it adequately covers idempotency and additive nature.

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 plus a note, front-loaded with purpose. Every sentence adds value: resource list, behavior, use cases, sibling reference. 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 simple 2-param schema and no output schema, description fully covers purpose, behavior, usage guidelines, and sibling relationship. No gaps for agent decision-making.

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?

Input schema has 100% description coverage with clear GID and tags explanations. Description adds context about normalization but does not significantly surpass schema. Baseline 3 is appropriate.

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

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

Explicitly states 'Add tags to any taggable Shopify resource' and lists examples. Clearly distinguishes from sibling 'remove_tags' by naming it for full taxonomy management.

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 use cases: 'ad-hoc segmentation, marketing campaigns, driving smart collection membership rules'. Mentions pairing with remove_tags, implying when to use each. Could be improved by explicitly stating when not to use (e.g., when replacing all tags).

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 fully discloses behavioral traits: it restores remaining quantity on the underlying fulfillment order, does not issue a refund, and returns the new status. 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, zero waste. Front-loaded with the core action, followed by usage guidance, side effects, limitations, and return value. 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's simplicity (one required parameter, no output schema), the description fully covers purpose, when to use, behavioral effects, and return value. No missing 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?

The description adds no extra semantic meaning beyond the input schema, which already fully describes the single parameter 'id' as 'Fulfillment GID to cancel.' Schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description starts with a clear verb and resource ('Cancel an existing fulfillment') and immediately distinguishes its use case from siblings like cancel_order by specifying when to use (lost in warehouse, address bounced, customer cancelled).

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 (item won't ship) and when not (does not issue refund), and provides direction to combine with order-level refund tools. Also describes the effect on the fulfillment order.

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?

Even with no annotations, description fully discloses behavioral traits: async job with jobId response, side effects of refund/restock/notify, and preconditions. It does not contradict any structured fields.

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 a single paragraph but well-structured, front-loading the main purpose then detailing options. Could be slightly more structured (e.g., bullet points) but remains concise 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?

Given 6 parameters, async nature, and no output schema, description covers all necessary context: preconditions, side effects, relationships with sibling tools, and response shape (jobId). Complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining usage context for each boolean flag (e.g., when to set refund false, restock false) and linking to refund_order. Adds moderate additional 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?

Description clearly states 'Cancel a Shopify order.' and specifies verb+resource. It distinguishes from siblings like cancel_fulfillment and refund_order by mentioning them directly.

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 when-to-use and when-not-to-use guidance, including cannot cancel already-cancelled orders or orders with active fulfillments, and directs to cancel_fulfillment first. Also explains conditions for refund, restock, and notifyCustomer flags.

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, description fully discloses behavior: immediate payment capture attempt with potential failure, creation of payment-pending order, one-way transition, and returned GID.

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?

Four sentences, each essential. Main action in first sentence, followed by two payment scenarios and a final constraint. 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?

Complete for a conversion tool: covers payment modes, state transition, result, and limitations. No output schema but return value is described.

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 100% of parameters; description adds context about default behavior and failure case for paymentPending, and rejection of non-OPEN drafts, enriching 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?

Clearly states 'Convert an OPEN draft order into a real Shopify order' with specific verb and resource. Distinguishes from creation tools (create_order) and deletion tools (delete_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?

Explicitly describes when to use (for converting drafts), differentiates between paymentPending=true/false scenarios, and notes that completed drafts cannot be reopened, guiding 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?

With no annotations provided, the description carries full burden. It discloses the side effect that the collection becomes visible in the storefront unless publication channels are configured separately, and notes that the return value is a GID. It does not cover authentication or rate limits, but for a creation tool, the transparency is 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?

The description is three sentences, each useful: first states purpose and limitation, second lists required vs optional, third explains return value and side effect. No wasted words, perfectly 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?

Given the tool has 4 parameters, no annotations, and no output schema, the description adequately covers: purpose, required fields, return value (GID), side effect, and a usage pointer to sibling tools. It is complete for an agent to understand and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that handle defaults to slugified title and must be unique, and that productIds are for seeding manual collections (not smart). This goes beyond the schema's definitions.

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 'Create a new manual collection' and explicitly distinguishes from rule-based smart collections, which are unsupported. It provides a specific verb (create) and resource (collection), differentiating it from sibling tools like update_collection or delete_collection.

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 tells when to use this tool (for manual collections) and when not to (smart collections should use the Shopify admin). It also explains the return value (GID) and how it is needed for subsequent calls like add_products_to_collection, providing clear context for 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?

No annotations provided, so description carries full burden. It discloses required fields (email/phone), uniqueness, default consent (NOT_SUBSCRIBED), legal requirement for opt-in, first address becomes default, and return value GID. This is comprehensive behavioral disclosure.

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 well-structured: starts with core purpose, then requirements, optional features, legal note, and return value. It is slightly lengthy but every sentence adds value. 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 no output schema, the description explains return value (GID) and links to related tools. It covers all essential aspects (required inputs, uniqueness, addresses, consent) for effective usage, handling nested objects and 8 parameters well.

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?

Input schema has 75% description coverage. Description adds value beyond schema: explains why email/phone required, uniqueness, default shipping address, consent default, and returned GID usage. It also clarifies the consent field's default and legal implications.

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 'Create a new customer record' and details required and optional fields, distinguishing it from update_customer. It specifies the minimum inputs (email or phone) and uniqueness constraints, leaving no ambiguity about the tool's function.

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

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

Provides explicit conditions: supply email or phone, uniqueness requirements, default consent, and legal note for opted-in state. It also mentions using the returned GID for other tools. Lacks explicit 'when not to use' 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?

Despite no annotations, the description thoroughly discloses behavior: line item constraints (variant vs custom), optional attachments, draft state (OPEN), and return values (GID, invoice URL). No contradictions.

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

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

The description is informative but slightly verbose with multiple clauses. However, every sentence adds value and it is well front-loaded with the purpose. Could be slightly tighter but effective.

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 complex tool with 6 parameters and no output schema, the description provides all necessary context: line item rules, optional fields, draft lifecycle, and return values. High completeness given the schema coverage.

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%, and the description adds substantial detail: explains line item shapes, rejection of mixed shapes, purpose of email vs customerId, and distinction between custom and variant items. Exceeds schema 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 creates a draft order (editable cart/quote), distinguishing it from related tools like complete_draft_order and create_order. It provides specific Shopify terminology and context.

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

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

The description explains when to use (for editable carts/quotes) and mentions subsequent actions (complete_draft_order or send invoice). It implicitly distinguishes from create_order but lacks explicit 'when not to use' or direct 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?

With no annotations provided, the description fully discloses side effects: 'customer-facing email if notifyCustomer is true; webhook fires; remaining quantities decrement.' This goes beyond basic behavior.

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 the core action, each sentence adding value. No unnecessary words. Structure supports quick comprehension.

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 (nested objects, side effects), the description covers main points well. However, no output schema exists, and the description does not explain the return value (likely the fulfillment record). Minor gap.

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?

Although schema coverage is 100%, the description adds critical context: omitting fulfillmentOrderLineItems fulfills everything, tracking URL auto-derives for major carriers, and line item IDs come from list_fulfillment_orders.

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 explicitly states 'Mark items as shipped — creates a fulfillment record', clearly identifying the verb (create) and resource (fulfillment record). It distinguishes from siblings like cancel_fulfillment and update_fulfillment_tracking.

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

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

Description explains when to use (marking items as shipped) and mentions optional tracking and notification. It also references list_fulfillment_orders for IDs. However, it does not explicitly state when not to use this tool or provide alternatives like cancel_fulfillment.

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 covers key behaviors: silently ignoring status for non-publishable types, optional handle generation from displayName, and serialization of field values as strings. It also mentions the return value (GID).

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 yet comprehensive, front-loaded with the main action, and each sentence adds unique 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?

Given 4 parameters, no output schema, and no annotations, the description covers prerequisites, parameter details, edge cases, and return value. It is self-contained for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds significant value: explaining that type must match a registered definition, handle generation logic, field value serialization (JSON-encoded for complex types), and status restrictions. This goes well beyond 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 it creates a new metaobject instance of an existing type. It distinguishes from sibling tools like delete_metaobject, update_metaobject, and get_metaobject by specifying creation and referencing list_metaobject_definitions for type verification.

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 advises calling list_metaobject_definitions first if unsure of the type, and explains optional handle generation and status applicability. It does not explicitly state when not to use, but provides clear context for 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?

Despite no annotations, the description reveals key behaviors: defaults for financial status, customer notification, and inventory handling. It explains line item types and oversell policy. However, it doesn't mention rate limits, authentication, or error outcomes, holding it back from a 5.

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 well-structured and concise: first states purpose, then usage guidelines, then defaults. Every sentence adds critical information with no redundancy. It is appropriately sized for the complexity of the tool.

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

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

Given no output schema and 8 parameters (1 required), the description covers essential aspects: line item types, defaults, when to use alternatives. It could mention output format or error scenarios, but the core semantics are well addressed. Falls just short of 5 due to lack of post-execution 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the line item structure (variant vs custom), providing usage context for each parameter, and clarifying defaults. It goes beyond the schema's descriptions, especially for lineItems and financialStatus.

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: 'Create a real Shopify order directly, bypassing the draft-order flow.' It distinguishes from sibling tools (create_draft_order) and specifies exact use cases (historical orders, phone/in-person sales).

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 provides when to use ('import historical orders, record a phone/in-person sale') and when not to ('For interactive carts... use create_draft_order then complete_draft_order instead'). Also includes default behaviors (PENDING financial status, no notification).

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 fully discloses key behaviors: product creation first then image attachment, default DRAFT status to prevent premature publishing, initial hidden 'Default Title' variant, and the need for create_variants to add real options. The return value (GID and handle) is also specified.

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

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

The description is concise and well-structured: starts with the main action, then discusses image attachment, status, variants, and return value in logical order. Every sentence adds valuable information 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?

Given the parameter count (7), low schema coverage (29%), no output schema, and no annotations, the description covers essential aspects: return value, process steps, and best practices. It could mention prerequisites or side effects (e.g., authentication needs, rate limits) but is otherwise thorough for the tool's complexity.

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

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

Schema coverage is only 29%, but the description adds meaning for key parameters: explains image_urls (attached after creation), status (default DRAFT, use ACTIVE when ready), and alludes to title. However, it does not elaborate on vendor, product_type, or tags beyond the schema, missing an opportunity to fully compensate for 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 'Create a new product' and details the creation process, distinguishing it from sibling tools like create_variants and update_product. It explains the two-step image attachment, default status, and variant handling, making the purpose unambiguous.

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

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

The description provides explicit guidance: use default status DRAFT to avoid accidental publishing, pass status=ACTIVE when ready to go live, and call create_variants for real variants. It also clarifies the image attachment process as a follow-up, helping the agent decide when and how to use the tool.

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

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

With no annotations, the description adequately discloses creation behavior, option coverage requirement, strategy effects, and inventory seeding limitations. Could mention side effects like webhook triggers but covers critical operational details.

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?

Four sentences, front-loaded with core action, no redundant information. 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?

Covers key aspects for successful invocation: constraints, strategy, inventory behavior, and alternative tools. Lacks error handling or response format but acceptable given no output schema and comprehensive parameter guidance.

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 67% but description adds context for strategy parameter and inventoryQuantities usage. Reinforces schema descriptions with practical guidance on when to use each parameter.

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 one or more variants on an existing product' with specific verb, resource, and context. Distinguishes from sibling tools like update_variants and delete_variants.

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 explains when to use strategy='REMOVE_STANDALONE_VARIANT' for first variants and when to prefer set_inventory_quantity for ongoing inventory changes. Also states constraint that optionValues must cover all product options.

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. Description mentions return value (GID) and need to verify delivery. Does not disclose potential side effects, rate limits, or authentication requirements. Partial coverage.

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?

Five concise sentences, each serving a purpose. No redundant information. Front-loaded with main action and common topics.

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 all essential aspects: topic suggestions, callback requirement, field filtering, metafield opt-in, return value, and verification advice. Lacks mention of overwriting behavior but still sufficiently complete for a creation 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 80%, description adds value by listing common topics and explaining the benefit of includeFields. However, it mostly echoes schema descriptions. Adequate but not exceptional.

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 ('Subscribe') and resource ('webhook topic') with specific endpoint mention. Lists common topics to clarify scope. Distinct from sibling tools like update_webhook or list_webhooks.

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 some context: callbackUrl must be HTTPS in production, and verification is needed. However, no explicit guidance on when to use this vs. sibling tools like update_webhook or list_webhooks.

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 irreversibility, no deletion of contained products, and return behavior (deleted ID or not-found message). No annotations are provided, so the description carries the full burden; it covers key behavioral traits but could mention authorization 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?

Two sentences, no wasted words, front-loaded with action and side effects, then usage hint and return info. 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?

Given no output schema, the description explains the return value. It covers purpose, side effects, usage guidance, and return format, making it complete for this simple 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 has 100% coverage with a parameter description that repeats parts of the tool description. The description adds no new semantic detail beyond what is already in the schema.

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

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

Clearly states the verb and resource ('Permanently delete a collection') and specifies that products inside are not deleted, distinguishing it from tools like delete_product or remove_products_from_collection.

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 advises confirming the collection ID with get_collection before calling, which is a clear when-to-use guideline and suggests an alternative verification step.

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 fully covers behavioral traits: irreversibility, state constraints, and return format (deleted GID or no-op). 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, each providing essential information. Front-loaded with the main action. No wasted words.

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

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

Given the single parameter, no output schema, and no annotations, the description provides complete context: purpose, constraints, irreversibility, and return value.

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% for the single parameter id, so baseline is 3. The description adds context about return behavior, slightly enhancing understanding beyond the schema.

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

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

The description clearly states the action: 'Permanently delete a draft order.' It specifies constraints on which drafts can be deleted (OPEN/INVOICE_SENT) and distinguishes from siblings like cancel_order for completed drafts/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?

Explicitly tells when to use (only for OPEN/INVOICE_SENT drafts), what not to use (completed drafts are real orders), and provides an alternative ('cancel them instead'). Also describes return behavior.

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 deletion is irreversible, that other metafields on the same resource are unaffected, and that the operation is a no-op for invalid keys. With no annotations provided, this fully informs the agent of the tool's behavioral traits.

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, front-loaded with the core purpose, and each sentence adds necessary context without redundancy. It efficiently covers irreversibility, prerequisites, and limitations.

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 no output schema and no annotations, the description adequately covers deletion behavior, safety notes, and usage patterns. Minor gap: no mention of the response (e.g., whether it returns success or the deleted entity), but this is not critical for an agent to use the tool correctly.

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

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

The input schema already provides descriptions for all three parameters (100% coverage), so the description adds no additional semantic detail beyond restating the parameter names. The baseline of 3 is appropriate as the schema does the heavy lifting.

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 begins with 'Permanently delete a single metafield by (ownerId, namespace, key)', which is a specific verb and resource with the required parameters. It clearly distinguishes this tool from siblings like set_metafield and delete_metaobject by specifying the exact identification triple.

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 recommends using list_metafields first to confirm namespace and key, warns that typos cause a no-op rather than an error, and explains that only one metafield is deleted per call (not bulk). This provides clear guidance on when and how to use the tool.

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

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

No annotations provided, so description fully covers behavioral traits: irreversible, metafield references become broken (Shopify does not auto-clean), and return behavior (deleted GID or no-op message).

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, no fluff. Front-loaded with purpose, then consequences, then usage tip, then return info. 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?

No output schema, but description specifies return values. Covers purpose, side effects, prerequisite action, and result. Complete for a single-parameter delete 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 already covers the parameter with 100% coverage. Description adds value by reiterating the irreversible nature and the consequence of broken references, plus the return behavior.

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 'Permanently delete a metaobject by GID', specifying the action and resource. Distinguishes from sibling tools like update_metaobject and get_metaobject.

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 advises to use get_metaobject to confirm the record before deleting, and highlights irreversibility and broken references. Provides clear usage 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 provided, the description carries full burden. It discloses irreversibility, the constraint on minimum variants, and how completed order variants are handled (kept-but-hidden). Lacks info on authorization or rate limits, but is otherwise transparent.

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, each adding critical information: action, irreversibility constraint, and nuance about order preservation. No wasted words; front-loaded with the primary purpose.

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

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

Given no output schema and no annotations, the description covers the main behavioral aspects of the tool: irreversibility, the constraint on emptying a product, and order preservation. Missing details on error handling or return values, but sufficient for a deletion 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?

Input schema has 50% coverage: productId has a basic description ('Product GID.'), variantIds has none. The description implies variantIds by saying 'one or more variants' but adds no detail about format or constraints beyond schema. Does not clarify that productId is a GID or how to obtain it.

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 'permanently delete[s] one or more variants from a product', specifying the action, resource, and scope. It distinguishes from siblings like delete_product by mentioning the alternative for whole product deletion.

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 'permanently delete' indicates finality. Provides when-to-use guidance by noting that 'Each product must keep at least one variant' and that 'Shopify rejects requests that would empty the product', advising against deleting the last variant. Also clarifies behavior for completed orders.

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 the full burden. It discloses irreversibility and what the tool returns (deleted GID or no-op). Could mention any prerequisites like authentication, but overall sufficient.

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

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

Three sentences: first defines the action, second provides usage context, third describes return. No redundant information; 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?

For a simple deletion tool with one parameter and no output schema, the description covers all necessary aspects: purpose, irreversibility, usage scenarios, and return value.

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?

Input schema has 100% coverage with a clear description for the single parameter. Description adds no additional parameter details beyond the schema, which is adequate.

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: 'Permanently unsubscribe from an event topic by deleting the webhook subscription.' It specifies the resource (webhook subscription) and distinguishes from sibling tools like create_webhook, update_webhook, and list_webhooks.

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

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

It explicitly states when to use: 'Use when retiring an integration or switching topics.' It also notes that deletion is irreversible and that re-creation requires create_webhook, providing an alternative.

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. States return is a 'friendly text view' and that pageInfo flags product existence. Lacks details on idempotency, authorization needs, or whether it's a pure 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?

Two clear, well-structured sentences. Front-loads purpose, no fluff. Every sentence provides actionable 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, description adequately covers return fields (title, handle, etc.) and pagination info. Could mention error cases or format details for a higher score.

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?

Both parameters documented in schema (100% coverage). Description adds value by explaining practical use of productsFirst=0 and pageInfo behavior, going beyond schema definitions.

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 uses specific verb 'Fetch' and specifies resource 'single collection by GID' with detailed fields (title, handle, etc.). Clearly distinguishes from sibling tools like list_collections or create_collection.

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

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

Provides explicit guidance for using productsFirst=0 for metadata-only. Mentions pageInfo for pagination, but could be more explicit about when to prefer this over list_collections or other collection 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 provided, so description carries full burden. Describes read-only behavior and details of return value. Lacks information on error handling or permissions, but for a fetch tool this is adequate.

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, no filler. Front-loaded with purpose and return details. Every sentence contributes meaning.

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?

Simple tool with one param. Description covers what, when, and return format. Missing error conditions, but overall sufficient for agent 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 has 100% coverage with id description. Description adds value by suggesting source of ID ('Get one from list_draft_orders'), aiding parameter generation beyond 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?

Description clearly states verb 'Fetch' and resource 'single draft order', lists specific details returned, and differentiates from siblings like update_draft_order and complete_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?

Explicitly recommends using before update_draft_order or complete_draft_order, providing clear context. Does not mention alternatives like list_draft_orders, but the guidance is sufficient for agent decision.

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 full burden. It explicitly lists returned fields (status, tracking entries, parent order, timestamps) and implies a read-only operation. While it doesn't mention authentication or rate limits, for a simple fetch tool this is sufficient and transparent.

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

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

Two sentences, no fluff. First sentence states purpose and returns, second provides usage guidance. Every word earns its place.

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

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

For a simple 1-parameter retrieval tool with no output schema, the description fully covers what it does, when to use it, and what to expect. No 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?

Only one parameter 'id' with schema description 'Fulfillment GID.' The description mentions 'by GID' and 'delivers a fulfillment GID,' reinforcing the parameter's meaning. With 100% schema coverage, the description adds marginal value beyond the schema, so 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?

The description uses the specific verb 'Fetch' and identifies the resource 'fulfillment' with clarification that it's a shipment record. It distinguishes from sibling tools like list_fulfillment_orders (list) and cancel_fulfillment (cancel) by specifying a single item retrieval by GID.

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 two usage scenarios: after create_fulfillment to confirm the shipment, and when a webhook provides a fulfillment GID needing details. This provides clear when-to-use guidance and 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 adequately discloses behavior: it is a read operation ('Fetch'), returns line-item set and remaining quantities, and avoids parent lookup. It does not mention error handling or rate limits, but for a simple fetch tool this is sufficient.

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

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

Two sentences, no filler words. Front-loaded with the core action and returns. 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?

For a single-parameter tool with no output schema, the description covers the return values and use case. It could mention potential errors (e.g., invalid GID) but is complete enough for effective tool 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 coverage is 100% and the parameter 'id' is described as 'FulfillmentOrder GID.' The description repeats this in prose ('by GID') but does not add extra meaning beyond the schema. Baseline score is appropriate.

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

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

The description clearly states the verb ('Fetch') and resource ('fulfillment order by GID') and specifies what it returns ('full line-item set and remaining quantities'). It distinguishes itself from list_fulfillment_orders by noting it returns a single record.

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 tells when to use this tool ('when you have the FulfillmentOrder ID directly from a webhook payload') and what advantage it offers ('without having to look up its parent order'). Also references a sibling tool ('same shape as list_fulfillment_orders'), providing clear 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?

With no annotations provided, the description carries the full burden. It discloses a key behavioral detail: field values longer than 120 characters are truncated in the rendered output (but full values remain on the underlying record). This is critical for an agent to set expectations. It doesn't cover authentication or rate limits, but for a read-only operation, the disclosure is adequate.

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 core purpose, immediately followed by the truncation detail and usage advice. Every part is essential and well-organized, with no wasted words.

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

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

Although there is no output schema, the description explicitly lists what is returned (display name, handle, type, publishable status, all field values) and notes the truncation behavior. This gives agents a clear understanding of the response content. It could mention any pagination or sorting, but given the tool fetches a single item by ID, it is 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?

The only parameter 'id' has 100% schema description coverage with an example GID and a reference to list_metaobjects. The description adds value by repeating and contextualizing the schema's guidance on discovering GIDs, reinforcing the workflow. This goes beyond what the schema alone provides.

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 exact verb ('Fetch'), the resource ('single metaobject'), the method of identification ('by GID'), and the specific fields returned ('display name, handle, type, publishable status, and all of its field values'). It also notes the truncation behavior, which adds precision. The purpose is distinct from sibling tools like 'list_metaobjects' and 'list_metaobject_definitions'.

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

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

The description explicitly instructs the agent to use 'list_metaobjects' first to discover GIDs, providing a clear prerequisite and pointing to the correct sibling tool for discovery. While it doesn't explicitly state when not to use this tool, the guidance is sufficient for an agent to understand the typical workflow.

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 describes the return format (JSON) and accepted ID formats (GID or numeric ID with auto-promotion). It doesn't mention error cases or authentication, but for a simple fetch operation, it is adequately transparent.

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 first sentence clearly states the tool's purpose and what it returns. The second provides usage guidance. Structure is front-loaded and efficient.

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

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

For a simple read tool with one required parameter and no output schema, the description covers everything needed: what fields are returned, ID format, and how to discover IDs. It also connects to related tools (list_orders, list_fulfillment_orders).

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 single parameter 'id' has a schema description that is 100% complete. The description adds extra context about accepting both GID and numeric ID forms, that numeric IDs are auto-promoted, and where to get an ID (list_orders).

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 'Fetch a single order's full record' and lists specific fields (email, totals, status flags, timestamps, line items, customer email). It distinguishes itself from sibling tools like list_orders and list_fulfillment_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?

Explicitly advises to 'Use list_orders to discover order IDs first' and suggests a follow-up with list_fulfillment_orders for shipments. This provides clear when-to-use and which alternative tools 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 are provided, so the description carries full burden. It describes the return data in detail (header fields, inventory totals, first 10 images/media, first 20 variants). It does not explicitly confirm it's read-only, but 'fetch' implies safe read. Additional context on downstream usage adds 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?

The description is two sentences, front-loaded with the purpose, and efficiently conveys essential information without any extraneous text.

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

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

No output schema exists, so the description must explain return values. It does so by listing header fields, inventory totals, images, media, and variants with details. It also addresses limitations (first 20 variants) and provides follow-up guidance. Missing error handling or edge cases, but adequate for a simple fetch 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?

The input schema has 100% coverage with a detailed description of the 'id' parameter. The description repeats the ID type (GID or numeric) and adds context on return format (JSON), but does not add meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states it fetches a single product's full record by GID or numeric ID. It specifies what data is returned and distinguishes itself from other get_* tools for different resources (e.g., get_collection, get_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 provides guidance on follow-up actions: using variant inventoryItem GIDs for set_inventory_quantity and using list_variants for more than 20 variants. It does not explicitly state when not to use this tool or alternatives like list_products, but the context is clear.

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

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

Clearly indicates a read-only operation ('Fetch'), with no annotations to contradict. Discloses that the response includes full configuration details, which is consistent with a read tool. Lacks mention of permissions or rate limits but is acceptable for a simple fetch.

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 states action and output details, second provides usage guidance. No wasted words, front-loaded with key 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?

Despite no output schema, the description enumerates the returned fields (topic, endpoint, format, etc.), making the tool's output clear. Usage guidance completes the picture for a simple read tool. No gaps.

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

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

Schema covers the single parameter 'id' with description 'Webhook subscription GID' at 100% coverage. The description reaffirms 'by GID' and lists returned fields, adding some context but not significantly beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'Fetch' and resource 'single webhook subscription's full configuration', listing included fields (topic, endpoint, etc.), clearly distinguishing it from list_webhooks (multi) and create/update/delete siblings.

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: 'Use to verify subscription details before update or delete, or when debugging delivery issues.' Does not mention alternatives explicitly, but context is sufficient for an agent to decide.

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 bears full burden. Discloses readonly nature implicitly ('list') and pagination behavior, but does not explicitly state safety or error conditions. Adequate for a simple 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?

Very concise: three focused sentences covering purpose, return fields, pagination, and usage. No filler, each sentence earns its place. Front-loaded with primary action.

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, but description lists return fields. Covers pagination mechanics and query syntax. Lacks details on error handling or edge cases, but sufficient for a list tool with three simple parameters.

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

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

Schema coverage is 100%, and description adds value beyond schema by explaining cursor usage, query examples, and performance tip for 'first' parameter. Enhances usability without redundancy.

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: 'List collections in the store, most recently updated first.' Specifies return fields (title, handle, ID, product count) and distinguishes from siblings like get_collection by stating it's used to find a collection's GID before other operations.

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: 'Use this to find a collection's GID before calling get_collection, update_collection, or add_products_to_collection.' Also explains cursor pagination and query syntax. Lacks explicit 'when not to use' but offers clear context for its role.

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 burden. It discloses ordering, filtering syntax, pagination method, and returned fields. However, it doesn't mention rate limits, authentication requirements, or idempotency. 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 three sentences with no waste. It front-loads the primary purpose, then adds filtering/pagination details, and closes with practical use cases. 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?

Given no output schema and no annotations, the description is quite complete: it specifies returned fields, ordering, filtering, pagination, and use cases. It could mention potential errors or rate limits, but for a list 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 has 100% coverage for its 3 parameters. The description adds value by providing examples of query syntax and explaining pagination context, going beyond the schema descriptions. Baseline 3 raised to 4 for this added 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 the action ('List customers'), the resource ('customers'), and adds ordering ('newest first by creation date') and returned fields. It distinguishes itself from sibling tools like 'create_customer' and 'update_customer' by focusing on listing.

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

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

The description explicitly states when to use this tool: 'to find customer GIDs before referencing them in draft orders or to segment for marketing.' It also mentions filtering capabilities. However, it does not explicitly state when NOT to use it or provide 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?

No annotations provided, so description carries full burden. It discloses cursor-based pagination, filtering, and returned data. Does not mention auth or rate limits, but adequately covers key behaviors.

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 paragraph well-organized: purpose, return fields, filtering, pagination. No redundant sentences, 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?

No output schema, but description enumerates returned fields. Covers pagination, sorting, filtering, and query syntax. Complete for a list tool 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 descriptions cover 100% of parameters. Description adds value through examples for the 'query' parameter, going beyond the schema. Still room for more detail on cursor 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?

Clearly states it lists draft orders with definition, ordering, and returned fields. Distinguishes from siblings like get_draft_order and complete_draft_order through context.

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 listing all draft orders, mentions filtering syntax, but lacks explicit when-to-use vs alternatives like get_draft_order. However, context signals are clear enough.

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

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

Even without annotations, the description discloses key behaviors: multiple fulfillment orders can exist per order, remaining quantity calculation, and returned fields (location, destination, line-item progress).

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 detailed yet concise, front-loading the primary action and providing necessary context in a structured manner 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?

For a tool with one parameter and no output schema, the description adequately explains the purpose, usage flow, and return values, making it complete for the AI agent to select and invoke correctly.

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

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

Schema has 100% coverage with a clear description and example for orderId. The description adds some context but does not significantly enhance parameter understanding beyond what the schema provides.

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 fulfillment orders for a Shopify order, explains what fulfillment orders are, and distinguishes it from related tools like create_fulfillment and get_fulfillment_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 explicitly positions this as the primary read tool before create_fulfillment, providing clear context for when to use it, though it does not 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?

No annotations provided, so description carries full burden. It discloses return fields, explains inactive location behavior, and implies read-only nature. Lacks mention of authentication, but otherwise transparent for a list 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?

Four sentences pack essential information without redundancy. Front-loaded with purpose, followed by return details, cross-references, and behavior note. Efficient 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?

Given no output schema, description compensates by listing returned fields and explaining GID usage and inactive location constraints. For a simple list tool with one parameter, it is 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?

Only one parameter 'first' with schema coverage 100%. The description adds no additional meaning beyond the schema, which already details min/max/default and a note. Baseline 3 is appropriate.

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

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

Description clearly states the tool lists store locations (physical or virtual), specifies types (warehouses, retail stores, drop-ship partners), and lists returned fields (name, active/inactive flag, city+country, GID). It is specific and distinguishes within the context of inventory and fulfillment operations.

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

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

Description explains that location GID is required by set_inventory_quantity and create_fulfillment, and that inactive locations cannot accept new inventory or fulfillments. This provides clear when-to-use context, though no explicit alternatives among siblings 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?

No annotations provided, so the description carries the full burden. It correctly identifies this as a read operation, describes the output fields, and normalizes empty results. It does not mention pagination beyond the 'first' parameter which is already in schema, but overall behavior is well-conveyed.

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: first states purpose, second explains return content, third gives usage guidance. Front-loaded with key information, no fluff, 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?

For a list tool with 3 parameters and no output schema, the description covers purpose, return structure, usage context, and a common scenario (empty results). It could mention pagination behavior (cursor-based) but overall 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 context for the 'namespace' parameter (scope to one app/integration, recommended for many metafields). However, it does not mention the 'first' parameter (pagination) though schema has 67% coverage. The description provides some added value beyond schema but not fully compensates for the missing parameter description.

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 metafields for a single Shopify resource, specifies what is returned (namespace.key, type, value, description), and distinguishes from siblings like set_metafield and delete_metafield. It is specific with verb and resource.

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 usage context: use before set_metafield or for auditing, and recommends passing namespace when resource has many metafields. However, it does not explicitly state when not to use it or name alternative tools beyond set_metafield.

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 pagination (cursor-paginated) and the returned content (field definitions, type handle, required fields). Could mention access requirements or rate limits, but for a read-only list tool, it is fairly transparent.

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: first states purpose, second explains content, third gives usage guidance and pagination. Front-loaded and concise with no waste.

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, description explains what definitions contain (type handle, field definitions, required fields) and mentions pagination. Adequate for a list tool with two 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 description coverage is 100%, and the description adds practical guidance: '25 is usually plenty — most stores have <50 metaobject types total' and explains cursor usage for pagination, enhancing understanding beyond 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 action (list metaobject definitions) and the resource (custom types/schemas on Shopify store). It differentiates from siblings by explicitly mentioning usage before list_metaobjects and create_metaobject.

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 advises when to use the tool: before calling list_metaobjects or create_metaobject. Implicitly excludes using it for querying instances or creating instances, providing clear context.

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

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

Describes return fields (name, handle, GID, status for publishable types) and cursor pagination with `after` parameter. No annotations exist, so the description carries the burden; it adequately covers read-only behavior and pagination, though could explicitly state non-destructiveness.

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?

Four concise sentences, front-loaded with purpose, no redundant information. Every sentence adds necessary context.

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 sufficiently explains return fields and pagination. It references sibling tools appropriately, making it complete for a listing 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?

All three parameters are described in schema (100% coverage). Description adds value by explaining the meaning of `type` (from list_metaobject_definitions) and cursor usage for `after`, beyond 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 explicitly states the tool lists instances of a single metaobject type, with concrete examples ('lookbook', 'product_feature'). It differentiates from siblings like get_metaobject (individual) and list_metaobject_definitions (type 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?

Provides clear context: use for listing instances of a type, obtain type handle from list_metaobject_definitions, and follow up with get_metaobject for full details. Implicitly advises when to use alternatives.

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

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

No annotations are provided, so the description must carry the full burden. It discloses pagination behavior (cursor-based, next cursor shown), ordering (newest first), and query syntax. It does not mention error handling or rate limits, but for a read-only list tool this is adequate.

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-loading the main purpose and returned fields, then adding pagination and usage guidance. Every sentence adds value with no wasted words.

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

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

Despite no output schema, the description enumerates the returned fields (name, total price, financial status, fulfillment status, timestamp) and covers pagination, ordering, and filtering. This is complete for a list tool given the 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?

Input schema has 100% description coverage for all 3 parameters. The description adds value by explaining the cursor-paginated behavior (relevant to 'after'), providing examples of common query filters (relevant to 'query'), and setting default page size context. This goes beyond 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?

Description clearly states it lists orders with specific returned fields (name, total price, financial status, fulfillment status, timestamp) and mentions ordering by creation date. It distinguishes itself from siblings like get_order and list_fulfillment_orders by noting it is used to find order GIDs before those calls.

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

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

Description explicitly states when to use this tool: to find order GIDs before calling get_order or list_fulfillment_orders. It also describes supported query syntax for filtering. While it doesn't explicitly list when not to use, the context is clear and provides sufficient guidance for an AI agent.

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 must disclose behavioral traits. It explains cursor-based pagination, that last line shows next cursor, and that it returns total inventory across all variants/locations. 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?

Four sentences, each serving a distinct purpose: action+returns, query syntax, pagination, usage context. No redundant 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?

No output schema, but description explains return fields and pagination. Covers query syntax and usage context thoroughly. Complete for a list tool with 3 parameters.

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

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

Schema coverage is 67% (2 of 3 params have descriptions). Description adds value by explaining query syntax with examples and clarifying pagination cursor usage. First parameter lacks explicit description but has default/min/max in 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?

Description clearly states it lists products with cursor-based pagination, specifies return fields (title, status, GID, total inventory), and mentions Shopify query syntax. This is specific and distinguishes from siblings like get_product (single product) and list_variants (variants).

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: to find product GIDs before calling product-scoped tools. Describes pagination pattern and query filtering capabilities. Does not explicitly state when not to use, but context is clear from sibling names.

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 accurately describes the data returned (read-only) and lists fields, but does not mention pagination behavior or cursor handling despite the 'first' parameter. No destructive side effects are claimed, so no contradiction, but missing pagination details reduces 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?

The description is three sentences: first sentence defines scope, second enumerates returned fields, third provides usage guidance. No unnecessary words, highly efficient 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 2 parameters and no output schema, the description gives a comprehensive overview of returned data and usage context. However, it lacks explanation of pagination mechanics for the 'first' parameter, which is needed for large product variant lists.

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%: productId is described as 'Product GID' but 'first' lacks any description. The description adds no extra meaning for 'first' beyond its existence, failing to compensate for the missing schema description. For a parameter controlling result count, this 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 it lists all variants of a single product along with option definitions and possible values, specifying the exact fields returned. It explicitly distinguishes from sibling mutation tools (create_variants, update_variants, delete_variants) by advising use before calling them.

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 it 'to inspect a product's full SKU matrix before calling create_variants/update_variants/delete_variants,' providing clear context. It does not explicitly state when not to use, but the read-only nature is implicit and alternatives are implied by sibling names.

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 full burden. It discloses the returned fields (topic, delivery format, endpoint, etc.) and mentions filtering by topic. However, it does not explain pagination behavior (though schema suggests it via 'first' and 'after' parameters) or potential performance implications of listing many webhooks.

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 no unnecessary words. It front-loads the core action and then adds relevant details in a structured manner, making it easy for an AI agent to parse quickly.

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 lists key return fields (topic, delivery format, endpoint, API version, filters). It also explains the filtering option. It does not mention pagination or ordering, but overall it provides sufficient context for a list 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?

Only 33% of parameters have schema descriptions. The description adds value by explaining the 'topics' filter and providing example values. It does not elaborate on 'first' (page size) or 'after' (cursor) beyond their schema definitions, which is a gap given low coverage.

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

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

The description clearly states the tool's purpose: 'List webhook subscriptions on the store.' It explains what webhooks are and mentions specific event topics, delivery targets, and returned fields. This distinguishes it from siblings like 'create_webhook', 'delete_webhook', and 'get_webhook'.

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 advises using the tool to 'audit existing automation hooks before creating new ones,' which provides clear context for when to use it. However, it does not explicitly state when not to use it or mention alternatives like 'get_webhook' for individual subscriptions.

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 the full burden. It explains return values (refund GID and total amount), restockType behaviors, and the notify option. However, it does not mention idempotency, rate limits, or authorization requirements, which are common behavioral concerns.

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 moderately sized and front-loaded with the core action. It efficiently covers key details without unnecessary repetition. Minor improvement could be made by structuring it into bullet points for quick scanning.

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 moderate complexity (6 parameters, nested objects) and lack of output schema, the description is complete: it covers what the tool does, when to use it, parameter behaviors, return values, and customer notification. No obvious gaps.

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

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

Schema description coverage is 100%, but the description adds value by clarifying when to omit refundLineItems, explaining the restockType enum in practical terms, and describing shipping options. This goes beyond the schema's basic 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 tool's purpose is clearly stated: it issues a refund for specific line items, shipping, or both. It distinguishes from the sibling tool cancel_order by explicitly noting that refund_order is for partial refunds, while cancel_order with refund=true handles full refunds.

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 outlines when to use this tool versus cancel_order, and provides scenarios such as refunding a single item, shipping, or an adjustment. It also explains the restockType controls and the notify parameter.

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 fully discloses behavioral traits: async execution for larger batches (response includes job ID and done status), silent skipping of non-members, and that it only removes membership without deleting or modifying products. This is comprehensive for a mutation 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?

The description is three sentences, each delivering specific value: the action, async note, confirmation that products are not deleted. No unnecessary words, and the core purpose is front-loaded.

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

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

The description covers essential aspects: what it does, how it works (async, silent skip), and what it does not do (delete products). The schema fully documents parameters. Without an output schema, the mention of job ID and done status is sufficient context. Sibling references help orientation.

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

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

The input schema covers both parameters fully (100% description coverage). The description adds context about the response structure and async behavior but does not add new meaning to the parameters themselves beyond what is in the schema. Thus a baseline score of 3 is appropriate.

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

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

The description clearly states the action (remove products from a manual collection) and distinguishes it from the sibling tool add_products_to_collection by referencing its similarity. It also mentions async behavior for larger batches, adding specificity.

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 tells when to use the tool (to remove products from a manual collection) and provides context about silent skipping of products not in the collection. It references the sibling tool add_products_to_collection, giving a comparison, but does not explicitly list when not to use or 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?

Despite no annotations, the description discloses the behavior of silently ignoring missing tags, implying idempotency. It does not cover auth or error handling, but the operation is simple and the disclosure is sufficient for most use cases.

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

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

Two sentences, no redundancy, and front-loaded with the core action and resource list. 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's simplicity, no output schema, and two well-documented parameters, the description fully satisfies what an agent needs: what it does, how it behaves on missing tags, and alternatives.

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?

Input schema covers 100% of parameters with detailed descriptions, including the GID format and normalization behavior. The tool description does not add new parameter-level information beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Remove tags') and the scope ('any taggable Shopify resource'), listing specific resource types. It also distinguishes from sibling tools like update_product/update_customer that replace the full tag set, making purpose unambiguous.

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

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

Explicitly states that absent tags are silently ignored and directs users to alternative tools for replacing the full tag set, providing clear when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries full burden. It discloses that positions are 1-indexed and must be unique across variants, and that changes affect display order. It does not mention potential side effects like error handling or permissions, but for a mutation tool, it sufficiently explains the core behavior.

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 the purpose, and every sentence adds value. It is concise with no redundant 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 the tool's simplicity (2 required params, no output schema), the description fully covers constraints and usage. It explains position indexing, uniqueness, and partial updates. The agent can confidently invoke this tool without missing 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?

The input schema provides minimal descriptions for productId and positions, but the description adds significant meaning: positions are 1-indexed, must be unique, and only changing variants need to be provided. This compensates for schema brevity and gives the agent clear instructions on how to fill the fields.

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

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

The description clearly states the verb 'Set' and resource 'display order of variants on a product', specifying that it affects order on product page and admin. This distinguishes it from sibling tools like 'update_variants' or 'create_variants' which handle different aspects of variants.

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

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

The description provides a key guideline: 'Only provide the variants whose positions are changing — others stay where they are.' This tells the agent how to structure input. However, it does not explicitly state when to use this tool over alternatives, though no sibling tool exists for reordering, making the context clear enough.

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

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

With no annotations, the description carries full burden. It explains the output format (ASCII table or raw JSON) but does not explicitly state the tool is read-only or mention any side effects, auth requirements, or limits. It provides reasonable but not comprehensive behavioral cues.

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

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

The description is concise and well-structured: a single purpose sentence, a brief explanation of ShopifyQL, and two illustrative examples. Every sentence adds information, no fluff.

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

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

Given the lack of output schema, the description adequately describes the return format and provides examples. However, it could mention error handling, query limits, or the read-only nature for completeness. Still, it covers the core functionality well.

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

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

The input schema already provides descriptions for both parameters (100% coverage). The description adds value by explaining ShopifyQL and giving concrete examples (e.g., 'FROM sales SHOW total_sales BY day SINCE -30d TIMESERIES'), which clarify the query parameter beyond the schema's brief description.

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 'Run a ShopifyQL query against the store and return the result as a rendered ASCII table', using a specific verb ('run'), resource ('ShopifyQL query'), and output format. It distinguishes itself from sibling CRUD tools by being a query/analytics tool.

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 versus alternatives, but its purpose as an analytics query tool is implied. No exclusions or alternative suggestions are provided, leaving the agent to infer usage context from the tool's name and examples.

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 explains the overwrite behavior, uniqueness constraint, reason code recording, and audit logging. Does not mention side effects, but overall transparent.

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 4 sentences, front-loaded with the main action, and each sentence adds useful 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?

For a mutation tool with 4 parameters, the description covers the operation, parameter origins, reason codes, and side effects (audit log). No output schema needed.

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

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

Schema coverage is 100% but description adds value by explaining how to obtain inventory_item_id and location_id from other tools, and describes reason codes in detail beyond 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?

Description clearly states the verb 'Set' and the resource 'absolute available inventory for one variant at one location'. It is specific and distinguishes from siblings as no other tool modifies inventory levels.

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 context on when to use (direct overwrite) and gives examples of reason codes with their typical use cases. Does not explicitly state when not to use, but no competing sibling tool exists.

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

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

Discloses upsert logic, type/value serialization, and error format via MCP. No annotations provided, so description carries burden. Covers key behaviors without 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?

Single paragraph with clear logical flow: purpose, uniqueness, value format, error handling. No redundant sentences.

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, but description omits return value on success. Given complexity, missing return info reduces completeness. Mentions errors but not success 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 100% (baseline 3). The description adds context about the triple as unique identifier and serialization rules per type, adding value beyond 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 explicitly states the tool upserts a single metafield on supported Shopify resources, listing resource types. It clearly distinguishes from siblings like delete_metafield.

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

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

It explains the upsert behavior and unique triple, implying when to use. Alternative tools like delete_metafield are indirectly suggested through sibling list, but no explicit 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?

Warns that changing handle breaks existing links without redirects, which is critical behavioral info. No annotations provided, so description carries full burden.

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 covering purpose, usage, and warning. Extremely efficient with no fluff.

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

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

Covers all key aspects for an update tool: what fields, how to use, side effects. No return value explanation but acceptable given no output schema.

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

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

Adds meaning beyond schema: clarifies description is HTML, handle change implications, and that empty string clears description. Schema coverage is 100% so baseline is 3.

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

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

The description clearly states it updates a collection's title, description, or handle, and distinguishes from membership-changing 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?

Explicitly explains when to use (update title/desc/handle), how to use (omit unchanged fields), and points to alternative tools for membership changes.

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 fully discloses patch behavior ('omitted fields stay as-is'), tag replacement semantics, and uniqueness constraints. It does not cover authorization needs or error handling, but the disclosed details are sufficient for a straightforward update 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?

The description is a single paragraph, front-loaded with the main purpose, and every sentence adds value. No redundancy or 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?

Despite no output schema, the description covers update semantics, constraints, and alternatives for related operations (tags, addresses, marketing consent). It could mention error responses or required permissions, but the provided information is sufficient for typical 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 coverage is 71% (5 of 7 parameters described). The description adds critical context: 'tags is a full replacement', 'omitted fields stay as-is', and uniqueness constraints for email/phone. The term 'name' in the description could be ambiguous (firstName/lastName), but the schema clarifies. Overall, it adds value beyond the schema.

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

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

The description clearly states 'Update an existing customer's profile fields' and lists specific fields (email, name, phone, tags, internal note). It distinguishes from sibling tools like add_tags/remove_tags and address-specific mutations, establishing a clear 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 tells when to use this tool (for updating profile fields) and when to use alternatives: add_tags/remove_tags for additive/subtractive tag changes, address-specific mutations for addresses, and customerEmailMarketingConsentUpdate for marketing consent. Also notes uniqueness constraints for email/phone.

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 the critical behavioral nuance that lineItems replaces entirely, and states no payment triggering. Lacks permissions/rate limits, but with no annotations, the description carries the burden 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?

Four sentences with zero fluff. Front-loaded with the main action, then critical behavioral note, then exclusions, then usage tip. Every sentence adds essential 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?

Covers all key aspects: purpose, constraints (OPEN only), behavioral warning (lineItems replace), exclusion of completed drafts, and guidance on pausing. No output schema needed for this 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?

Input schema has 100% description coverage, so baseline is 3. The description adds extra guidance for lineItems (e.g., read current items first) and reiterates constraints, providing value beyond the schema.

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

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

The description clearly states it modifies existing OPEN draft orders, specifying fields (customer, email, note, tags, line items) and contrasting with completed drafts. This distinctively differentiates from sibling tools like create_draft_order and complete_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?

Explicitly says when to use (OPEN drafts) and when not to (completed drafts), provides alternatives (use order tools for real orders), and gives guidance on pausing drafts without triggering payment.

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 reveals key behaviors: Shopify auto-derives URL for known carriers, omitted fields unchanged, notifyCustomer triggers email. Lacks mention of idempotency or permissions, but covers main traits.

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 states purpose, second provides usage and parameter semantics. No filler; 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?

Covers all parameters and key behaviors. Does not describe return value or error conditions, but no output schema exists; given complexity, this is mostly 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 only 20%, but description adds meaning: company+number suffice, URL auto-derived, notifyCustomer controls re-sending. This compensates for sparse schema descriptions.

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

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

The description clearly states the action ('Update or add tracking info on an existing fulfillment') and distinguishes from sibling tools like create_fulfillment and cancel_fulfillment by specifying it is for after-the-fact corrections.

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 tells when to use: after create_fulfillment without tracking, or when fixing a wrong tracking number. Provides guidance on parameters (company+number sufficient) and optional notifyCustomer behavior.

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 the full transparency burden. It discloses key behaviors: upsert semantics, handle redirection, type immutability, and field clearing. It does not mention permissions, rate limits, or error conditions, but the provided details are sufficient for safe invocation.

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

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

The description is concise and well-structured. It front-loads the main purpose and then sequentially covers key points (upsert behavior, clearing fields, redirect, type restriction). Every sentence adds necessary information 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?

Given the tool's complexity (5 parameters, upsert logic, handle management) and the absence of an output schema, the description covers essential behavioral and usage details. It could slightly improve by mentioning the return value (e.g., the updated metaobject), but that is not critical 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 100%, but the description adds significant value: it explains the upsert mechanism for fields, how to clear fields, the condition for redirectNewHandle, and the status constraint. For the fields parameter, it details how to serialize values (primitives as literal strings, JSON types as JSON-encoded), which goes beyond the schema description.

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 'Update' and the resource 'metaobject', specifying the modifiable aspects (handle, field values, publishable status). It distinguishes from sibling tools like create_metaobject and delete_metaobject by noting that the type cannot be changed, thereby preventing misuse.

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 'how-to' guidance: fields are upserted by key, pass only changed fields, clear a field with empty string, use redirectNewHandle for handle changes, and note that type requires delete and recreate. However, it does not explicitly state when to avoid using this tool (e.g., when needing to change the type), though that is implied.

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 fully discloses behavioral traits: it notes that most order fields are immutable, and tags/customAttributes are full replacements. This informs the agent of side effects and limitations.

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, well-structured, and front-loaded with purpose. 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?

Given no output schema and no annotations, the description is complete: it covers updatable fields, immutable fields, replacement semantics, and typical use cases. No additional information is needed for an agent to correctly invoke the 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?

The input schema covers all 5 parameters with descriptions, achieving 100% coverage. The description adds context beyond the schema (e.g., which fields are immutable, replacement behavior), raising it above the baseline of 3.

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

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

The description clearly states the tool updates specific metadata fields (email, tags, note, customAttributes) on an existing order. It differentiates from siblings like refund_order and cancel_order by noting which fields are immutable, making the purpose unambiguous.

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

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

The description explicitly tells when to use (fixing email, adding note, attaching tags) and when not (for line items, totals, etc.), suggesting alternatives (refund/cancel then create). It also advises reading current tags before merging, providing complete 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. Discloses partial update behavior and that ARCHIVED status hides product but preserves order history. Lacks mention of authorization needs or reversibility, but provides good operational context for a mutation 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 well-structured sentences. First sentence front-loads purpose and fields. Second sentence covers behavior and alternatives. No redundant words. 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?

Given no output schema and low schema coverage, description covers the tool's full scope: what it does, how to use it (partial update), effect of status, and pointers to other tools for related operations. Complete enough 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 low (14% only for id and status enum). Description adds value by explaining partial update semantics and 'only send changed fields' pattern. Explicitly describes status options. Does not add details for other params beyond listing, but enough for core fields.

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

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

Clearly states it updates core fields of an existing product, lists specific fields (title, description, vendor, productType, tags, status). Distinguishes from sibling tools like update_variants, upload_product_image, etc., by specifying what not to use it for.

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 advises to only provide fields to change, with omitted fields left untouched. Explains effect of status=ARCHIVED. Directs user to alternative tools for variants, prices, inventory, and images, giving clear 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?

Although no annotations exist, the description explains that updates are per-variant and only specified fields are written, and clarifies the meaning of inventoryPolicy values. It does not cover potential side effects or rate limits, but is still sufficiently transparent for a simple update tool.