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

With no annotations provided, the description must carry the full transparency burden. It only restates the delta semantics ('increase or decrease') which are already in the schema, and does not disclose side effects, permission requirements, idempotency, or return behavior. This is a significant gap for a mutating operation.

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

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

The description is a single concise sentence with the main action front-loaded. The parenthetical '(increase or decrease)' is slightly redundant with the schema but does not bloat the text. It earns its place as a quick summary, though it could be shorter without loss.

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 4-parameter tool with no output schema, the description is minimally viable. It clearly explains the core operation but omits practical context such as when to use it, what the tool returns, and whether the 'reason' parameter is expected in certain scenarios. This is adequate but not comprehensive.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional parameter meaning beyond what the schema provides; the 'increase or decrease' wording duplicates the delta property's description. No extra context about how parameters interact is given.

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 'adjusts' with specific resources ('inventory of an item at a location') and the nature of the change ('increase or decrease'). This distinguishes it well from sibling tools like get_inventory_levels or get_product_inventory, which are read-only 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?

The description implies usage for modifying inventory amounts but does not explicitly state when to choose this tool over alternatives or provide exclusions. It lacks guidance like 'use this for corrections or receiving' or 'if you need to view inventory, use get_inventory_levels instead.' Usage context is only implied by the tool's purpose.

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 indicates a read-only operation ('Lists') and defines the exact scope ('all countries the shop ships to'). Though no annotations are present, the verb clearly signals a non-mutating operation, which is sufficient for a zero-parameter tool. It lacks mention of return format, but that is a minor omission.

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

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

The description is a single sentence, front-loaded with the verb and object, and contains no filler. It is maximally concise while remaining informative.

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

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

For a simple list operation with no parameters, output schema, or annotations, the description covers the essential behavior. It could be improved by specifying the return format (e.g., country codes vs. names), but it is sufficient for the agent to select and invoke 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 tool has zero parameters, so the description adds no parameter-specific information. According to the guidelines, a baseline of 4 applies when there are no parameters, and the description does not introduce any confusion.

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 ('Lists') and resource ('all countries the shop ships to'), clearly differentiating it from sibling tools like shop_locales (which likely handles locales) and shop_policies. It precisely defines the tool's 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?

No guidance is provided on when to use this tool versus alternatives. The description simply states what it does, without mentioning shop_locales, shop_info, or other related tools, and does not specify use cases or exclusions.

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

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

No annotations are provided, and the description does not disclose side effects such as payment reversal, inventory restocking, or permission requirements. The schema hints at refund and notifyCustomer options, but the description does not elaborate on the consequences of cancellation. This is a significant gap 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 a single concise sentence with no wasted words. It is appropriately sized for the tool's simplicity, though it could benefit from including optional parameters. Structure is clear 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 destructive operation with no annotations or output schema, the description is incomplete. It does not explain the order lifecycle after cancellation, potential side effects, or error conditions. The schema provides parameter details but not broader execution 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 schema provides 100% coverage of parameters, with clear descriptions for id, reason, refund, and notifyCustomer. The description adds no additional parameter-level meaning, so it relies entirely on the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'cancel' and the resource 'order', making it unambiguous. It distinguishes from sibling tools like list_orders or get_order, which are read operations. However, it lacks additional context such as the Shopify domain or optional behavior.

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

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

The description offers no guidance on when to use this tool versus alternatives like update_order or create_draft_order. There is no mention of prerequisites, such as order status or payment state. This leaves the agent to infer usage from the schema alone.

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 of behavioral disclosure. It only reveals the discount type capability and omits side effects, required permissions, uniqueness constraints, activation timing, or return value details. For a creation tool, this is insufficient 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 a single, efficiently structured sentence without filler. It leads with the verb and resource, making it easily scannable and appropriately concise relative to the tool's complexity.

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

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

With 8 parameters, no annotations, and no output schema, the description leaves out critical operational context such as what the function returns, whether the discount is immediately active, and error behavior. The schema covers parameters but not the broader usage 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 schema already describes all 8 parameters with 100% coverage, including the 'use either percentage or amount' caveat. The description's mention of percentage and fixed amount adds no new parameter-level meaning beyond the schema, so the baseline of 3 is applied.

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 ('creates') and the resource ('discount code'), and goes further by specifying the two supported types ('percentage or fixed amount'). This makes it easy to select and distinguishes it from sibling list tools like list_discount_codes and list_automatic_discounts.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of whether this is for manual discount codes only, or how it relates to automatic discounts, prerequisites, or scenarios where another tool would be more appropriate.

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 available, so the description must carry the full behavioral burden. It only states the create action without disclosing side effects, permission requirements, or behavior on duplicate emails, which is a significant gap 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 a single, concise sentence that is front-loaded with the core action. It is efficient and free of fluff, though it provides no elaboration, which is acceptable for a straightforward create operation.

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

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

