MCP Shopify Admin Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.0
Disambiguation5/5
Each tool has a distinct purpose, and the plan/preview/execute stages are clearly separated. Even overlapping tools like product_update_plan and product_tags_add_plan are explicitly disambiguated with guidance on when to use which.
Naming Consistency5/5
Tool names consistently follow an object_verb pattern (e.g., product_list, collection_get) and the staged operations use a uniform resource_action_plan/preview/execute suffix. The few exceptions (inventory_levels, product_publications_get) are still clear and don't break the overall pattern.
Tool Count2/5
At 49 tools, the server is over twice the recommended upper bound. The plan/preview/execute triple multiplies the count, but it still results in an overwhelming surface that will be difficult for agents to navigate efficiently.
Completeness4/5
The server covers the core Shopify domains well: products, collections, orders, customers, inventory, and publications. However, it lacks common operations like product/collection deletion, customer creation/update, and order creation, which are notable gaps for a full admin surface.
Average 4.1/5 across 49 of 49 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds minimal behavioral context beyond annotations. It does not disclose that planning likely avoids immediate execution, what side effects (if any) occur, or what the tool returns. Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description neither confirms nor elaborates on these.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded, with two short sentences that state the core purpose and a key detail (heterogeneous updates). No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is inadequate for a bulk operation tool without an output schema. It does not explain the output/return value (e.g., a plan ID for use with preview/execute), any prerequisites, or relationship to sibling planning tools. The openWorldHint annotation suggests possible side effects, but the description remains silent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add any parameter semantics beyond the schema's minimal descriptions ('Store name', 'Array of product updates (max 100)', 'Response format'). It fails to explain how to structure updates or what acceptable values are beyond the enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('Plan') and resource ('bulk update of multiple products'), and explicitly notes that different products can have different updates. This distinguishes it from siblings like product_update_plan (single product) and product_bulk_update_preview/execute (different phases).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 versus alternatives. It does not mention the preview/execute counterparts or indicate that this is a preparatory step. The only hint is the word 'Plan' and the sibling naming, which the description itself does not leverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, open-world, non-idempotent operation, but the description does not clarify what side effects 'plan creation' has. The phrase 'create an automated twin' may mislead an agent into thinking this tool directly creates a collection rather than producing a plan. No mention is made of how a plan is persisted, returned, or later executed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences and front-loads the core purpose. The second sentence is a bit meandering with the colon and 'point downstream systems at it,' but overall it is efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex nested rule_set schema, no output schema, and the existence of separate preview/execute siblings, the description omits necessary lifecycle context such as whether a plan ID is returned, how to proceed to execution, or what the planning step actually does. It only covers a narrow use case and leaves agents guessing about the tool's place in the workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter already has a description. The tool description adds the phrase 'optionally AUTOMATED via a rule_set,' which reiterates the schema's note that omitting rule_set creates a manual collection, but it does not add meaningful semantic depth beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as planning the creation of a new collection with an optional automated rule_set, and the 'Plan' wording distinguishes it from collection_create_preview and collection_create_execute. However, 'Plan creation' is a mildly awkward phrase and the use-case sentence could blur the distinction between planning and actually creating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use this when Shopify refuses to convert an existing manual collection: create an automated twin, then point downstream systems at it.' This gives a concrete scenario, though it does not explicitly mention when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnly, idempotent, and non-destructive behavior. The description adds no new behavioral context beyond what the schema provides (e.g., 'filtering by status and pagination' is already in parameter descriptions). It fails to mention pagination flow or response characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, front-loaded with 'List orders', and includes all essential information. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (7 params, all documented in schema) and strong annotations, the description is minimally adequate. However, it does not explain cursor-based pagination usage or the response format beyond schema fields, leaving some gaps for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description's mention of 'status' and 'pagination' is redundant with schema fields; no additional semantic meaning is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'List orders from a Shopify store' with a specific verb and resource. It distinguishes itself from sibling order_get by focusing on listing multiple orders with filtering, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing orders, especially with optional filtering and pagination, but does not provide explicit when-to-use vs alternatives. No exclusions or alternative tool mentions are included, so the guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context beyond the word 'preview', which is consistent with the annotations. It doesn't describe side effects or output characteristics, but given the strong annotation coverage, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It is appropriately concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is extremely minimal. While annotations and schema cover safety and parameters, there is no explanation of what the preview returns or what 'preview' entails. With no output schema, the description should offer more detail about the expected result to help the agent set expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both operation_id and response_format having descriptions. The main description adds no extra parameter information, but the baseline of 3 applies since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Preview a planned collection creation' uses a specific verb ('preview'), names the resource ('collection creation'), and clearly distinguishes from sibling tools like collection_create_execute and collection_create_plan. The intent is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 that it should be used after collection_create_plan and before collection_create_execute, nor does it note any exclusions. The schema hints at the dependency via operation_id from plan, but the description itself offers no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the tool supports filtering and pagination, but provides no further behavioral details such as return format or rate limits, so it adds limited value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It clearly states the action, target, and key optional capabilities.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity of a list operation, the description plus schema provide adequate context. The tool has no output schema, but the return value (a list of products) is self-evident. However, it could benefit from a note about response structure or pagination cursor behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameter meanings are already documented. The description's mention of 'optional filtering and pagination' loosely maps to the query, limit, and cursor parameters, but it adds no new detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('products from a Shopify store'), making the tool's purpose clear. It mentions optional filtering and pagination, but does not explicitly distinguish itself from sibling tool product_search, which could also support filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for general product listing but provides no explicit guidance on when to use product_list versus product_search or other alternatives. The parameter schema hints at store_list for store discovery, but the description itself lacks usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds minimal behavioral context beyond stating the use of Shopify search syntax, which is already partially captured in the query parameter description. No new behaviors such as pagination or response format are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that clearly communicates the core function without unnecessary words. It is appropriately sized for a simple search tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with rich annotations and complete schema coverage, the description adequately orients the agent. It mentions the essential distinguishing feature (Shopify search syntax) and does not need to repeat parameter details. The absence of an output schema is not compensated, but the description is sufficient for this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description's mention of 'Shopify's search syntax' adds a small clarification but does not provide significant additional meaning beyond the query parameter's examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search'), resource ('products'), and method ('Shopify's search syntax'), clearly defining the tool's function. This distinguishes it from sibling tools like product_list by indicating it performs a search with query syntax rather than simply listing products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives like product_list. It only implies the search syntax capability, but there is no direct comparison or mention of alternative tools, leaving the agent without clear selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds 'Shows what will happen,' which clarifies it is a simulation, but this is not a significant behavioral disclosure beyond what annotations already imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the purpose, and every word earns its place. No unnecessary detail or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, with annotations covering safety and schema covering parameters. However, the description does not detail what 'Shows what will happen' actually includes, and there is no output schema. It is adequate but lacks richer context about the returned information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema. The description itself adds no parameter-specific meaning, and the baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Preview' with the resource 'planned order cancellation' and states the outcome ('Shows what will happen'). This clearly distinguishes it from sibling tools like order_cancel_plan and order_cancel_execute.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after planning ('planned order cancellation') but does not explicitly mention when to use it vs alternatives or provide exclusions. It gives enough context to suggest it is a pre-execution step, but lacks direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description adds 'optional search and pagination' as minor behavioral context. However, it does not disclose deeper behaviors such as rate limits, response structure, or the fact that openWorldHint suggests the list may be incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that packs the essential action, resource, and key options without any redundant words. It is front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with only one required parameter and strong annotations, the description is largely sufficient. It covers the core operation; though there is no output schema, the return type (list of customers) is implicit. The description could mention that the 'store' parameter should reference a store from 'store_list', but that is already in the parameter schema. Overall, no critical gap for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already well-documented (e.g., 'limit', 'query', 'store', 'cursor', 'response_format'). The description only refers to 'optional search and pagination', which slightly emphasizes but does not add meaning beyond the schema. Baseline 3 applies given complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' targeting the resource 'customers' within 'a Shopify store', immediately distinguishing it from sibling tools like 'customer_get' or 'product_list'. It also notes optional search and pagination, adding useful scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching multiple customers, mentioning optional search and pagination, but it does not explicitly state when to use this over alternatives like 'customer_get' for a single customer. No exclusions or prerequisites are provided, leaving usage to be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the useful detail that it shows before and after quantities, but it does not go further to explain any limitations or edge cases, so it adds modest value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences that are entirely on-topic and free of redundancy. Every word contributes to understanding the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool, the description is nearly complete. It states the purpose and the output content, and the annotations cover side effects. However, it does not explicitly note that the preview makes no actual changes to inventory (beyond what 'preview' implies), so a small gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with both parameters already described. The description does not add any additional parameter-level meaning beyond what the schema provides, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Preview' and the resource 'planned inventory adjustment,' making the tool's purpose unambiguous. It also states it 'Shows the before and after quantities,' which distinguishes this from the related plan and execute tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool relative to inventory_adjust_plan or inventory_adjust_execute, nor does it name alternatives. However, the name and the mention of 'planned' adjustment imply it is used after planning and before execution, providing only implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds filtering capabilities but no additional behavioral context such as pagination behavior, response format nuances, or the distinction between store and location_id. With rich annotations, the description contributes moderate extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that immediately state the tool's purpose and primary filters. No wasted words, and the key action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with robust annotations and 100% schema coverage, the description is sufficiently complete for selection and basic invocation. It captures the core functionality and filtering dimensions. However, it does not address pagination or the relationship between 'store' (required) and 'location_id', which could cause minor ambiguity, but this is largely covered by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all seven parameters. The description mentions filtering by location, product, or SKU, which maps to location_id, product_id, and sku, but this adds no new meaning beyond the schema's existing parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('inventory levels') with clear scope ('for products at specific locations'). It distinguishes from sibling tools like inventory_adjust_* which modify inventory rather than read it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating the filtering options, but it does not explicitly mention when to use this tool versus alternatives, nor does it provide exclusions or prerequisites. The readOnlyHint annotation helps, but the description itself lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds minimal behavioral context beyond 'preview all changes,' which slightly clarifies the scope of the preview but doesn't disclose return format, pagination, or side effects. With annotations carrying most of the safety burden, this is a mid-level score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that clearly states the tool's purpose. Every word earns its place; there is no fluff or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the annotations, and a fully documented schema, the description is mostly complete. It tells the agent this is a preview operation, which aligns with the plan-preview-execute pattern visible in sibling tools. However, it does not describe what the preview output will contain (though response_format indicates JSON/markdown) or any limitations, so it falls just short of a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both operation_id and response_format have descriptions. The tool description does not add meaning beyond the schema, but the schema already fully documents the parameters. Thus 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Preview' with a clear resource 'bulk product update operation.' It distinguishes itself from sibling tools like product_bulk_update_plan and product_bulk_update_execute by explicitly stating it's a preview step. The singular product_update_preview sibling is also differentiated by the 'bulk' qualifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to preview changes before execution, but it doesn't explicitly state when to use it versus alternatives like product_bulk_update_execute or product_update_preview. The schema reference to 'Operation ID from product_bulk_update_plan' hints at the preceding step, but the description itself lacks explicit guidance on workflow sequencing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds context about what the preview displays (products and channels), but does not disclose additional behavioral traits beyond what annotations provide. It is consistent with the annotations, so no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the primary purpose. It contains no redundant information and every word contributes to understanding the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple schema and absence of an output schema, the description sufficiently explains the tool's purpose and the nature of its output (which products and channels). It could be more explicit about the requirement for an operation_id from a prior plan, but that is already captured in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for both parameters (operation_id and response_format), achieving 100% coverage. The description adds no extra parameter information, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Preview') and resource ('products'), explicitly stating the output scope ('which products will change publication state, and on which channels'). This clearly distinguishes the tool from its plan and execute siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is a preview step for a publish operation, but it does not explicitly state when to use it relative to product_publish_plan or product_publish_execute. The operation_id parameter referencing product_publish_plan in the schema hints at the workflow, but the description itself lacks explicit guidance or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the tool as a safe, non-mutating operation. The description's addition ('Shows what will be shipped') primarily describes the output rather than adding behavioral context like side effects, permissions, or error behavior. Thus, it provides minimal extra transparency beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It front-loads the action ('Preview') and immediately clarifies the purpose ('Shows what will be shipped'). Every word adds value, fitting the conciseness criteria perfectly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple preview tool with comprehensive annotations (read-only, idempotent) and full schema coverage, the description is complete. It states what the tool does and what the output represents. Given that the output schema is absent and the tool is straightforward, the description sufficiently covers the necessary context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes both parameters: operation_id references the source plan, and response_format defines its enum and default. Since schema_description_coverage is 100%, the description does not need to add parameter details. It does not, and the baseline for high coverage is 3, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (preview) and the resource (a planned order fulfillment), and explicitly indicates what the preview will show ('what will be shipped'). It distinguishes itself from sibling tools like order_fulfill_execute (which executes) and order_fulfill_plan (which creates the plan), making the tool's specific role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage within a plan-preview-execute workflow (via the verb 'preview' and the parameter referencing order_fulfill_plan), but it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions. The context is present but only implied, so it falls short of a 4 or 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds the need for prior preview and production confirmation, but doesn't disclose other behavioral traits such as irreversibility, side effects, or how success is reported. For a mutation tool, this is a moderate gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loaded with the verb and object, and every word earns its place. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a step in a known workflow, specifying prerequisites and production-specific conditions. However, with no output schema, it fails to mention post-execution behavior or how to verify the result, leaving a moderate completeness gap for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters, including the source of operation_id and the meaning of confirm_production. The description merely restates the confirm_production requirement without adding new semantic depth, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Execute' with the resource 'previewed product update', clearly identifying the tool as the final action in the product update workflow. It distinguishes itself from sibling tools like product_update_plan and product_update_preview by emphasizing the preview requirement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states a clear prerequisite ('Requires prior preview') and a conditional requirement for production stores ('confirm_production: true'). While it doesn't explicitly list alternatives or when-not-to-use, the workflow context with sibling plan/preview/execute tools makes the usage context obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive, non-idempotent behavior. The description adds the production store confirmation nuance, which is valuable context. But it doesn't disclose other behavioral aspects like irreversibility or that the operation_id is consumed. Given annotation coverage, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one succinct sentence that front-loads the core purpose and includes the critical production caveat. 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple execute step in a plan-preview-execute workflow, and annotations cover safety and side effects. The description covers the essential action and the key production nuance. Given the absence of an output schema, the description is reasonably complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already documented in the schema. The description does not add any new parameter detail beyond what the schema provides, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Execute') and resource ('previewed collection creation'), clearly distinguishing this tool from planning and previewing siblings. It also adds the production store requirement, leaving no ambiguity about the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'previewed collection creation' implies the tool should be used after collection_create_preview, providing clear context. It also notes the confirm_production requirement for production stores. However, it doesn't explicitly state when not to use it or name alternative tools, so it stops short of a full guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds value by specifying that the response includes address and recent orders, which is additional behavioral context about the returned data beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no superfluous words. It front-loads the core purpose ('Get detailed information') and immediately adds relevant specifics, achieving maximum conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description reasonably covers the expected return content by mentioning address and recent orders. It does not detail error handling or pagination, but for a straightforward get-by-id tool with strong annotations, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters, with clear descriptions for id, store, and response_format. The description adds no additional parameter-specific meaning beyond what the schema already provides, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'a specific customer', and further specifies 'including their address and recent orders', which makes the tool's function immediately obvious and distinguishes it from sibling tools like customer_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for retrieving a single customer's details, but it does not explicitly contrast with customer_list or other get tools. There is no explicit when-to-use or alternative guidance, leaving the usage context to be inferred from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context by specifying the response contains 'current state, preview data, and result', which goes beyond a simple 'status' and helps the agent know what information to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 15 words that front-loads the core purpose ('Get detailed status of a specific operation') and then lists the included content types. No filler or repetition; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description carries the burden of explaining what the tool returns. It does so by mentioning 'current state, preview data, and result', which is sufficient for a status lookup tool. Given the simple parameter set and strong annotations, the description is nearly complete, though it could have briefly pointed to operation_list for discovering operation IDs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both operation_id and response_format have descriptive text in the schema. The description itself adds no parameter-specific meaning beyond what the schema already provides, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' with a clear resource: 'detailed status of a specific operation'. It distinguishes from siblings like operation_list (which lists operations) and operation_cancel (which cancels) by focusing on a single operation's status, including its current state, preview data, and result.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: you need a specific operation ID, but it does not explicitly state when to use this tool versus alternatives like operation_list or operation_cancel. No exclusions or alternative tool references are provided, so usage is only implied, not clearly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds that the response includes variants, images, and inventory, which is useful context about what the tool returns. However, it doesn't go beyond that—no mention of potential errors, rate limits, or other behavioral nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence. It front-loads the action and output scope without any wasted words. It is concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with full schema coverage and safety annotations, the description is complete enough. It tells the agent what the tool does and what to expect in the response. There is no output schema, so the mention of variants, images, and inventory partially fills that gap. It lacks guidance on when to use this vs siblings, but that is more of a usage-guideline issue.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all parameters have descriptions). The description does not add any parameter-specific meaning beyond the schema; it only mentions the resource details (variants, images, inventory). The schema already explains id, store, and response_format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get detailed information about a specific product including variants, images, and inventory.' It uses a specific verb ('Get') and resource ('product'), and specifies scope ('specific') which distinguishes it from product_list and product_search. The title 'Get Product' reinforces this.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use this tool when you need details on a specific product, as opposed to listing or searching. It does not explicitly name alternatives like product_list or product_search, but the phrase 'specific product' provides clear context for when to use it. No exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds the diagnostic context (products missing from storefront/feeds) but does not disclose additional behavioral details such as return shape, pagination, or edge cases. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and the second sentence adds practical use-case context without any waste. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with strong annotations and full schema coverage, the description is sufficiently complete. It states what it does and when it is useful, but could have improved by explicitly naming sibling alternatives or noting output behavior. Still, it is well above the minimum viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all three parameters (id, store, response_format) described in the schema. The tool description adds no parameter-specific semantics, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Show') and clearly identifies the resource ('which sales channels a product is published to'). It distinguishes itself from siblings like product_get (product details) and publication_list (list publications) by focusing on publication status across channels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: diagnosing products that exist in a collection but never appear on the storefront or in an external feed. This implies when to use the tool but does not explicitly mention alternatives or exclusion criteria, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value by specifying what data is returned (line items, fulfillments, customer info) but does not disclose additional behavioral traits such as required permissions, rate limits, or handling of missing orders. This meets the lower bar for annotation-backed tools but lacks rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately communicates the tool's purpose and key outputs. Every word earns its place; there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with full schema coverage and safety annotations, the description sufficiently indicates return contents. It does not need to explain return structure since no output schema exists, but it gives enough context for an agent to select and invoke the tool correctly. The sibling context (mutations, list tools) reinforces its role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (store, id, response_format) already documented. The description adds no extra parameter semantics beyond 'specific order', 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get') and resource ('detailed information about a specific order'), and enumerates included content (line items, fulfillments, customer info). This distinguishes it from sibling tools like order_list (which lists orders) and order_fulfill (which mutates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for fetching a single order's details, implying use when a specific order_id is known. It does not explicitly mention when not to use it or name alternatives, but the context is unambiguous for a getter tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the destructive nature is known. The description adds valuable specific behavior: it uses Shopify's tagsRemove mutation and guarantees that 'every other tag untouched.' This clarifies the exact scope of the destructive action. It also emphasizes the subtractive nature, complementing the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose ('Plan a SUBTRACTIVE tag operation'), and every sentence adds meaningful detail. The second sentence specifies the mutation and the non-destructive guarantee. There is no redundant or extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what the underlying operation does but does not clarify what 'plan' means in terms of output or workflow, and there is no output schema. It doesn't mention that the plan might generate a plan ID or that it is a dry-run before preview/execute. Given the plan/preview/execute sibling pattern, some context is implied, but the description alone is incomplete for a new agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 5 parameters, each with a clear description in the schema. The tool description itself adds no additional parameter information, but the schema fully documents what each parameter represents. Therefore, the baseline of 3 is appropriate; the description does not need to compensate for missing schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Plan a SUBTRACTIVE tag operation using Shopify's tagsRemove mutation.' It explicitly differentiates from add operations by emphasizing 'SUBTRACTIVE' and specifies the exact scope: 'Removes only the named tags and leaves every other tag untouched.' This distinguishes it from siblings like product_tags_add_plan and the preview/execute counterparts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: it is for planning a removal operation (as opposed to previewing or executing). The word 'Plan' and the operation type make this clear. However, it does not explicitly state when NOT to use this tool (e.g., 'use product_tags_add_plan for adding tags') or mention alternatives directly. Sibling naming provides additional context, but the description alone lacks explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds that the response includes MANUAL vs AUTOMATED and the rule set, giving useful behavioral context beyond the annotations. No contradiction, but no details on error handling or pagination (likely not needed).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the verb and resource. Every phrase adds value, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with four well-documented parameters and rich annotations, the description is adequate. It mentions the key output aspects (MANUAL/AUTOMATED, rule set) and the identifier options. No output schema exists, but the description doesn't need to explain return values beyond what it already provides.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline of 3 applies. The description reiterates that id can be numeric or GID and that handle is an alternative, but this is already stated in the schema descriptions. No additional parameter semantics are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get one collection' and specifies the three accepted identifiers (numeric ID, full GID, or handle), distinguishing it from collection_list and collection_update/create. Mentioning that it 'Reports MANUAL vs AUTOMATED and the rule set' adds specificity about the output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the use case explicit: retrieve a single collection when you have an identifier. It doesn't name alternatives like collection_list, but the wording 'one collection' implies single-item retrieval, and sibling tool names make the contrast evident. Clear context but no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond these annotations: it discloses that output includes collection type, rules, and product count, and importantly notes that only AUTOMATED collections propagate to external feeds. This aligns with annotations and does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the tool's primary action, the second adds critical output details and a domain-specific caveat. There is no redundant language, and each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with rich annotations and a fully documented schema, the description is adequate. It communicates what the tool returns and highlights an important distinction (manual vs. automated) that affects downstream behavior. Without an output schema, it might ideally mention pagination or the default limit, but the presence of a cursor parameter in the schema compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for all 5 parameters, each with a description. The tool description does not add extra parameter-level semantics beyond what the schema already specifies, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource pattern: 'List collections in a store,' clearly distinguishing this from the sibling collection_get. It also details the outcome (shows MANUAL vs AUTOMATED, rules, product count), which differentiates its scope unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it lists collections for a given store and explains a key detail about AUTOMATED collections propagating to external feeds, implying which use cases it serves. However, it does not explicitly state when not to use it or mention alternatives like collection_get.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral detail beyond annotations by stating it shows 'current vs new state'. Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so no contradiction. It doesn't detail side effects, but the annotations cover the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that clearly states the action and resource without any filler or redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool without an output schema, the description provides the key behavioral fact (current vs new state) and relies on annotations for safety. The workflow context is partly implied by sibling tool names and the parameter reference to collection_update_plan, making it reasonably complete for a simple preview operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for both operation_id and response_format, including an enum and default for the latter. The description itself does not add parameter-specific meaning, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Preview') and identifies the resource ('planned collection update'), clearly distinguishing it from the sibling tools collection_update_plan and collection_update_execute. The added phrase 'showing current vs new state' further clarifies the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear usage context: use this tool to preview a planned update before execution. It references 'planned collection update' and the operation_id comes from collection_update_plan, but it does not explicitly state alternatives or when-not-to-use. This is sufficient for a straightforward preview tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds value by explicitly stating 'This actually changes the inventory' and the production store requirement, which is not captured elsewhere. This provides meaningful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and efficient, consisting of three short sentences. Each sentence serves a purpose: stating the action, emphasizing the real-world effect, and highlighting a key requirement. No fluff or redundancy, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema, but rich annotations), the description covers the essential context: it is an execution step, it changes inventory, and production stores need confirm_production. It could optionally mention the return value, but the absence is acceptable because the operation's outcome is implied by its role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for all three parameters, including descriptions for operation_id, response_format, and confirm_production. The description's mention of confirm_production simply repeats what the schema already states, adding no new semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Execute a previewed inventory adjustment.' It uses a specific verb (Execute) and resource (previewed inventory adjustment), and distinguishes itself from sibling tools (inventory_adjust_plan, inventory_adjust_preview) by emphasizing that it 'actually changes the inventory,' making it unambiguous as the execution step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'previewed' implies the tool should be used after inventory_adjust_preview, and the note 'Production stores require confirm_production: true' gives a specific condition. However, it does not explicitly mention when not to use it or name alternative tools, though the sibling context makes the intended workflow clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations by revealing that the tool creates a staged operation that must be previewed and executed, meaning it does not directly modify inventory. This complements annotations (readOnlyHint false, destructiveHint false) without contradiction, though it omits details about operation management (e.g., cancellation).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences. It front-loads the core purpose, then adds the critical workflow caveat in the second sentence without any wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity of a 3-step plan/preview/execute workflow and the lack of an output schema, the description adequately communicates the tool's role and the required next steps. It could further specify the output (e.g., an operation ID) or name the exact sibling tools, but the current level is sufficient for an agent to understand the tool's place in the workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% parameter description coverage, so the description need not explain parameters. The tool description adds no additional parameter semantics, but the schema already fully describes each property, 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.
Purpose5/5
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 ('Plan') and resource ('inventory adjustment'), and distinguishes it from sibling tools by explaining it creates a staged operation prior to preview and execution. This prevents confusion with inventory_adjust_preview and inventory_adjust_execute.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for planning and that the resulting operation must be previewed and executed, implying the workflow. However, it does not explicitly name the alternative tools or state when not to use this tool, stopping short of full usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false; the description adds that only pending/unexecuted operations are affected and frames the action as discarding a plan. It doesn't detail error behavior or exact side effects, but the combination covers the essential safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences; the action and scope are front-loaded and no word is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple cancellation tool with one required parameter and strong annotations, the description explains what it does and when to use it. It doesn't specify the return value or how to obtain operation_id, but the presence of operation_list and the tool's low complexity keep it usable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with descriptions (100% coverage), and the tool's description doesn't duplicate parameter details. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'cancel' and names the resource 'pending operation' with the qualifier 'not yet been executed.' This clearly distinguishes it from read-only siblings like operation_list/operation_status and from plan/execute tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear use case: 'This is useful if you want to discard a planned operation.' It doesn't explicitly state when not to use or mention alternatives, but the context is sufficient for an agent to know when to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: operations expire after 30 minutes, and 'pending' is defined as awaiting preview or execution. This gives the agent a clearer model of what the list contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The first sentence states the core function, and the second adds the essential caveat about expiry. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with strong annotations and full schema coverage, the description is mostly complete. It clarifies scope and expiry, and the response format is handled by the schema. However, since there is no output schema, it could have mentioned what fields are returned or whether the list is ordered, but that is not critical for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, response_format, is fully described in the schema with enum values, a default, and a description. The tool description adds no additional parameter-level information, so it relies entirely on the schema's 100% coverage. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as listing pending operations, with a specific scope ('waiting for preview or execution'). This distinguishes it from siblings like operation_status (which checks specific operations) and operation_cancel (which cancels them). The verb 'List' and resource 'pending operations' are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need to see operations awaiting preview or execution. It adds the 30-minute expiry context, which is useful for monitoring urgency. However, it does not explicitly name alternatives like operation_status or operation_cancel, so it 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description reinforces this with 'actually cancels the order.' It adds the production store requirement for confirm_production, which is not in annotations. No contradiction. The description provides useful behavioral context beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose and a key caveat. Every sentence adds value: the first states the action, the second emphasizes the destructive nature and the production requirement. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action, the prerequisite (previewed), and an important setting. Given the annotations plus full schema coverage and the straightforward plan-preview-execute pattern, this is sufficient. It doesn't detail response behavior, but no output schema exists and the context is simple enough that this is not a major gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and all parameters have adequate descriptions, including operation_id referencing 'order_cancel_plan' and confirm_production's purpose. The description does not add further parameter details, but the schema carries the load, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Execute a previewed order cancellation.' The verb 'Execute' and resource 'order cancellation' are specific, and 'This actually cancels the order' distinguishes it from preview/plan steps, aligning with the sibling tool names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates this tool is for executing a previously previewed cancellation, implying it follows order_cancel_plan and order_cancel_preview. It adds the critical condition 'Production stores require confirm_production: true,' but does not explicitly name alternatives or exclusions. The context is clear enough for typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations by revealing that this tool creates a staged operation rather than directly executing the cancellation. It aligns with annotations (readOnlyHint: false, destructiveHint: false) by indicating a non-read-only planning action that does not itself destroy data, without contradicting any structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise, consisting of two short sentences that convey the core purpose and the critical lifecycle requirement. Each sentence adds necessary information without redundancy, and the most important detail (staged operation requiring preview/execute) is placed clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (six parameters, no output schema, and a clear three-phase sibling workflow), the description sufficiently explains where this tool fits but omits details about the return value or how to reference the created plan. The sibling tool names and schema partially compensate for this gap, but a brief mention of the plan ID or next steps would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all six parameters, including their default values and enums, achieving 100% coverage. The description does not add any additional parameter-level semantics, which is acceptable given the schema's completeness, but it also does not enhance understanding beyond the structured definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Plan an order cancellation.' It explicitly introduces the concept of a staged operation that must be previewed and executed, which distinguishes it from the sibling order_cancel_preview and order_cancel_execute tools by explaining its role as the initial planning step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description delineates the proper usage sequence by stating the operation must be previewed and executed, implying that this tool is the first step in a multi-phase workflow. It does not explicitly name alternative tools like order_cancel_preview, but the staged reference provides clear context for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by specifying that it 'marks items as shipped' and that production stores require confirm_production: true. This complements the destructiveHint and idempotentHint annotations without contradicting them, though it does not detail other potential side effects 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of three short sentences that directly convey the tool's purpose, primary effect, and a key requirement. Every sentence earns its place with no redundancy or filler, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is part of a plan/preview/execute flow, the description adequately covers the essential context: it executes a previewed fulfillment, records shipping, and notes a production-store constraint. With complete schema coverage and relevant annotations, the description is sufficient for an agent to use it correctly, though it could mention how errors or repeated executions are handled.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete coverage (100%) for all three parameters, including the confirm_production requirement. The description does not meaningfully add new information about parameters beyond what the schema states, so it sits at the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a previewed order fulfillment and marks items as shipped. This specific verb+resource combination distinguishes it from sibling tools like order_fulfill_plan and order_fulfill_preview, making its purpose immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Execute a previewed order fulfillment' provides clear context that this tool should be used after obtaining a preview, and the note about production stores requiring confirm_production adds a specific usage condition. However, it does not explicitly name alternatives or state when not to use it, which prevents a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds that the tool 'creates a staged operation' and that it 'must be previewed and executed', which clarifies the side effect (creating a plan) and the required follow-up steps. This complements the annotations without contradicting them, though it does not detail other behavioral traits like authentication or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and front-loaded with the purpose. Every sentence adds value: the first states what the tool does, the second explains the crucial planning-step behavior. There is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the presence of annotations, and full schema coverage, the description covers the essential workflow context. It explains the staged nature and the need for preview/execute, which is key. However, since there is no output schema, the description doesn't mention what the plan operation returns (e.g., an operation ID), leaving a small gap in expected response behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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, achieving 100% schema_description_coverage. The tool description does not add any parameter semantics beyond what the schema already contains, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Plan' with a clear resource 'order fulfillment', and explicitly states it creates a staged operation that must be previewed and executed. This distinguishes it from sibling tools like order_fulfill_preview and order_fulfill_execute, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the workflow: this tool creates a plan that must be followed by preview and execute steps. It gives context that this is the initial planning step, but does not explicitly name alternatives or state when not to use it. Sibling tool names reinforce the context, but explicit exclusion is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive, non-read-only, non-idempotent behavior. The description adds valuable context beyond annotations: the requirement for confirm_production on production stores, which is a critical execution detail. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
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 and includes the most critical caveat. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of annotations and a comprehensive schema, the description is largely complete. It captures the core action, the preview dependency, and the production confirmation nuance. It does not describe the return format or side effects, but these are covered by schema and annotations to a reasonable extent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and all parameter descriptions are present, so the schema fully documents parameters. The description reinforces the purpose of confirm_production but adds no new semantic meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a previewed bulk product update, using a specific verb (execute) and resource (bulk product update). It also distinguishes itself from plan/preview siblings by emphasizing the 'previewed' prerequisite and the production confirmation requirement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after previewing (the product_bulk_update_preview step) and highlights when confirm_production is needed. It does not explicitly state alternatives or exclusions, but the context of plan/preview/execute siblings makes the intended flow clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavioral context beyond the annotations: it explicitly states 'No changes are made until execution,' clarifying that this is a staging step despite readOnlyHint being false. This helps the agent understand the tool's side-effect profile and workflow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the purpose. Every sentence earns its place by explaining the staged operation and the critical 'no changes until execution' behavior, with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description conveys the essential workflow: the tool creates a staged operation requiring preview then execution. It doesn't detail how the plan is returned or referenced, but the sibling tool names (e.g., product_create_preview, operation_list) fill that contextual gap, making it adequately complete for a planning step.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for all 9 parameters, so the description does not need to add parameter details. Baseline of 3 is appropriate; the description adds no extra semantic value but the schema already documents each parameter clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Plan a new product creation' with a specific verb and resource. It also distinguishes itself from sibling tools by explaining that it creates a staged operation that must be previewed and then executed, setting it apart from direct create/preview/execute tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear workflow guidance: this tool is used to plan, then must be previewed and executed. It implies the proper sequence without explicitly naming alternatives, but the context is sufficient for an agent to know when to use this tool versus actual creation or execution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by confirming the preview behavior ('Shows exactly what will be created') and the required sequencing, which goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the primary purpose and followed by a critical usage constraint. No wasted words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two parameters and no output schema, the description conveys the key operational context: it is a non-destructive preview that must precede execution. It stops short of describing the output format, but the response_format parameter already hints at json/markdown options, making this sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with operation_id and response_format both documented meaningfully. The description does not add parameter-level detail, but the schema already provides sufficient semantic meaning, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function: 'Preview a planned product creation' with the specific verb 'Preview' and resource. It distinguishes itself from sibling tools like product_create_execute by stating it shows what will be created rather than performing the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Must be called before execution' provides explicit when-to-use guidance within the plan-preview-execute workflow. It does not explicitly name alternatives or state when not to use, but the context is clear from the sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations indicate non-read-only, idempotent, and non-destructive behavior. The description adds the crucial staged behavior—planning does not execute directly and requires a preview step—which goes beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with purpose, and each sentence adds value (purpose, ID source, workflow requirement). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of a planning tool with four well-documented parameters and no output schema, the description sufficiently covers the tool's role in the broader publish workflow. It could mention no further prerequisites or outputs, but it is functionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents all parameters, including the fact that publication_ids come from publication_list. The description provides no additional parameter-level detail beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (plan) and the resource (publishing products to sales channels). It distinguishes this from sibling tools like product_publish_preview and product_publish_execute by explicitly naming the planning phase.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly directs users to publication_list for channel IDs and explains the staged workflow ('must be previewed then executed'). It lacks explicit exclusions or alternatives, but the workflow context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds valuable context: 'Existing tags are never removed' clarifies the additive nature and reinforces non-destructive behavior. It also discloses the production confirmation requirement, which is not fully captured by annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with exactly two sentences that front-load the core purpose and add a critical safety note. There is no redundant information or fluff; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity of this execute-step tool, the description, schema (with 100% param coverage), and annotations together provide sufficient context. The operation_id source is implicitly acknowledged via 'previewed' and explicitly in the schema, and response_format covers return preferences. No output schema exists, but the description does not need to explain return values in this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all three parameters (operation_id, response_format, confirm_production) have descriptions in the schema. The description reiterates the confirm_production requirement but does not add new parameter semantics beyond what the schema already provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a previewed additive tag operation via Shopify's tagsAdd mutation. It uses a specific verb ('execute') and resource ('tag operation'), and the phrase 'additive' distinguishes it from removal operations such as product_tags_remove_execute.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a prerequisite by saying 'previewed', indicating the operation must have been planned via product_tags_add_plan. It also notes that production stores require confirm_production=true, which is a key usage condition. It does not explicitly name alternatives, but the additive wording and sibling names provide enough context for when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context by specifying that the preview shows the distinction between genuinely new tags and already-present ones, which is not in the annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loaded with the core action and no filler. Every word contributes to understanding the tool's purpose and output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two well-documented parameters, strong annotations, and a clear description of output behavior, the context is nearly complete. It could explicitly state that no changes are applied (though annotations imply this) or mention behavior for invalid operation IDs, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for both parameters: operation_id is described as 'Operation ID from product_tags_add_plan' and response_format has an enum with default. The description adds conceptual meaning about 'additive' and 'genuinely new' but does not add further per-parameter syntax or constraints, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses the specific verb 'preview' and identifies the resource as an 'additive tag operation.' It further clarifies that it shows per-product which tags are genuinely new versus already present, which clearly distinguishes it from plan and execute siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the workflow context by referencing 'operation_id from product_tags_add_plan,' indicating this is a preview step after planning. However, it does not explicitly state when to use it versus alternatives or when not to use it, though the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds the behavioral nuance that it 'shows which named tags are actually present per product', providing insight into the output without contradicting any annotation. It does not over-disclose or conflict with the hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys purpose and key behavior without unnecessary words. It avoids repeating schema details or annotations, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only preview tool with two well-documented parameters, the description is complete enough: it explains what the tool does and the nature of its output. It does not explain the response format in detail, but with no output schema and only a response_format param, the description sufficiently covers the tool's core purpose. A small gap is the lack of workflow context (e.g., that it requires an operation_id from a plan), but that is already in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'operation_id' and 'response_format' described. The description does not add extra parameter-level detail beyond the schema; it mentions 'named tags' and 'per product' but these are operational rather than parameter-specific. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Preview a subtractive tag operation — shows which named tags are actually present per product.' The verb 'preview' and the resource 'product tags' are specific, and 'subtractive' differentiates it from addition previews or the execute step, effectively distinguishing it among sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: it is a preview for a tag removal operation, showing actual tag presence, which would be used after planning and before execution. However, it does not explicitly name an alternative tool or state 'when not to use it', so it misses the top score for explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds value by specifying that the output is a diff between current and new values, which is behavioral context beyond the annotations. It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no redundant content. It uses front-loaded language that immediately states the purpose and the key output behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter schema, rich annotations, and the output description (diff), the tool is adequately described. It does not specify error handling or return structure, but with no output schema and idempotent/read-only hints, this is not a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters (operation_id from product_update_plan, response_format with enum), giving 100% coverage. The description does not add parameter-specific detail, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a preview operation for product updates, with a specific verb ('Preview') and resource ('product update'). It distinguishes from siblings like product_update_plan and product_update_execute by stating it shows the diff between current and new values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used after creating a planned update (via product_update_plan) by referring to a 'planned product update'. It does not explicitly mention alternatives or exclusions, but the context is clear enough that this is the preview step before execution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable context about the content (types of sales channels) and the intended use (getting publication IDs for publishing). It does not describe return format or pagination, but with robust annotations this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences. The first sentence front-loads the purpose with examples; the second adds a clear motivation. Every word earns its place, and it is neither too terse nor overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with 3 well-documented parameters, strong annotations, and no output schema, the description sufficiently covers why this tool exists and how the results should be used. It explains the need for publication IDs and gives channel examples, making it complete for an agent selecting the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (limit, store, response_format) are already documented in the schema. The description adds no additional parameter-level semantics beyond what is in the schema, matching the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'List the store's publications (sales channels)'. It also provides concrete examples (Online Store, Facebook & Instagram, Point of Sale) and notes the need for a publication ID before publishing. While it doesn't explicitly contrast with siblings like product_publications_get, the scope is clear and 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool: 'You need a publication ID before you can publish a product to a channel.' It implies this tool is a prerequisite for publishing workflows, but it does not explicitly describe alternatives or when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations: it explains the staged nature (must be previewed then executed) and discloses the side effect of making membership visible to external feeds (e.g., Meta catalog). This complements the annotations (readOnlyHint=false, destructiveHint=false) without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and well-structured: three sentences covering purpose, primary use case with example, and critical workflow constraint. Every sentence adds value with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with nested objects and no output schema, the description covers the primary use case, the meaning of rule_set, and the required staging workflow. It does not explicitly state what the plan returns, but the presence of sibling status tools and the plan/preview/execute pattern makes this less critical. The description is sufficiently complete for an agent to select and invoke the tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% parameter descriptions, so the baseline is 3. The description adds meaningful semantics by giving a concrete example (TAG EQUALS 'or-cocktail-dresses') and explaining that supplying rule_set converts a manual collection to automated. This enhances understanding of the rule_set parameter beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Plan an update to a collection.' It elaborates on the primary use case (converting MANUAL to AUTOMATED) and explicitly differentiates from sibling tools by noting 'Staged: must be previewed then executed.' This distinguishes it from preview and execute tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (for planning updates, especially conversions to automated) and indirectly indicates the workflow via 'Staged: must be previewed then executed.' It does not explicitly name alternative tools or state when not to use it, but the staging note strongly implies the proper sequence with preview/execute siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds critical behavioral context: it actually creates the product, requires a prior preview, and has a production-store specific requirement. This enriches the agent's understanding of side effects and preconditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and every word earns its place. No redundancy or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, the description covers the essential context: what it does, the precondition (prior preview), and an important special case. It could mention what the response contains, but that's not necessary for tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters, but the description adds semantic weight to confirm_production by explaining its real-world necessity for production stores. It also implies operation_id is tied to the prior preview, linking it to the workflow.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Execute a previewed product creation' and 'This actually creates the product,' distinguishing it from the preview and planning siblings. The specific verb 'execute' and resource 'product creation' make 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the usage prerequisite: 'Requires prior preview' and provides a conditional rule for production stores ('Production stores require confirm_production: true'). While it doesn't name alternatives directly, the plan/preview/execute sibling pattern makes the workflow clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond annotations: 'Publishing is additive — it never unpublishes a product from a channel it is already on' explains side effects and non-destructive nature. It also highlights the production-specific requirement, adding context not present in the idempotent/destructive hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, and every sentence carries essential information. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema and the presence of annotations covering idempotency and destructiveness, the description covers the core purpose, key behavioral constraints, and a production requirement. A minor gap is that the 'previewed publish' reference could more explicitly tie to the operation_id from product_publish_plan, but overall the context is adequate for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The tool description reinforces the confirm_production parameter ('Production stores require confirm_production: true') but adds no new meaning beyond that. Baseline 3 is appropriate for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Execute' with the resource 'a previewed publish', clearly indicating this tool performs the final step of a publish operation. It distinguishes itself from the sibling plan/preview tools by referencing the preview requirement and adding the additive behavior detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The first sentence 'Execute a previewed publish' implies the prerequisite of having a previewed publish operation, and 'Production stores require confirm_production: true' gives a concrete conditional requirement. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds valuable context on top: the operation is 'subtractive' (specifying the nature of the change), requires a prior preview, and has a special production-store confirmation requirement. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus a concise note about production requirements. Both sentences carry essential information with no filler, and the key action verb appears first. It is well-structured and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an execute step in a multi-step workflow, the description covers the essential context: the operation must have been previewed, it is subtractive (destructive), and production requires confirmation. While no output schema exists, the description doesn't detail return values, but the absence is partially mitigated by the tool's role as an execution step in a predictable pattern. The minor mismatch between 'previewed' in the description and 'from product_tags_remove_plan' in the schema could be clearer, but overall context is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all three parameters with 100% coverage, giving baseline credit. The description adds semantic value by highlighting that confirm_production must be true for production stores, which is not explicit in the schema's default value or description. It also indirectly clarifies that operation_id comes from the preview step in the workflow.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Execute a previewed subtractive tag operation' — a specific verb ('execute'), a specific resource ('tag operation'), and a distinguishing modifier ('subtractive', 'previewed'). This differentiates it from sibling plan/preview tools and from add-tag operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'previewed subtractive tag operation' implies the user must first run a preview step, aligning with the plan→preview→execute sibling pattern. It also gives a clear conditional: 'Production stores require confirm_production: true.' However, it does not explicitly name the exact precedent tool (e.g., 'use after product_tags_remove_preview') or list exclusions for non-production cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by revealing that the tool creates a staged operation rather than performing an immediate update, and that 'Only provided fields will be updated,' indicating a partial-update semantic. Annotations indicate readOnlyHint=false and openWorldHint=true, but the description adds meaningful behavioral context about the staging and patch-like behavior. It doesn't disclose potential external side effects, but this is adequately covered by the openWorldHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each serving a purpose: stating the action, explaining the staged workflow, and clarifying the update semantics. No filler or redundant information is present. It is highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters and no output schema, so the description should ideally mention what the plan returns (e.g., a plan ID). It doesn't, but it does cover the essential workflow (preview and execute) and the partial-update behavior. The openWorldHint annotation and sibling tool names provide additional context. Overall, it is fairly complete for a planning step, but the lack of return-value information is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 100%, all 9 parameters are individually described. The description adds collective semantic value by stating 'Only provided fields will be updated,' which clarifies how the optional parameters behave (i.e., omitted fields retain their existing values). This is a useful addition beyond the individual property descriptions, though it doesn't explain the response_format parameter's role in the plan response.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Plan a product update.' It distinguishes itself from siblings by specifying 'Creates a staged operation that must be previewed and executed,' which sets it apart from product_update_preview and product_update_execute. The verb 'plan' is specific to this step in the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly indicates the usage sequence: 'must be previewed and executed,' meaning this tool is for creating a plan before previewing and executing. It does not explicitly exclude alternatives like bulk update or tag operations, but the staged operation phrasing provides clear context for when to use this tool. This is slightly below full clarity because it doesn't mention the specific sibling tools by name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds return-field context (name, environment, default status), which enriches the agent's understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first gives the action, the second adds useful field context. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the description covering the store attributes, it provides enough information for an agent to use it without additional explanation. No output schema exists, but the description compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (response_format) is fully documented in the schema with an enum and default, achieving 100% schema coverage. The description adds no parameter-specific details, which is acceptable at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('all configured Shopify stores'), clearly distinguishing it from other list tools like product_list or order_list. It also states the purpose of discovery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this to see available stores before performing operations,' providing clear context for when to invoke. No alternative is needed since no sibling covers the same resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description adds key behavioral context: the need for confirm_production in production and the risk of rejection when converting collection types. This is exactly the kind of context annotations alone cannot provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: the primary purpose, a critical prerequisite, and a fallback alternative. It is front-loaded with the main action and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential purpose, usage, and caveats for a destructive execute operation. However, it does not mention the return value or how to track the operation's status, though such info may be inherited from sibling tools like operation_status. Given no output schema, a slightly higher level of detail would be expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents all three parameters, so the baseline is 3. The description adds extra meaning by highlighting confirm_production's requirement for production stores, which reinforces and clarifies the schema's description. This is more than just repeating the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a previewed collection update, distinguishing it from the plan and preview stages. It names the specific action and resource, and the mention of 'previewed' differentiates it from creating a new update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: production stores require confirm_production: true, and if Shopify rejects converting a manual to automated collection, create a new automated collection with collection_create instead. This directly addresses when to use the tool and when to use an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it 'uses Shopify's tagsAdd mutation, which appends tags without touching existing ones,' and highlights concurrency safety and immunity to stale-snapshot issues. This adds meaningful behavioral context beyond the annotations (readOnlyHint, destructiveHint, idempotentHint), and no contradictions exist with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: first states the purpose, second explains behavior, third gives usage guidance. Every sentence contributes substantive information with no filler or repetition of schema details, making it compact and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, behavior, alternative selection, and parameter grouping, which is sufficient for a planning tool with no output schema. However, it does not explicitly mention the plan/preview/execute workflow or the `response_format` parameter, though these are implied by the sibling tools and schema respectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 100% of parameter descriptions, but the description adds crucial relational semantics: 'Supply either `targets` (per-product tags) or `product_ids` + `tags` (same tags for all).' This clarifies mutual exclusivity and grouping that the schema alone does not explicitly state, enhancing understanding beyond the structured fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Plan an ADDITIVE tag operation across products,' specifying the verb, resource, and operation type. It distinguishes itself from product_update and the sibling product_tags_remove_plan by emphasizing the additive nature and explicitly naming an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit direction: 'Use this instead of product_update whenever you only need to add tags,' and explains why (safe, immune to stale-snapshot tag loss). It also clarifies the two input modes (`targets` or `product_ids` + `tags`), which is actionable guidance for selecting the right parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![mcp-shopify-admin MCP server](https://glama.ai/mcp/servers/maxiomus/mcp-shopify-admin/badges/card.svg)](https://glama.ai/mcp/servers/maxiomus/mcp-shopify-admin)

Score Badge

Copy to your README.md:

[![mcp-shopify-admin MCP server](https://glama.ai/mcp/servers/maxiomus/mcp-shopify-admin/badges/score.svg)](https://glama.ai/mcp/servers/maxiomus/mcp-shopify-admin)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/maxiomus/mcp-shopify-admin'

If you have feedback or need assistance with the MCP directory API, please join our Discord server