Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mage-os-mcp Find me a waterproof jacket under $100 and tell me if it's in stock"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An open-source Model Context Protocol (MCP) server that lets AI agents shop and query a Magento / Mage-OS store. It connects to a store's public storefront GraphQL API, so any Magento 2.4+ / Mage-OS store can use it — no module to install, no admin credentials required for the core catalog tools.
Point Claude (or any MCP client) at your store and ask: "Find me a waterproof jacket under $100 and tell me if it's in stock."
Most existing Magento MCP servers are either developer tooling (help you write Magento code), admin/BI dashboards (REST + admin token), or coupled to a commercial SaaS. mage-os-mcp is deliberately different:
Shopper-first. A small, curated, read-first toolset focused on the "let an AI agent shop" use case — quality over surface area.
API-based & portable. Talks to the storefront GraphQL endpoint. Works against any store, self-hosted or cloud. No Magento module to deploy.
GraphQL-first. Uses the storefront GraphQL API where practical; REST/direct only where GraphQL genuinely can't do it.
Truly open — MIT licensed. Fork it, ship it, build on it.
Related MCP server: Shopify Storefront MCP Server
Early v1. Working tools:
Tool | Description | API |
| Free-text catalog search → SKU, name, price, stock, image | GraphQL |
| Full product detail by SKU → description, pricing, discounts, stock, categories, media | GraphQL |
| Batch availability check for up to 100 SKUs → in-stock flag + low-stock qty | GraphQL |
| Store category tree (departments + subcategories) with product counts | GraphQL |
| List products in a category by | GraphQL |
| Start an anonymous shopping cart → returns a | GraphQL |
| Add products (SKU + quantity) to a guest cart; per-item errors surfaced | GraphQL |
| View a guest cart's line items and totals by | GraphQL |
| Authenticate a customer (email + password) → returns a | GraphQL |
| Logged-in customer's profile & saved addresses (by | GraphQL |
| Logged-in customer's orders — status, totals, items, tracking | GraphQL |
Planned next: checkout / place order. B2B is intentionally out of scope for now.
Note on carts: the cart tools use Magento's guest cart mutations (no login required).
add_to_cartcurrently targets simple products by SKU; configurable/bundle products (which need selected options) are reported back inuser_errorsand are a planned enhancement.
Note on authentication:
loginexchanges credentials for a Magento customer token viagenerateCustomerToken. The token is stored server-side (in memory) and never returned to the client — tools take an opaquesession_idinstead, so the raw credential stays out of the model's context. Sessions live for the server process lifetime; if it restarts, log in again.
Node.js >= 20
A reachable Magento 2.4+ / Mage-OS store with the storefront GraphQL endpoint enabled (the default)
git clone https://github.com/<you>/mage-os-mcp.git
cd mage-os-mcp
npm install
cp .env.example .env # then edit .env
npm run buildConfiguration is via environment variables (see .env.example):
Variable | Required | Default | Description |
| ✅ | — | Store base URL, no trailing |
|
| Store view code, sent as the | |
|
|
| |
|
| Per-request timeout in milliseconds |
# Development (no build step, via tsx)
npm run dev
# Production
npm run build && npm startThe server speaks MCP over stdio. stdout is reserved for the protocol; logs go to stderr.
npm run inspectAdd to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):
{
"mcpServers": {
"mage-os": {
"command": "node",
"args": ["/absolute/path/to/mage-os-mcp/dist/index.js"],
"env": {
"MAGENTO_BASE_URL": "https://app.mage-os.test",
"MAGENTO_INSECURE_TLS": "true"
}
}
}
}src/
├── index.ts # MCP server: registers tools, wires stdio transport
├── config.ts # env-based config loader
├── magento/
│ ├── client.ts # GraphQL client (Store header, TLS/timeout handling)
│ └── queries.ts # GraphQL documents (one place to review what we ask for)
└── tools/
├── searchProducts.ts # search_products
└── getProduct.ts # get_productEach tool is a small, testable function that takes the GraphQL client + validated args and returns a plain JSON object. index.ts handles MCP registration and serialization. Adding a tool = one file in tools/ + one query in queries.ts + one registerTool call.
MIT — see LICENSE.
Add one or more products (by SKU and quantity) to a guest cart. Returns the updated cart with line items and totals. Per-item problems (out of stock, unknown SKU, configurable products needing options) are reported in user_errors rather than failing the whole call.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | One or more products to add to the cart. | |
| cart_id | Yes | The guest cart id returned by create_guest_cart. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers meaningful behavioral insight: per-item failures (out of stock, unknown SKU, configurable products needing options) are collected in user_errors instead of failing the entire call. It also discloses the return shape (updated cart with line items and totals). It does not cover aspects like cart validation or quantity merge semantics, but the disclosed error model is substantial and actionable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with the primary action, followed by return value and error-handling behavior. Every sentence contributes essential information with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description explicitly states what is returned (updated cart with line items and totals) and how errors are surfaced (user_errors). It covers the main invocation outcome and the partial-failure behavior. It is slightly light on prerequisites and edge cases, but for a two-parameter guest-cart tool this is a solid, usable description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, with clear explanations for cart_id, items, sku, and quantity. The description adds only an echo of 'by SKU and quantity' and does not supplement parameter meaning beyond the schema. Baseline 3 is appropriate because the schema already documents parameters fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Add one or more products (by SKU and quantity) to a guest cart.' It clearly distinguishes this from sibling tools such as view_cart, check_stock, and create_guest_cart. The mention of returning the updated cart with line items and totals further pins down the tool's role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the use case clear: adding products to a guest cart. It implies a prerequisite via 'guest cart' plus the schema's reference to create_guest_cart, but it does not explicitly state when to avoid this tool or name alternatives. Still, the context is clear enough for an agent to know this is the relevant action for populating a cart.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the store's category tree (departments and their subcategories) with product counts. Use this to discover how the catalog is organized, then pass a category uid to get_category_products to list its items.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must establish the read/discovery profile itself. 'Return the store's category tree' makes clear this is a read operation, and 'with product counts' states what payload detail to expect. It does not disclose caveats, but for a zero-parameter catalog read none are strongly needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the first states the return value, the second gives practical routing guidance. The description does not repeat the title or schema contents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-argument catalog browse tool with no output schema, the description tells the agent what it will receive (a tree of departments/subcategories with counts) and how to continue. The only minor omission is the exact response shape, which is not necessary for successful invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool exposes zero parameters, and schema coverage is trivially 100%, so there is no parameter burden for the description to carry. The mention of category uid refers to the downstream get_category_products tool, not to this call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opening phrase 'Return the store's category tree...' pairs a specific verb with a concrete resource and scopes it to departments/subcategories and product counts. The closing reference to get_category_products helps distinguish this tree-discovery tool from the item-listing sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this to discover how the catalog is organized' is an explicit invocation condition, and 'then pass a category uid to get_category_products' names the next-action alternative. This gives the agent a clear decision path without requiring schema inspection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check availability for one or more products by SKU. Returns, per SKU, whether it was found, whether it is in stock, and the remaining quantity when the store exposes a low-stock threshold. Use this to confirm availability before recommending or ordering items.
| Name | Required | Description | Default |
|---|---|---|---|
| skus | Yes | One or more exact SKUs to check availability for (up to 100 in a single call). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the return values (found, in stock, remaining quantity when a low-stock threshold is exposed), but does not explicitly state that it is a read-only operation, nor does it cover error handling, permissions, or rate limits. Some behavioral traits remain unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the action and expected output, then gives a practical usage note. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description adequately covers what the tool does, what it returns, and when to use it. It is missing details like error handling and authorization, but the tool is straightforward enough that these are not critical for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the skus parameter is fully documented in the schema. The description's mention of 'by SKU' and 'one or more products' reinforces the parameter's purpose but adds minimal new meaning beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a stock-availability check by SKU and specifies the per-SKU return fields. It is specific enough to distinguish from sibling tools like get_product or search_products, but it does not explicitly name alternatives, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit usage directive: 'Use this to confirm availability before recommending or ordering items.' This provides clear context for when to call the tool, though it does not mention when not to use it or reference alternative tools, preventing a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new anonymous (guest) shopping cart. Returns a cart_id that you must pass to add_to_cart and view_cart. Call this once at the start of a shopping session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the side effect (creating a new cart), the return value (cart_id), the required follow-up usage, and the intended call frequency ('once'). For a zero-input creation tool, this is a complete behavioral contract.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the core purpose, then immediately provides the return contract and usage guidance, making it highly scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, absence of input parameters, and lack of output schema, the description supplies everything needed for correct invocation: what the tool does, what it returns, and how the result is used downstream. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter information for the description to add. The description appropriately focuses on the output contract instead, which meets the baseline for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Start a new anonymous (guest) shopping cart.' It clearly distinguishes itself from siblings like search_products, add_to_cart, and view_cart by focusing on cart creation and naming its return value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: 'Call this once at the start of a shopping session.' It also tells the agent that the returned cart_id must be passed to add_to_cart and view_cart. It does not explicitly state when not to use it, such as for logged-in users, but 'anonymous (guest)' makes that implication clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List products within a category by its uid (from browse_categories), with pagination and sorting. Use this to show what's available in a department, e.g. everything in 'Bags'.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Result ordering. 'position' is the merchandised category order. | position |
| pageSize | No | How many products to return (1-50, default 10). | |
| currentPage | No | Page number for pagination (default 1). | |
| category_uid | Yes | The category `uid` to list products for (obtain it from browse_categories). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the safety burden: 'List' and 'with pagination and sorting' disclose that this is a read-only, paginated operation supporting sort options. It also states the prerequisite (uid from browse_categories). It doesn't mention response shape or rate limits, but for a straightforward read-only list tool the key behavioral traits are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler: the first states the operation and its key behaviors, the second gives a concrete use case. Front-loaded purpose and efficient example make the description scannable and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters, no output schema, and no annotations, the description covers purpose, usage context, pagination, and sorting. It leaves out the exact return envelope (e.g., whether pagination metadata is included), but for a list call with standard product objects this is a minor gap; an agent can invoke it correctly with the schema and description provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already documented. The tool description reinforces category_uid's provenance (from browse_categories) but adds no new meaning beyond the schema; the sorting options and pagination defaults live fully in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('products within a category'), identifies the key identifier (`uid`), and explicitly mentions pagination and sorting. It also orients the agent by referencing browse_categories as the uid source and gives a concrete department example, distinguishing it from search_products (search) and get_product (single item).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit usage context with 'Use this to show what's available in a department, e.g. everything in Bags' and tells the agent to obtain the uid from browse_categories. While it doesn't name a direct alternative or exclusion condition, the phrasing clearly routes selection to this tool for category listing rather than searching or fetching one product.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the logged-in customer's profile (name, email, saved addresses) using a session_id from login.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session_id returned by login. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It conveys that the operation is a read ('Get'), requires authentication via session_id, and is scoped to the logged-in customer. However, it does not mention failure modes, session expiration, or explicitly confirm there are no side effects, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the resource, includes the key returned fields, and states the required authentication context. Every word contributes necessary information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter getter, the description provides the essential context: what is being fetched, for whom, and how authentication is supplied. It names the returned profile fields, partially compensating for the lack of an output schema. It could be slightly more explicit about error or invalid-session behavior, but overall it is sufficiently complete for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents session_id as 'The session_id returned by login.' The description reinforces this by saying 'using a session_id from login,' but it adds no new parameter 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get'), the specific resource ('logged-in customer's profile'), and the fields returned ('name, email, saved addresses'). It also distinguishes itself from siblings by emphasizing the logged-in scope and the session_id requirement, which no other sibling tool mentions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is used after login, since it requires a session_id from login and targets the logged-in customer. No explicit alternatives or exclusions are given, but no sibling tool appears to offer the same profile-fetching functionality, so the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up the logged-in customer's orders (status, date, totals, line items, tracking) using a session_id from login. Optionally pass an order_number to fetch a single order; otherwise the most recent orders are returned.
| Name | Required | Description | Default |
|---|---|---|---|
| pageSize | No | How many recent orders to return when no order_number is given. | |
| session_id | Yes | The session_id returned by login. | |
| order_number | No | Optional order number (e.g. '000000001') to look up a single order. Omit to list the customer's most recent orders. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the data returned, the session-based auth requirement, and the different behavior with and without order_number. It does not mention edge-case behavior like invalid sessions or nonexistent orders, but the core behavioral contract is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence states the purpose and expected output; the second explains the key branching parameter behavior. Everything present earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, and the description compensates by summarizing the returned fields. It covers authentication context, single vs. list behavior, and optional parameters. Minor gaps like response format details and error behavior are acceptable for a simple lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful relational semantics: order_number changes the call from a list to a single-order lookup, and pageSize applies only when listing recent orders. This goes beyond the individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific action ('Look up') and resource ('logged-in customer's orders'), and enumerates the returned data fields. It distinguishes this tool from cart/product/customer siblings by focusing on order status and order history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: use with a session_id from login, optionally pass an order_number for a single order, otherwise get recent orders. It does not explicitly name alternatives or exclusions, but this is not needed given the sibling set and the specificity of the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch full details for a single product by its exact SKU: description, pricing (incl. discounts), stock, categories and images.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | Yes | The exact SKU of the product to retrieve. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden, and 'Fetch' reasonably signals a read-only operation. It adds some value by naming exactly what is returned, but it does not disclose error behavior, authentication needs, rate limits, or what happens when the SKU is not found. This leaves some behavioral uncertainty for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly written sentence with the action and resource front-loaded. Every phrase adds useful information, and there is no padding or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one parameter, no output schema, and no annotations. The description covers the lookup key and the main returned fields, which is enough for most invocations. It does not mention not-found responses or auth, but for a single-product fetch this is a minor gap rather than a blocking one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the only parameter 'sku' is already described as 'The exact SKU of the product to retrieve.' The description repeats the exact-SKU idea without adding new meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific verb 'Fetch' and a clear resource: a single product by exact SKU. It enumerates the included data areas (description, pricing, discounts, stock, categories, images) and implicitly distinguishes itself from siblings like search_products and check_stock.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by its exact SKU' provides clear context: use this tool when the caller already has a precise SKU and needs full product details. It does not explicitly name alternative tools or say 'use search_products when you do not have an exact SKU,' so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Authenticate a customer with email and password. Returns a session_id to use with get_customer and get_order_status. The credential is stored server-side and never returned. Returns success:false with a reason if the credentials are wrong.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | The customer account email address. | ||
| password | Yes | The customer account password. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It reveals that credentials are stored server-side and never returned, and that failed authentication returns 'success:false with a reason.' This adds meaningful behavioral context beyond the operation name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each earning its place: the core action, the downstream use of the session_id, and the error behavior. Information is front-loaded and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential return values (session_id, success:false with reason) despite the lack of an output schema, and ties the tool to downstream callers. It does not specify session expiration or exact response structure, but for a simple login tool this is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter descriptions already document email and password. The tool description adds minimal semantic value, mentioning that authentication uses email and password and that the credential is not returned, but this does not go beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Authenticate') and resource ('a customer'), and clarifies the purpose by explaining the returned session_id is used with get_customer and get_order_status. This clearly differentiates login from the read-oriented sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context by indicating that login should happen before using get_customer and get_order_status, and hints at the failure mode for bad credentials. It does not explicitly mention when not to use it or name alternatives, but the intended use is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the store catalog by free-text term. Returns matching products with SKU, name, price, stock status and image. Use this to discover products before fetching full details with get_product.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Result ordering. | relevance |
| search | Yes | Free-text search term, e.g. 'jacket' or 'yoga pants'. | |
| pageSize | No | How many products to return (1-50, default 10). | |
| currentPage | No | Page number for pagination (default 1). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It does state the behavior ('free-text search') and the output fields, but it does not disclose matching semantics, empty-result behavior, authentication needs, or rate limits. The core behavior is visible, but edge-case behavior is not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences. The first states the action and output; the second gives the follow-up workflow. There is no filler, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with a well-described schema, the description is largely complete: it explains what is searched, what fields are returned, and how it relates to get_product. Without an output schema, listing the returned fields is valuable. A small gap is the lack of guidance on when to prefer browsing tools over search.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter already has meaningful descriptions with defaults and enum values. The tool description reinforces that 'search' is free-text but adds no new parameter-level detail beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Search the store catalog by free-text term.' It also lists the returned fields (SKU, name, price, stock status, image) and distinguishes itself from get_product by positioning this as the discovery step. This is clear and non-tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this to discover products before fetching full details with get_product,' which gives an agent a clear workflow context. It does not mention alternative search/browse tools like browse_categories or get_category_products, but the free-text nature is implied well enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
View the current contents and totals of a guest cart by its cart_id.
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | The guest cart id returned by create_guest_cart. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. 'View' and 'current' suggest a non-mutating snapshot, but the description does not disclose behavior for missing, expired, or empty carts, nor whether any authorization is required. It does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that states the action, resource, and key requirement with no filler or redundant phrasing. It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only tool this is nearly complete: it identifies the cart, the operation, and what is returned conceptually. The lack of an output schema means some detail about the format of 'contents and totals' is absent, but the essential calling context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already explains that cart_id is 'The guest cart id returned by create_guest_cart.' The tool description mostly restates this connection without adding new parameter-level meaning, so a baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('View') and names the exact resource ('contents and totals of a guest cart') plus the identifying mechanism ('by its cart_id'). This clearly distinguishes it from sibling tools like create_guest_cart and add_to_cart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after a guest cart has been created by referencing the cart_id returned by create_guest_cart. It does not explicitly state when to prefer this over alternatives or when not to use it, but the context is reasonably clear for a simple read operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_to_cartbrowse_categoriescheck_stockcreate_guest_cartget_category_productsget_customerget_order_statusget_productloginsearch_productsview_cartScored across 11 tools
Every tool targets a distinct resource and action: catalog search vs. category browsing, product detail vs. stock check, and cart creation vs. cart viewing are clearly separated. Customer tools (login, get_customer, get_order_status) are also unambiguous in their scope.
The vast majority of tools follow a consistent verb_noun snake_case pattern (search_products, get_product, check_stock, add_to_cart, view_cart). The only deviation is 'login', which is a bare verb without an object, but this is a common and acceptable exception.
With 11 tools, the server is well-scoped for a storefront assistant. Each tool covers a meaningful step in catalog browsing, cart management, or customer account access without redundancy or bloat.
The catalog and customer account surfaces are well covered, but the cart workflow is incomplete: there is no way to update quantities or remove items, and there is no checkout or order placement tool. This creates a notable dead end after building a cart.
Agentic commerce gateway: discovery, search, checkout across Shopify/Woo/Odoo/PrestaShop.
AI shopping gateway for product search, inventory, carts, and merchant-hosted checkout.
AI-powered commerce API for luxury skincare shopping. Enables AI agents to search products, browse collections, manage shopping carts, and generate checkout URLs for the Regenique Elegance Shopify store.
Score a Magento or Adobe Commerce store on eight AI agent-readiness checks.