With no annotations or output schema, the description does not explain the return value, potential errors, or validation rules beyond the schema. For a mutation tool with 7 parameters, this is insufficient context for an agent to fully understand the operation.

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

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

The input schema provides full descriptions for all 7 parameters (email, note, tags, phone, lastName, firstName, addresses), so the schema already covers parameter meaning. The description adds no extra semantic detail beyond the schema, yielding the baseline score 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 'Creates a new customer' uses a specific verb and resource, clearly distinguishing it from sibling tools like update_customer, delete_customer, and get_customer. It unambiguously states the tool's primary 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?

No guidance is provided on when to use this tool versus alternatives, such as whether to create a new customer or update an existing one via update_customer. There is also no mention of prerequisites or scenarios where this tool is appropriate.

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 of behavioral disclosure. It simply states the fact of creation, without mentioning side effects, permissions, idempotency, or whether the draft order is instantly available or requires further processing. The agent receives no insight into the tool's behavior beyond the tautological action.

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

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

The description is a single, direct sentence with no filler or redundancy. It is front-loaded with the key verb and object, making it immediately clear what the tool does. This meets the highest standard for conciseness.

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

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

The tool has four parameters and no output schema or annotations, yet the description provides no additional context beyond the bare action. It does not explain return value, error conditions, or the distinction between a draft order and a regular order. This is a clear gap for a creation tool, leaving the agent with only the schema to work from.

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 describes all four parameters with 100% coverage, and the description adds no additional semantic nuance. Since the schema handles parameter meaning, the baseline score of 3 is appropriate; the description does not compensate for any gaps because there are none.

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 ('Creates') and the resource ('a draft order'), which distinguishes it from sibling tools like cancel_order or update_order. However, it does not elaborate on what a draft order is, which could cause ambiguity in e-commerce contexts.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, typical use cases, or scenarios where other tools (e.g., create_order) would be more appropriate.

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, but it offers no behavioral details such as effects, return values, validation, or side effects. It merely restates the action implied by the name.

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?

A single, clear sentence with no extraneous words; earns a 5 for efficiency and front-loading the core 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?

While the schema documents parameters, the description lacks context about what happens upon creation (e.g., response object, duplicate handling, or status defaults). For a tool with no output schema and no annotations, this is a significant 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?

All 6 parameters are fully described in the schema with 100% coverage, so the description adds no additional meaning. The baseline of 3 applies because the schema already handles parameter documentation.

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

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

The description uses the specific verb 'creates' and resource 'product', clearly distinguishing it from sibling tools such as update_product and delete_product. It is unambiguous and directly states the action.

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

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

No guidance is provided about when to use this tool versus alternatives; it simply states the action with no context about prerequisites or comparison to update/list tools.

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

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

With no annotations provided, the description must disclose behavioral traits on its own. It does state that deletion 'cannot be undone,' which is a critical behavioral fact. However, it does not mention potential side effects (e.g., effects on historical orders), permissions required, or what the response looks like after deletion.

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

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

The description is a single, concise sentence that front-loads the action and immediately states the most important caveat (irreversibility). No wasted words or 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?

For a simple tool with one well-documented parameter and no output schema, this description is largely complete: it states the purpose and the key destructive consequence. It could be enhanced by mentioning alternatives or side effects, but the core information needed to safely invoke the tool is present.

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 a complete description for the single 'id' parameter (Shopify Customer GID), so schema coverage is 100%. The description adds no additional parameter meaning, but the baseline of 3 is appropriate because the schema fully handles parameter semantics.

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 specifies the action ('Deletes') and the resource ('a customer'), distinguishing it from sibling tools like delete_product or update_customer. It also includes a prominent warning about irreversibility, which aids selection.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or safer alternatives like 'update_customer' for deactivating a customer. The warning about irreversibility is cautionary but does not provide 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?

No annotations are provided, so the description carries the full burden. It discloses a critical behavioral trait ('cannot be undone!'), which is essential for a destructive operation. However, it does not mention effects on related resources (variants, inventory, references) or error conditions.

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?

