Shopping MCP Server
The server provides an authenticated, eBay-backed shopping MCP server for product discovery, cart management, checkout quotes, and order handling.
Search the eBay catalog with
search_products(text query, category, sort, pagination).Read item details with
get_product.Browse taxonomy with
get_categories(full tree or subtree).Manage a user cart with
add_to_cart,view_cart, andupdate_cart_item(server-side pricing; quantities can be set to 0 to remove).Create checkout quotes with
checkout, including live price/availability verification and a shipping address.Place orders from an unexpired quote with
place_order, which clears the cart and is idempotent.View and manage orders with
get_order,order_history, andcancel_order(orders are user-scoped).Access resources and widgets such as
shopping://featured-products,shopping://categories,health://checks,metrics://shopping, and theshopping_assistantprompt.Enforce JWT authentication and scopes (
shopping:read,shopping:write) for all protected operations.
Provides access to eBay's catalog via Browse and Taxonomy APIs, enabling product search, item detail retrieval, and marketplace category tree exploration for the shopping server.
Click on "Install 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., "@Shopping MCP Serversearch for wireless headphones under $100 and add the top result to my cart"
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.
Shopping MCP Server
A production-oriented shopping MCP server built with NitroStack. It exposes an eBay-backed product catalog, authenticated carts and orders, health resources, prompts, and seven static-export widgets.
place_orderrecords an order in this service. It does not charge a payment method or create an eBay fulfillment order. Add a payment/fulfillment provider before using it for real commerce.
Features
eBay Browse search, item details, and Taxonomy category trees
Offline demo catalog for local development (
EBAY_MOCK=true)JWT authentication compatible with a Better Auth JWT plugin
User-scoped cart and order persistence
Postgres/Neon in production, atomic JSON-file storage locally, and
:memory:test modeLive price and availability verification during checkout
Expiring checkout quotes, order history, and cancellation
Zod input validation, normalized inputs, typed domain errors, structured responses, logging, caching, and eBay quota protection
Database, eBay, and system health checks exposed as
health://checksProduct, cart, and order resources plus the
shopping_assistantpromptProduct, search-results, category-tree, cart-summary, confirmation, order-summary, and cancellation widgets
Related MCP server: commerce-mcp-server
Requirements
Node.js 22+
pnpm 11+
eBay application credentials for live catalog access (optional for demo mode)
Postgres/Neon
DATABASE_URLfor multi-instance production persistence
Quick start
pnpm install:all
cp .env.example .env
pnpm verify
pnpm devpnpm verify builds the server and widgets, starts an isolated stdio MCP server, and exercises tool schemas, resources, prompt execution, JWT authorization, catalog lookup, cart updates, checkout, order placement, history, cancellation, and cart isolation.
Configuration
Copy .env.example and set values for the deployment. Important settings:
Variable | Purpose |
| Explicit signing algorithm and Better Auth JWKS endpoint ( |
| Current and temporary previous HMAC secrets; required only for HS* verification and at least 32 bytes outside development |
| Required JWT claim validation values ( |
| Issuer token lifetime and maximum accepted |
| Maximum age of cached public keys before refresh (default |
| Postgres/Neon connection string; required outside development and takes precedence over file storage |
| Single-process local JSON store, or |
| eBay keyset for live Browse/Taxonomy calls |
| eBay marketplace, default |
| Set |
|
|
| HTTP listener settings; production defaults to |
| CORS opt-in and exact comma-separated HTTP(S) origin allowlist; wildcard origins are rejected |
| Decimal tax rate used in checkout, for example |
| Must be set explicitly outside development; only |
| Checkout quote lifetime, default |
| Curated item list, or the fixed query used by |
| Bounded exponential backoff for transient eBay failures only |
| Bound a taxonomy response so a full tree cannot overflow a client |
|
|
| Reverse-proxy header policy; an |
| Include storage mode and applied migrations in |
| Advertise OAuth 2.1 discovery metadata for external MCP clients |
In development, missing eBay credentials are allowed for the offline demo. Outside development, set EBAY_MOCK=true to explicitly allow demo mode, or set EBAY_MOCK=false and provide both eBay credentials. A production configuration never silently falls back to the demo catalog. Monitor health://checks for the configured eBay status.
MCP surface
Tools
Tool | Auth | Description |
| Public | Search the eBay catalog |
| Public | Read current item details |
| Public | Read the marketplace category tree or subtree |
| JWT + | Add or increment a user cart item |
| JWT + | Read the authenticated user cart |
| JWT + | Set quantity; |
| JWT + | Create a ten-minute quote with live price/availability checks |
| JWT + | Persist an order from an unexpired quote and clear the cart |
| JWT + | Read one order owned by the authenticated user |
| JWT + | List the authenticated user’s orders |
| JWT + | Cancel an order owned by the authenticated user |
Protected calls use a Bearer token. For MCP clients, provide it as _meta.authorization: "Bearer <token>"; for Streamable HTTP clients, send the normal Authorization header. The verified JWT sub is the user ID—no tool accepts a caller-supplied userId. Tokens must contain a non-empty sub, iss, aud, and unexpired exp claim.
Authentication configuration
The selected strategy is a Better Auth JWT bridge for a trusted first-party frontend. The supported clients are that frontend and MCP clients that can forward bearer credentials. Better Auth must issue a signed JWT with a stable application-user sub claim. The recommended Better Auth JWT plugin configuration uses its JWKS endpoint and EdDSA; this server also supports explicitly configured RS*, PS*, ES*, and HS* algorithms. The server expects the following token contract from .env.example:
JWT_ALGORITHM=EdDSAandJWT_JWKS_URI=https://<frontend>/api/auth/jwks(recommended)Or
JWT_ALGORITHM=HS256andJWT_SECRETwhen the issuer is explicitly configured to mint HMAC tokensJWT_AUDIENCE=amazon-mcpJWT_ISSUER=better-authJWT_EXPIRES_IN=1h(the issuer controls the actualexpclaim)
The guard verifies the signature against the configured HMAC secret or cached remote JWKS, requires an explicit algorithm allowlist, validates expiration, issuer, audience, and non-empty sub, and fails closed when JWKS cannot validate a token. It accepts Authorization: Bearer <token> from HTTP requests and the equivalent MCP _meta.authorization metadata. Protected reads require shopping:read; cart, checkout, placement, and cancellation writes require shopping:write. A token with both scopes is needed for the complete recommended flow.
The corresponding Better Auth configuration should make these values explicit (the scopes should come from the application's authorization policy):
jwt({
jwks: {
keyPairConfig: { alg: 'EdDSA', crv: 'Ed25519' },
rotationInterval: 60 * 60 * 24 * 30,
gracePeriod: 60 * 60 * 24 * 30,
},
jwt: {
issuer: process.env.JWT_ISSUER,
audience: process.env.JWT_AUDIENCE,
expirationTime: process.env.JWT_EXPIRES_IN,
getSubject: (session) => session.user.id,
definePayload: ({ user }) => ({
sub: user.id,
scopes: ['shopping:read', 'shopping:write'],
}),
},
})Key rotation
For HMAC mode, JWT verification supports a current secret and one temporary previous secret. To rotate without logging out active users:
Generate a new random secret and deploy it as
JWT_SECRET.Move the old value to
JWT_SECRET_PREVIOUSin the same deployment.Keep the previous value for at least the maximum token lifetime (and any clock-skew/rollout buffer).
Remove
JWT_SECRET_PREVIOUSin a later deployment after that window.
For the recommended JWKS mode, configure Better Auth's rotationInterval and gracePeriod; the server caches the JWKS, refreshes on key IDs, and never falls back to an old or unsigned key when verification fails. Never log secrets or tokens. A token signed by any other key/secret, with the wrong issuer/audience, malformed claims, wrong signature, or expired exp is rejected.
OAuth discovery is intentionally not enabled by default because this deployment targets a trusted first-party frontend. If external OAuth authorization-server clients are required, configure NitroStack's OAuth module and discovery endpoints before exposing the HTTP transport to them.
Recommended flow:
search_products → get_product → add_to_cart → view_cart
→ checkout → confirm quote → place_order → get_orderResources and prompt
shopping://catalog-guideshopping://featured-productsshopping://categoriesshopping://cart-guideshopping://order-guideshopping://order-statusesmetrics://shoppinghealth://checkswidget://examplesshopping_assistantprompt for guided product research
Widget resources are automatically registered for every tool decorated with @Widget. pnpm build runs the Next.js static export and places the seven bundles in src/widgets/out/.
Commands
pnpm dev # development stdio server
pnpm build # widget export + TypeScript build
pnpm test # build + unit tests + MCP protocol tests
pnpm test:unit # unit and persistence tests only
pnpm test:coverage # unit tests with coverage thresholds
pnpm test:postgres # persistence tests against TEST_DATABASE_URL
pnpm verify # build + lint + typecheck + unit tests + protocol tests
pnpm verify:mcp # stdio, HTTP, dual, JWKS, and widget-mode protocol tests
pnpm verify:live # live eBay checks; skips without EBAY_APP_ID/EBAY_CERT_ID
pnpm lint # repository lint and formatting checks
pnpm typecheck # TypeScript only
pnpm start # build, then start
pnpm start:prod # start an existing dist buildPostgres coverage is opt-in and truncates every shopping table, so point it only at a disposable database:
TEST_DATABASE_URL=postgresql://user@localhost:5432/amazon_mcp_test pnpm test:postgresCorrectness guarantees
Cart contents come from the server.
add_to_cartaccepts onlyitem_idandquantity; the title, price, currency, URL, and availability are fetched from eBay. A forged price or a nonexistent item cannot enter a cart.Cart writes are atomic. Every mutation is a locked read-modify-write (a per-user advisory lock plus row lock on Postgres, a serialized write queue for the file adapter), so concurrent
add_to_cartcalls cannot lose an update.Quotes are durable and cart-bound. A checkout quote is persisted and fingerprinted against the cart it was priced from. If the cart changes afterwards,
place_orderreturns a conflict and the newer cart is left intact.Placement re-validates and is idempotent. Prices and availability are re-read immediately before placement, and the
checkout_idacts as the idempotency key: a retry returns the original order (alreadyPlaced: true), and two replicas cannot both consume one quote.The eBay budget is shared. With
DATABASE_URLthe daily application quota is an atomic Postgres counter that survives restarts and is shared by every replica. It counts eBay requests, not tool calls, because@Cachewraps@RateLimit.Failures stay quiet. Upstream messages are redacted before they reach tool output, logs, or metrics, and unexpected errors are replaced with a generic message.
Observability
metrics://shopping reports tool invocations, failures and error codes, eBay request counts, latency, retries and failure categories, catalog cache hit rate, quota usage, storage mode, applied migrations, and evaluated alerts (sustained eBay failures, a low or exhausted daily budget, an unreachable quota counter). It contains names, counts, and durations only — never tokens, credentials, or shopper data.
Over HTTP, /healthz is liveness (process only, so a dependency outage never triggers a restart) and /readyz is readiness (fails when persistence is unusable; a degraded eBay dependency is reported but does not remove the replica from service). health://checks remains the MCP-facing view.
Persistence and deployment
The Postgres adapter applies versioned, forward-only migrations at startup (shopping_schema_migrations), each inside a transaction under an advisory lock so concurrent replicas cannot apply the same version twice. It creates shopping_carts, shopping_orders, shopping_quotes, and ebay_quota, and scopes every read by the authenticated user.
Postgres is required for more than one replica. Carts, checkout quotes, orders, and the eBay quota counter all live there. The JSON adapter keeps its state in one process and is for a single local/demo instance only.
Before deployment:
Set
NODE_ENV=productionand explicitly chooseMCP_TRANSPORT_TYPE=http(ordualonly when stdio is intentionally needed).Set
HOST=0.0.0.0,DATABASE_URL, TLS settings,JWT_SECRET, and live eBay credentials through the secret manager.Set
SHOPPING_FULFILLMENT_MODE=demoexplicitly; startup fails without it outside development.Keep
EBAY_MOCK=falsefor live access and verifyhealth://checksreports the database and eBay asup.Run
pnpm verify, andpnpm verify:liveonce against the eBay sandbox with real credentials.Put the HTTP transport behind TLS. Set
TRUSTED_FORWARDED_HOSTSto the public host andREQUIRE_HTTPS=truewhen a proxy terminates TLS. Leave CORS disabled for non-browser clients, or setENABLE_CORS=truewith an exactCORS_ALLOWED_ORIGINSallowlist; wildcard CORS is not supported.Load
JWT_*,DATABASE_URL, and eBay credentials from the platform's secret store. Never commit a.env.
Logging and retention
Log records carry a request ID, tool name, authenticated subject, duration, and error code. Tool input is never logged, because it can contain a shipping address and _meta.authorization carries a bearer token; upstream eBay messages are redacted before they are logged. Treat the subject claim as personal data and keep operational logs to the shortest retention your incident process allows.
Not a real commerce backend
place_order records an order in this server's database. There is no payment authorization or capture, no inventory reservation, no eBay order or fulfilment integration, and no refund handling — the eBay Browse and Taxonomy APIs are read-only under an application token and cannot reserve stock. Orders therefore have exactly two states, placed and cancelled, any un-cancelled order is eligible for cancellation, and every order reports fulfillment: "demo". SHOPPING_FULFILLMENT_MODE=external is rejected at startup so a deployment cannot appear to be something it is not.
Available Tools
11 toolsadd_to_cartAdd to cartC
Add a product to the authenticated user cart. Never pass a user ID; it comes from the JWT subject.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Optional title snapshot from get_product | |
| item_id | Yes | eBay item ID from get_product | |
| currency | No | Optional ISO currency code | |
| quantity | Yes | Number of units to add | |
| condition | No | Optional item condition | |
| image_url | No | Optional product image URL | |
| unit_price | No | Optional displayed price snapshot | |
| item_web_url | No | Optional eBay item URL |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the burden of behavioral disclosure. It states that the user ID comes from the JWT subject, which is a useful constraint, but it does not reveal other behavioral aspects: whether adding an existing item increases the quantity or creates a duplicate, what happens on failure, or any side effects beyond the implicit write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise, consisting of two sentences with no redundancy. It front-loads the primary action and follows with the key constraint, both of which are instantly actionable. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description is thin. It does not cover how the system handles duplicate items, what happens when quantity exceeds limits, or how the cart is confirmed. The presence of a sibling tool like update_cart_item makes it crucial to clarify behavior when adding an already existing item, which is not addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for all 8 parameters, including the origin of item_id and the optional fields. The description adds minimal extra meaning beyond the schema, but even with full schema coverage, it does not explain the purpose of snapshot fields like title or unit_price in this context, which remains at 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 clearly states the action (add a product to the authenticated user cart) and names the resource (cart). It is distinct from siblings like view_cart or update_cart_item, though it does not explicitly differentiate itself, making the purpose easily discernible.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks guidance on when to use this tool versus alternatives. It mentions that the user ID comes from the JWT subject, but does not explain when to prefer add_to_cart over update_cart_item or how to handle existing cart entries. There is no mention of exclusions or alternative scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cancel_orderCancel orderA
Cancel an order belonging to the authenticated user when it has not already been cancelled.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | Order ID to cancel |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the action and prerequisites, but does not mention side effects (e.g., order status changes to cancelled), error behavior for already-cancelled orders, or whether cancellation is reversible. This is a minimal viable description but not richly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and immediately follows with the key conditions. Every word earns its place, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with no output schema, the description covers the essential context: who can use it and when it applies. It does not specify the resulting state or error handling, but these are less critical for a straightforward cancel operation. Overall, it is sufficiently complete for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the parameter order_id is already documented as 'Order ID to cancel'. The description adds no additional semantics beyond restating the action. A baseline of 3 is appropriate because the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Cancel') and resource ('an order'), and adds two important scoping conditions: it must belong to the authenticated user and must not already be cancelled. This distinguishes it from sibling tools like get_order or place_order, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: only cancel orders owned by the authenticated user and only when they are not already cancelled. It does not explicitly name alternatives or say when not to use this tool, but the conditions are sufficient for most agents to decide correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
checkoutPreview checkoutA
Create a short-lived checkout quote using live eBay prices and availability. This does not place an order.
| Name | Required | Description | Default |
|---|---|---|---|
| shipping_address | No | Optional address used to calculate the checkout quote |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It reveals the most important side effect boundary ('This does not place an order') and notes the quote is short-lived and uses live data. However, it does not explain whether the quote is saved, whether the operation modifies the cart, or what prerequisites are required (e.g., existing items). For a non-destructive preview tool, this is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. It front-loads the core purpose and immediately includes the key limitation ('does not place an order'). Every word contributes to understanding the tool's role.
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 definition is fairly complete for a simple one-parameter tool, but it lacks an output schema and does not describe what the returned quote contains, nor does it state whether a cart or items must exist before calling. Since the only parameter is well-documented in the schema, the main gaps are output format and usage prerequisites, making the description somewhat incomplete for confident 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 schema description coverage is 100%: the only parameter, shipping_address, is fully described ('Optional address used to calculate the checkout quote'). The tool description itself makes no mention of parameters, so it adds no semantic value beyond the schema. Baseline 3 applies because the schema already handles the meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly specifies the action ('create a short-lived checkout quote') using live eBay prices, and explicitly states what it does not do ('This does not place an order'). This disambiguates it from the sibling tool place_order, giving an agent a precise understanding of 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: this tool is for previewing checkout with live prices, not for finalizing orders. It does not explicitly name the alternative tool (place_order) or specify prerequisites like 'items must be in the cart', but the 'does not place an order' statement provides a key exclusion that helps route an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_categoriesGet product categoriesA
Retrieve the eBay category tree, or a category subtree when category_id is supplied.
| Name | Required | Description | Default |
|---|---|---|---|
| category_id | No | Category ID, or 0 for the complete tree | 0 |
TDQS
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 clearly states this is a read-only retrieval operation, which is inherently safe. However, it does not disclose any behavioral traits such as error handling for invalid category_id, size limits, or response structure. For a simple read operation, this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, and every word contributes meaning. It is concise without losing necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and no output schema, the description covers the core call logic. It could specify what a subtree looks like or how invalid IDs are handled, but the low complexity and the schema's documentation of the parameter make this sufficiently complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% because the property description for category_id explains its meaning and the '0' special case. The tool description adds a subtle point about subtree behavior but does not materially go beyond the schema. This aligns with the baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and names the exact resource ('eBay category tree'), including the optional subtree case. This clearly differentiates it from the sibling tools, which are all about products, cart, or orders—none deal with categories.
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 primary use case explicit: retrieve the full tree by default or a subtree when category_id is provided. It does not explicitly list when not to use it, but since there is no alternative category tool among siblings, this guidance is adequate. A small gap is not mentioning that omitting category_id is equivalent to 0.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_orderGet orderB
Retrieve one order belonging to the authenticated user.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | Order ID returned by place_order |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It states the scoping constraint ('belonging to the authenticated user') but does not disclose what happens if the order is not found, whether the operation is read-only, or any authorization requirements. The verb 'Retrieve' implies a safe read, providing basic transparency without detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, direct sentence with no filler. The key information (action, resource, ownership) is front-loaded and every word earns its place. Ideal conciseness for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description conveys the essential intent but lacks guidance on use cases and error behavior. It is minimally viable but leaves the agent to guess about return format and failure modes.
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 order_id parameter is well-documented ('Order ID returned by place_order'). The tool description adds no additional parameter context beyond the schema, 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Retrieve') and resource ('one order'), and clarifies ownership ('belonging to the authenticated user'). It distinguishes from order_history by implying a single order fetch, though it does not explicitly mention lookup by ID. Clear enough for an agent to understand the core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like order_history or cancel_order. The description does not mention conditions such as needing an order_id from place_order, nor does it contrast with list operations. An agent must infer usage from the parameter schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_productGet productA
Retrieve current details and pricing for one eBay item.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | eBay item ID, for example v1|123|0 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. 'Retrieve' implies a read-only operation, and 'current details and pricing' indicates the data returned. However, it does not disclose potential errors, authentication requirements, or response structure. Acceptable for a simple lookup but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that is easily front-loaded and contains no filler. Every word contributes to understanding the tool's 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 tool with one parameter and no nested objects, the description covers the core purpose. It lacks explicit mention of response format or error handling, but 'current details and pricing' hints at the output. Given the simplicity, the description is sufficient for agent 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 only parameter 'item_id' is fully described in the schema (100% coverage). The description adds no additional parameter meaning beyond the schema, 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?
States a specific verb ('Retrieve'), a specific resource ('current details and pricing for one eBay item'), and scope ('one eBay item'). This clearly distinguishes it from sibling tools like search_products (searching) and get_categories (taxonomy).
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 the tool is for fetching a single item's details, which is clear context. It does not explicitly mention when to use it over alternatives (e.g., after searching), but the single-item scope is enough guidance for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
order_historyOrder historyA
List orders belonging only to the authenticated user, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of orders to return | |
| status | No | Optional status filter |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It discloses user scoping and sorting order, but does not explicitly state that this is a read-only operation or mention authentication requirements. It adds some value beyond the schema but lacks completeness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly written sentence that conveys the essential scope and ordering without any wasted words. It is front-loaded with the action and resource.
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 two optional parameters and no output schema, the description covers the core purpose and constraints well. It lacks explicit return-format details and authentication prerequisites, but for a simple list operation, it 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 description coverage is 100%, providing descriptions for both 'limit' and 'status'. The tool description adds no parameter-specific information beyond what the schema already documents, 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 uses a specific verb 'List' and resource 'orders' with clear scope ('belonging only to the authenticated user') and ordering ('newest first'). This distinguishes it from sibling tools like get_order (single order) and place_order (creating orders).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this is a list operation scoped to the authenticated user, which implies use when retrieving order history. However, it does not explicitly state when to use this tool over get_order or how status filtering fits, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
place_orderPlace orderA
Place an authenticated user order from an unexpired checkout quote and clear the cart.
| Name | Required | Description | Default |
|---|---|---|---|
| checkout_id | Yes | Checkout ID returned by checkout | |
| shipping_address | No | Optional address to save on the order |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the core side effects (placing the order and clearing the cart) and the requirement of an authenticated user. However, it does not mention what happens on failure (e.g., expired quote), permissions, or the return value, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that efficiently conveys the action, prerequisite, and side effect. Every word earns its place, 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 simple two-parameter tool with no output schema, the description covers the essential action and side effects. However, it omits details about the response format, error conditions (e.g., expired checkout quote), and any post-conditions beyond clearing the cart. These gaps prevent a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage of parameters, including descriptions for checkout_id and shipping_address. The description adds context that the checkout quote must be unexpired, but it does not add meaningful semantics beyond what the schema already states. 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 the specific verb 'Place' and names the resource 'authenticated user order', with a clear precondition ('from an unexpired checkout quote') and a distinct side effect ('clear the cart'). This clearly differentiates it from siblings like checkout, get_order, and cancel_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'from an unexpired checkout quote' implies that the tool should be used after checkout and with a valid checkout_id. However, it does not explicitly state when to prefer this over alternatives, nor does it mention any exclusion conditions. The guidance is present but implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_productsSearch productsB
Search the eBay catalog for products matching a text query and optional category.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Optional eBay sort order | |
| limit | No | Number of products to return | |
| query | Yes | Words to search for, such as wireless headphones | |
| offset | No | Number of products to skip | |
| category_id | No | Optional eBay category ID |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must communicate behavioral traits, but it only states a basic search operation. It does not disclose pagination behavior via limit/offset, sorting choices, read-only safety, or any output characteristics. The description merely restates the tool's headline action without adding context.
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 clean sentence with no filler, and the core purpose is front-loaded. It could benefit from slightly more structure or examples, but it remains appropriately concise and easy to parse.
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 five parameters, no annotations, and no output schema, this one-line description leaves out important operational context: pagination semantics, sorting options, response shape, and how this search relates to sibling tools like get_product or get_categories. An agent must rely entirely on the schema and parameter names to understand calling conventions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input-schema descriptions already explain every parameter in detail (e.g., 'Words to search for', 'Number of products to return'). With 100% schema coverage, the baseline is 3, and the description does not meaningfully enhance parameter understanding beyond highlighting 'text query' and 'optional category'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('Search'), the target ('the eBay catalog'), the result ('products'), and the primary filtering inputs ('text query' and 'optional category'). The verb–resource pairing is specific and easily distinguishes this from sibling tools like get_product (single product lookup) and get_categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus the listed siblings (e.g., get_product for a known ID, get_categories for browsing). No exclusion conditions or alternative mentions are given, leaving the agent to infer usage from the general wording alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_cart_itemUpdate cart itemA
Set an item quantity in the authenticated user cart; quantity 0 removes it.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | eBay item ID already in the cart | |
| quantity | Yes | New quantity; 0 removes the item |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It clearly discloses that setting quantity to 0 removes the item, which is a non-obvious side effect. However, it does not mention error conditions, whether the quantity overwrites an existing value, or any authentication requirements beyond the implied 'authenticated user'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core action and includes the most important edge case (quantity 0). No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description covers the main intent and the removal edge case, but lacks information about failure modes, idempotency, or what happens when the item is not already in the cart. Given no annotations or output schema, a bit more context would be helpful, though the core usage is adequately clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds the 'authenticated user cart' context and reinforces the 0-removal behavior, but this largely mirrors the parameter descriptions rather than adding substantial new meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Set'), a clear resource ('item quantity in the authenticated user cart'), and a distinctive behavior (quantity 0 removes it). This cleanly separates it from sibling tools like add_to_cart and view_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 context by mentioning 'authenticated user cart' and the update semantics, but it does not explicitly state when to prefer this tool over add_to_cart or view_cart, nor does it mention any exclusions or prerequisites beyond authentication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
view_cartView cartA
View the authenticated user cart and its current item subtotal.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. 'View' implies a read-only operation and 'authenticated user' signals an auth requirement. It does not detail whether any side effects occur, but for a simple view operation that is likely unnecessary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence. The verb and object are front-loaded, and every word adds meaning. There is no padding or repetition of the title.
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 zero-parameter, read-only tool, the description is nearly complete. It identifies the resource and the key output (subtotal). It could perhaps mention that the full cart contents are returned, but the phrasing 'view the cart' implies this. Given the simplicity, no major gaps exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description needs to add no parameter-level meaning. The rule establishes a baseline of 4 when no parameters exist, and the description correctly focuses on behavior rather than params.
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'), names the resource ('authenticated user cart'), and adds a concrete detail ('current item subtotal'). This clearly distinguishes it from sibling tools like update_cart_item or add_to_cart, which modify the cart, and order-related 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 context is clear: this tool is for viewing the current user's cart and subtotal. It does not explicitly state when not to use it or name alternative tools, but among siblings the intended use is unambiguous because no other tool reads the cart.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
Each tool targets a distinct action or resource: search vs. specific product vs. category tree vs. cart operations vs. checkout vs. order lifecycle. No overlap in purpose, and descriptions clearly differentiate them.
Most tools follow a verb_noun pattern (search_products, get_product, get_categories, view_cart, update_cart_item, add_to_cart, place_order, cancel_order), but 'checkout' and 'order_history' deviate (single verb, noun phrase without a verb). The inconsistency is noticeable but not chaotic.
11 tools is well-scoped for a shopping domain, covering discovery, cart, checkout, and order management without unnecessary redundancy or bloat.
The tool surface covers the full shopping lifecycle: product discovery, cart, immediate cart actions, checkout, order placement, order retrieval, and cancellation. Minor gap: no direct 'get all categories' without subtree tree logic, but other methods query properly.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Search multi-merchant supply, checkout, and track orders via MCP.
Remote MCP connector for eBay, Shopify, Best Buy & Etsy marketplace data via the Commerce API
Unified MCP server for 70+ eCommerce platforms: products, orders, customers, and more.
Remote MCP for Living Stack offer discovery and buyer-authorized checkout preparation.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for eBay buyer-side workflows enabling search, watch, bid, buy, and management of MyeBay via a hybrid REST and Trading API stack.151Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables e-commerce operations such as product search, price updates, and order notes via MCP tools, with secure credential handling.
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage products, shopping carts, and orders in an online store through a well-defined MCP API.
- FlicenseNot gradedqualityDmaintenanceEnables e-commerce shopping assistant capabilities including product search, cart management, payment processing, and order fulfillment via MCP tools.
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/anshux1/amazon-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server