One sentence with a clear verb, resource, and a high-impact warning. No redundant language; every word contributes to understanding the tool's destructive nature.

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 documented parameter, the description is nearly complete. It lacks mention of the return value or behavior for non-existent products, but these are minor given the direct operation. The irreversibility warning adds necessary 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 schema description covers 100% of the single parameter ('Shopify Product GID'), so the description adds no parameter-level meaning. Baseline 3 is appropriate since the schema already fully documents the 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?

The description uses a specific verb 'Deletes' with a clear resource 'product', making its purpose unambiguous. It is easily distinguished from sibling tools like create_product and update_product, and the irreversibility warning further clarifies the action.

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 over alternatives, but the permanence warning implies caution. Sibling names (create_product, update_product) provide implicit context, but no explicit prerequisites or when-not-to-use guidance is given.

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 of disclosing behavioral traits. It only states that the tool 'gets detailed information,' which implies a read-only operation, but it does not disclose whether any permissions are required, what happens if the customer does not exist, or what specific fields are included in 'detailed information.' This is a significant gap for a tool with no output schema.

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

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

The description is a single concise sentence that is front-loaded with the action ('Gets') and the resource ('customer'). It contains no filler or redundant information, making it appropriately sized 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 the tool's simplicity (one required parameter, no output schema, no annotations), the description is minimally viable but lacks detail about the return format or error behavior. It fails to explain what 'detailed information' entails, leaving the agent uncertain about the expected response. This represents a clear gap, making it a 3 rather than a 5.

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 the single parameter 'id,' explicitly describing it as 'Shopify Customer GID.' The description adds no additional parameter context, but the baseline of 3 applies because the schema already fully documents the parameter. No further compensation is needed.

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 'gets' and clearly identifies the resource as 'a single customer,' distinguishing it from sibling tools like list_customers and customer mutation tools. The focus on 'single customer' contrasts with the plural list operation, 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 no explicit guidance on when to use this tool versus alternatives such as list_customers or create/update/delete customer. While the name and description imply its use for retrieving one customer's details, there is no mention of appropriate context, exclusions, or fallback options, leaving the agent without clear decision-making support.

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 but only states the counting action without disclosing side effects, read-only nature, or performance characteristics. It does not explicitly confirm that this is a safe read operation.

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

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

The description is a single, focused sentence with no extraneous information, effectively front-loading the 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?

For a simple zero-parameter count tool, the description is nearly complete, but it does not explicitly state the return format (e.g., an integer). However, the tool name 'get_customer_count' makes the return value obvious, so the gap is minimal.

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 tool has zero parameters, and the schema coverage is 100% (vacuously). The description doesn't need to add parameter details, and none are missing.

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 'Counts customers in the shop' with a specific verb ('counts') and resource ('customers in the shop'), distinguishing it from sibling tools like list_customers or get_order_count. It's unambiguous about its 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?

No guidance is provided on when to use this tool compared to alternatives like list_customers or get_customer. The description simply states the action without explaining use cases or exclusions.

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

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

With no annotations provided, the description carries the full burden. It indicates a read operation via 'shows', which implies non-destructive behavior, but does not disclose any additional behavioral traits such as response format, whether zero-quantity locations are included, or permissions needed.

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, front-loaded sentence that conveys all essential information with no wasted words. It is highly concise 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?

For a simple read tool with one parameter and no output schema, the description is largely complete: it states what is shown and the scope. Minor gaps include lack of return structure detail, but this is not critical for selection and 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% as the single parameter inventoryItemId has a description ('Inventory Item GID'). The tool description adds little to parameter understanding beyond that, so the baseline 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 tool shows inventory quantities for a product at all locations, with a specific verb ('shows') and resource ('inventory quantities'). It is clear, but does not explicitly distinguish from sibling tools like get_product_inventory, which may overlap.

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?

Usage context is implied: the agent can infer it should be used when needing inventory levels across all locations for a given product. However, there is no explicit guidance on when to use this versus alternatives such as get_product_inventory or adjust_inventory.

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

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

No annotations are provided, so the description must bear the burden of behavioral disclosure. It only states that the tool 'gets detailed information' but does not describe error behavior, permissions, rate limits, or return structure. Without annotation support, this is a significant gap.

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, focused sentence with no verbose or redundant content. It is front-loaded with the action and resource, making it easy to scan and understand.

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

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

The tool is a simple get-by-ID operation, and the description provides the core purpose. However, with no output schema describing the return value and no annotations, the vague phrase 'detailed information' leaves the agent guessing what data will be included. It is minimally viable but with clear gaps.

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

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

The input schema has 100% description coverage for the `id` parameter, including a clear example of the expected Shopify GID format. The description adds no parameter-level information beyond what the schema already provides, so 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 uses a specific verb ('gets') and resource ('a single order'), making the purpose immediately clear. It distinguishes itself from sibling tools like list_orders by explicitly specifying 'single order', so an agent can select it correctly.

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?

There is no guidance on when to use this tool versus alternatives (e.g., list_orders). It does not mention prerequisites, exclusions, or scenarios where another tool would be more appropriate. The implied usage from 'single order' is minimal and not explicit 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?

No annotations are provided, so the description must carry the burden of disclosing behavior. It implies a read-only operation by saying 'counts', but it does not explicitly state that it returns a numeric count or that it has no side effects. This is a minimal but acceptable level of transparency for a simple count 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 concise sentence that front-loads the primary action ('Counts orders') and adds crucial context about optional filters. Every word carries value with 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?

The tool is simple with one optional parameter and no output schema. The description adequately explains what it does and the filter types. However, it could explicitly state that it returns a count (number) to be fully complete, but this is implied and acceptable for a tool of this simplicity.

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

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

The schema descriptions cover 100% of parameters, including an example filter, so the baseline is 3. The tool description adds that filters can be by status or date range, which aligns with the schema example but does not introduce new details beyond what the schema already 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 counts orders, using a specific verb ('counts') and resource ('orders'). It also distinguishes from related tools like get_product_count and get_customer_count by specifying the resource type, and from list_orders by emphasizing counting rather than 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 provides clear context that the tool counts orders and optionally filters by status or date range, which implies when to use it over list_orders. However, it does not explicitly mention alternatives or when not to use it, so it misses the threshold for a 5.

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 bears the burden. 'Gets' indicates a read operation, but it does not disclose potential errors (e.g., 404 if not found), permission requirements, or return format. The simplicity of a getter partially mitigates this, but more detail would improve 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 a single, concise sentence that immediately states the action and target. No unnecessary words or 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?

For a simple getter with one well-documented parameter, the description is adequate. It does not explain the return structure, but given the absence of an output schema, a bit more detail about what 'detailed information' includes would be helpful. However, the tool is straightforward and sibling context clarifies its role.

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

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

Schema coverage is 100% with the id parameter fully described. The description adds only 'by its ID', which adds no meaning beyond the schema. It reinforces the parameter usage but does not provide additional semantic value.

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

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

The description clearly states the tool retrieves detailed information for a single product by ID. It distinguishes itself from sibling tools like list_products (which lists multiple products) and other product 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?

The description implies usage when a specific product ID is known and detailed information is needed. It does not explicitly contrast with alternatives, but the context from sibling tools makes the use case clear.

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

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

No annotations are provided, so the description carries the full burden. It only states the basic counting behavior and omits important details like whether all products or only published products are counted, the return type, and any caching or rate-limit 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 six words long, front-loaded with the verb, and contains no filler or redundant information. It is appropriately sized for a zero-parameter 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?

For a simple zero-parameter count tool, the description is adequate but lacks an explicit statement about the return format and any differentiation from similar count or dashboard tools. It leaves minor gaps in selecting the right tool among siblings.

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 tool has zero parameters and the schema description coverage is 100%, so no parameter explanations are needed. The phrase 'in the shop' adds slight context but parameter semantics are inherently simple; baseline 4 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 the specific verb 'Counts' and identifies the resource 'products' with scope 'in the shop', clearly distinguishing it from sibling tools like get_order_count and get_customer_count.

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?

There is no guidance on when to use this tool versus alternatives such as list_products or shop_dashboard_summary. It does not mention exclusions, prerequisites, or explicit 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'shows' inventory, which implies a read operation, but it does not disclose whether inventory is aggregated across locations, whether out-of-stock variants are included, or what the response structure looks like. This leaves significant behavioral ambiguity.

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

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

The description is a single, front-loaded sentence that directly states the tool's core function with no extraneous words. It is concise, well-structured, and 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 one-parameter tool, the description covers the basic purpose but lacks critical context such as the exact return format (e.g., list of variants with quantities) and how it differs from related inventory tools like get_inventory_levels. Since there is no output schema, the description should provide more explicit details about what the agent can expect.

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 productId is fully documented in the schema with a clear description ('Shopify Product GID') and type, giving 100% schema coverage. The tool description adds no additional parameter-level detail, so the baseline of 3 applies without extra value from the 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 uses the specific verb 'shows' with a clear resource ('full inventory of a product') and scope ('all variants'), making the tool's primary function unambiguous. However, it does not explicitly differentiate from sibling tools like get_inventory_levels, which could also be interpreted as inventory-related, so it stops short of full distinction.

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

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

There is no guidance on when to use this tool versus alternatives such as get_inventory_levels or get_product. The description states what the tool does but does not provide context on preferable use cases, conditions, or exclusions, leaving the agent without directional help.

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 responsibility for behavioral disclosure. It fails to mention that arbitrary GraphQL queries may include mutations (potentially destructive), that the response is raw GraphQL, or any rate limiting/auth requirements. This is a significant gap for a generic execution 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 two sentences, front-loaded with the core action, and contains no filler. Every word earns its place, making it appropriately concise 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?

The tool is a generic GraphQL executor with no output schema. The description is minimal but sufficient for a simple passthrough tool; however, it omits details about response format and error handling, which would be helpful given the absence of annotations and output schema. It is adequate but not comprehensive.

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

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

The input schema provides full descriptions for both 'query' and 'variables', so schema coverage is 100%. The description adds no additional meaning about parameter formats or usage beyond what the schema already states, matching 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's function with a specific verb ('Executes') and resource ('arbitrary GraphQL query against the Shopify Admin API'). It also distinguishes itself from siblings by noting it's 'For advanced queries not covered by other tools,' making its purpose unique.

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 phrase 'For advanced queries not covered by other tools' provides explicit guidance on when to use this tool versus the many specialized sibling tools. However, it does not name specific alternatives or describe when not to use it, so it falls short of a strong 5.

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 of behavioral disclosure. It does not mention pagination, sorting, filtering, return format, or any side effects. The existence of a 'first' parameter implies pagination but the description neither confirms nor explains it.

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

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

The description is extremely short, which is concise, but it provides so little information that it amounts to under-specification rather than effective conciseness. It restates the tool name without adding context or structure.

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

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

The tool has a single parameter, no output schema, and no annotations, but the description still fails to convey what an automatic discount is, what the list contains, or any behavioral details. It is incomplete even for a simple 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?

The schema fully documents the single parameter 'first' with a clear description ('Number of results (max 50)'), and schema coverage is 100%. The description adds nothing about parameters, but since the schema is complete, the baseline 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 'Lists automatic discounts' is essentially the tool name rephrased, providing no additional differentiation from sibling tools like list_discount_codes. It states a clear verb and resource but fails to clarify what qualifies as an automatic discount or how this differs from other list 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?

No guidance is provided on when to use this tool versus alternatives such as list_discount_codes or create_basic_discount. The description lacks any context, prerequisites, or exclusions, leaving the agent without direction for tool selection.

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

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

With no annotations, the description must carry behavioral disclosure, but it fails to mention pagination limits or filtering capabilities. The word 'all' contradicts the schema's 'first' parameter (max 50), which is misleading about the tool's actual 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 a single, concise sentence with no redundant words. It front-loads the core function, achieving maximum efficiency in minimal space.

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 should explain return format and behavior. It omits that results are paginated and filterable, and the 'all' claim is inaccurate. The tool lacks critical context for an agent to use it 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 tool description adds no extra meaning to the parameters 'first' and 'query', relying entirely on the schema for their semantics.

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 "Lists all collections in the shop" uses a specific verb ('lists') and resource ('collections'), clearly distinguishing it from sibling tools like list_products and list_orders. Even without a title, the purpose is 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 no guidance on when to use this tool vs alternatives, nor any exclusions or prerequisites. It only restates the function, leaving the agent to infer usage from the name alone.

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 behavioral disclosure burden. It implies a read-only operation ('Lists') but does not disclose pagination behavior, result limits, or the exact filter query syntax. The vague 'etc.' leaves important filtering capabilities unspecified.

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?

A single sentence that states the core function and a key capability. There is no redundant information, and the important phrase 'Lists customers in the shop' appears first. This is appropriately concise.

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

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

The tool is simple with three optional parameters and no output schema, but the description omits usage guidance and return format. It does not explain how pagination works (despite the 'after' cursor in the schema) or what fields are returned per customer. While the schema covers parameter syntax, the description is thin for an AI agent trying to decide between list_customers and get_customer.

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

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

The schema covers 100% of parameters with descriptions, providing the baseline of 3. The description adds that filtering is by 'name, email, etc.', but the schema's examples ('email:test@example.com' or 'country:DE') are more specific. Therefore, the description adds minimal semantic 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 uses the specific verb 'Lists' and names the resource 'customers', clearly identifying it as a read-only listing tool. It also mentions filterability by name/email, setting it apart from create/update/delete siblings. However, it doesn't explicitly distinguish itself from other list_* tools or get_customer.

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 no guidance on when to prefer this tool over alternatives like get_customer for single-customer lookups or list_orders for other resources. There are no exclusions, prerequisites, or alternative tool references. It merely states what it does without 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 the full burden of behavioral disclosure. It only says 'lists all discount codes,' which implies a read-only operation, but it does not mention pagination behavior (despite the 'first' parameter with a max of 50), response format, or any other side effects. Minimal behavioral context beyond the obvious.

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, compact sentence with no filler words. It front-loads the core function and is appropriately sized for a simple list operation.

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?

There is no output schema and no annotations, so the description must convey return value expectations and behavioral nuances. It only says 'lists all discount codes,' omitting that the tool is paginated (with 'first' and max 50), that 'query' enables filtering, and what fields the list items contain. Under-specified for an agent to fully understand the tool's behavior.

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

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

The input schema provides full descriptions for both parameters ('first' and 'query'), so the description adds no parameter-level information. Since schema coverage is 100%, a baseline score of 3 is appropriate even without additional parameter detail in the 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 'Lists' and the resource 'all discount codes in the shop,' leaving no doubt about the tool's basic function. It does not explicitly distinguish from the sibling 'list_automatic_discounts', but the resource naming makes the distinction implicit.

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 offers no guidance on when to use this tool versus alternatives such as 'list_automatic_discounts', nor does it mention any prerequisites, exclusions, or specific scenarios. It is a bare statement of function without 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 must disclose behavior, but it only says 'Lists all locations'. The 'first' parameter (max 50) contradicts the 'all' claim, implying pagination is possible yet it is not disclosed. No mention of read-only status, ordering, or pagination behavior is included.

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, front-loaded sentence that immediately states the action and target. It contains no unnecessary words, though 'all' is slightly misleading due to the pagination parameter.

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?

Without an output schema or annotations, the description should at least mention pagination limits, return value shape, or the relationship with the 'first' parameter. The tool is simple, but the 'all' vs max-50 contradiction leaves a significant gap in understanding what the tool actually returns.

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 100% coverage for the single parameter 'first' with a description and default value, so the description does not need to explain it. The description adds no additional meaning but also does not mislead about the 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?

The description uses the specific verb 'Lists' and names the resource 'locations of the shop', clearly distinguishing it from siblings such as shop_locales or list_products. It is unambiguous and tells the agent exactly what the tool returns.

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

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

No guidance is provided about when to use this tool versus alternatives like shop_info or shop_locales. There is no mention of prerequisites, exclusions, or scenarios where another tool would be more appropriate.

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

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

With no annotations, the description must carry the full burden of behavioral disclosure. It conveys that the tool lists orders and supports filtering, but does not mention pagination behavior, default sorting, result limits, or whether it returns full order details or summaries. This is a minimal but non-contradictory 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?

The description is two short sentences, entirely focused and free of redundant information. Every word earns its place, making it a model of conciseness.

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

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

Given the tool has 5 parameters and no output schema or annotations, the description is adequate but leaves gaps. It doesn't clarify return format, pagination mechanics, or behavioral limitations. The schema covers parameters, but the tool's overall behavior and edge cases are under-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 description coverage is 100%, so the baseline is 3. The description's mention of 'status, date' loosely maps to the `query` parameter, but it does not add new meaning beyond the schema's explicit examples and parameter descriptions. No additional semantic value is provided.

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 'Lists orders in the shop' clearly states the verb (list) and resource (orders), immediately distinguishing it from order-specific siblings like get_order, update_order, cancel_order, and create_draft_order. The additional mention of filtering by status/date further narrows the scope.

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

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

The description provides clear context ('Lists orders in the shop') and hints at filtering via 'Filterable by status, date, etc.', but it does not explicitly exclude alternatives or state when to prefer this over get_order. It gives enough context for an agent to infer usage but lacks explicit '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 the burden of behavioral disclosure. It only repeats what the schema already contains (pagination, filtering) and adds no new context about rate limits, response format, sorting, or read-only nature. The vague 'etc.' does not compensate.

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 front-loaded, with two short clauses. However, the trailing 'etc.' is vague and slightly under-specified, keeping it from a perfect score.

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

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

The tool has no output schema and no annotations, so the description should explain return values and usage context. It only mentions pagination and filtering, but not the structure of the returned list, how to loop through pages, or how it differs from get_product. The description is too thin for a complete understanding.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'filtering by title, status, etc.' echoes the schema's query examples and adds little value. It does not introduce any new parameter meaning.

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

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

The description clearly states 'Lists products in the shop', which is a specific verb+resource that distinguishes it from siblings like get_product (single product) and create/update/delete. The mention of pagination and filtering further clarifies scope.

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

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

The description does not explicitly say when to use this tool versus alternatives such as get_product or list_collections. It implies usage for listing multiple products via 'Lists products' and 'Supports pagination and filtering', but no explicit exclusions or alternative tool names are provided.

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

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

With no annotations available, the description carries the full burden of behavioral disclosure. It states the tool 'returns' data, implying a read-only operation, but it gives no details about potential side effects, data freshness, scoping (e.g., all products vs. published only), or any limitations. Unlike the get_calls example where annotations covered safety, here the description is the only source and it is sparse.

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, front-loaded sentence that efficiently communicates the core purpose without wasted words. It earns its place by stating the action and the exact counts included.

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

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

The tool is simple with zero parameters, and the description adequately states what it returns. However, there is no output schema, so the description is the only reference for the return structure. It mentions the three count types but not how they are packaged (e.g., an object with specific keys) or whether there are any additional fields, leaving some ambiguity for the agent.

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 zero parameters, so the baseline is 4. The description correctly implies no inputs are needed and does not need to explain parameter semantics.

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 a specific verb ('returns') and resource ('compact overview of the shop') and enumerates the content (product, order, and customer counts). It distinguishes itself from sibling tools like get_order_count, get_product_count, and get_customer_count by offering a combined summary rather than individual counts.

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 no explicit guidance on when to use this tool versus alternatives such as get_product_count or get_order_count. The phrase 'compact overview' implies a dashboard use case, but there is no mention of when to prefer this over individual count endpoints or any exclusions.

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

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

With no annotations, the description carries the burden. 'Returns' implies a read-only operation, and the listed fields give some context. However, it does not explicitly state that no modifications occur, nor does it mention any potential side effects, permissions, or return format details. For a simple zero-param tool, this is adequate but not rich.

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, well-structured sentence that front-loads the key action ('Returns basic information') and provides a useful list of example fields. 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 simple, zero-parameter, read-only tool, the description is nearly complete. It lists the main fields returned, and the 'etc.' acknowledges there is more. Given the sibling context, it clearly differentiates from more specific shop-related tools. No output schema exists, but the description offers enough for an agent to understand the tool's scope.

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 tool has zero parameters, so the schema requires no explanation. The baseline for zero-parameter tools is 4, and the description does not need to add parameter semantics beyond what the empty schema already conveys.

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

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

The description clearly states the tool returns basic Shopify shop information, listing specific fields (name, domain, email, plan, currency). The verb 'Returns' and resource 'basic information' are specific, and it distinguishes from more specialized sibling tools like shop_locales and shop_policies.

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

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

The description implies use when general shop information is needed, but it does not explicitly mention when to avoid this tool or point to alternatives like shop_locales or shop_policies. No clear exclusions are stated, so guidance is partially implied rather than explicit.

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 implies a read-only operation through 'lists' but does not explicitly state safety characteristics (e.g., no side effects) or additional behavioral context such as response format, ordering, or authorization requirements. The description is adequate for a simple read but minimal.

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, clear, and efficient sentence with no redundant words. It perfectly front-loads the 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?

The tool is very simple with no parameters and no output schema. The description explains what it returns conceptually ('all configured languages/locales') but does not specify the exact return structure (e.g., array of strings, objects with codes/names). For such a minimal tool, this is adequate but could be slightly more explicit about the response format.

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

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

The tool has zero parameters, so the baseline is 4. The description adds no parameter information, but none is needed since the input schema is empty and coverage is 100%.

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 'Lists' and clearly identifies the resource as 'all configured languages/locales of the shop'. It distinguishes itself from siblings like shop_info and available_shipping_countries by focusing specifically on languages/locales.

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

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

No guidance is provided on when to use this tool versus alternatives or any exclusions. The description is purely functional and does not mention use cases, prerequisites, or scenarios where another sibling tool might be more appropriate.

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 states 'Returns' which implies a read-only operation, but it does not disclose potential caveats like authentication requirements, rate limits, or return format. For a simple read tool, this is adequate but not richly 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?

The description is a single sentence, front-loaded with the verb 'Returns', and includes concrete examples of policy types. Every word earns its place with no redundancy or filler.

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

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

For a 0-parameter, read-only tool with no output schema, the description fully conveys what the tool returns and the scope of policies. It could mention potential variations (e.g., 'may not include all policies for all regions'), but the 'etc.' covers additional types, making it complete enough.

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 tool has zero parameters, and the input schema is empty. The description implies no inputs are needed, which aligns with the schema. Per rubric, a 0-parameter tool gets a baseline of 4; there is no parameter information needed beyond this.

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

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

The description clearly identifies the resource (shop policies) and lists specific policy types (privacy, terms of service, refund, shipping, etc.), distinguishing it from siblings like shop_info and list_products. The verb 'Returns' is specific and matches the 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?

No explicit guidance is provided on when to use this tool versus alternatives, but the purpose is so direct (retrieving policies) that the usage is implied. There is no mention of when not to use or alternative tools, so it falls at 'implied 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, the description is the only source of behavioral info. It discloses that the operation is an update (mutation) but does not mention partial-update semantics, error handling, or any side effects.

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

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

The description is a single, short sentence with no redundancy or filler.

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

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

For a 7-parameter mutating tool with no output schema, the description is insufficient. It does not explain the return value, error conditions, or the specific behavior of updating fields.

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

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

All parameters have descriptions in the JSON schema, so the description adds no additional parameter semantics. Since schema coverage is 100%, the baseline score of 3 applies.

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

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

The description clearly states the tool updates an existing customer, using the verb 'updates' and the resource 'existing customer', distinguishing it from create_customer, delete_customer, and get_customer 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?

The description offers no guidance on when to use this tool versus alternatives, no prerequisites (e.g., must have an existing customer ID), and no exclusions. It only states the action.

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

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

With no annotations, the description must disclose behavioral traits but only states 'Updates an order' without explaining whether updates are partial or full, consequences on existing data, permission needs, or return format. This lack of detail is a significant gap for a mutating operation.

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

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

The description is a single, front-loaded sentence with no filler. The trailing 'etc.' is vague and slightly undermines precision, but the overall conciseness is good.

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 four parameters, no annotations, and no output schema, the description is too sparse. It does not explain expected response, update semantics (replace vs merge), error conditions, or operational context. The schema covers parameter definitions but not the behavioral envelope.

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

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

Schema description coverage is 100%, with each parameter (id, note, tags, email) clearly documented. The description adds no new semantic meaning beyond reiterating the fields, so the 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 uses the specific verb 'Updates' with the resource 'order' and lists editable fields ('notes, tags, email'), making the core function identifiable. It doesn't explicitly contrast with sibling tools like cancel_order, but the verb and scope are sufficient for basic differentiation.

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

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

No guidance is provided on when to use this tool versus alternatives such as cancel_order or create_draft_order. There is no mention of prerequisites, order states, or check-out scenarios, leaving the agent without decision support.

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 bears full responsibility for behavioral disclosure. It only states 'Updates an existing product' without detailing whether fields are partially updated, if specific permissions are required, what happens to unset parameters, or what the response contains.

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

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

The description is a single, efficient sentence that conveys the core purpose. It is front-loaded and contains no filler, though it is brief enough that additional context could be expected without harming conciseness.

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

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

Given this is a mutation tool with 7 parameters and no output schema, the description is far too sparse. It does not explain return values, error behavior, or the extent of the update, leaving significant gaps for an agent.

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 descriptions for all 7 parameters. The description adds no additional meaning beyond the schema, so the 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 uses the specific verb 'updates' with the resource 'existing product', clearly indicating the action. While it doesn't explicitly differentiate from siblings like create_product or delete_product, the verb itself makes the distinction obvious.

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

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

No guidance is given on when to use this tool versus alternatives. There is no mention of prerequisites, such as the product needing to exist, or scenarios where update_product is preferred over create_product or patch-like behavior.

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