Skip to main content
Glama
anshux1

Shopping MCP Server

by anshux1

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_order records 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 mode

  • Live 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://checks

  • Product, cart, and order resources plus the shopping_assistant prompt

  • Product, 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_URL for multi-instance production persistence

Quick start

pnpm install:all
cp .env.example .env
pnpm verify
pnpm dev

pnpm 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

JWT_ALGORITHM / JWT_JWKS_URI

Explicit signing algorithm and Better Auth JWKS endpoint (EdDSA + /api/auth/jwks by default)

JWT_SECRET / JWT_SECRET_PREVIOUS

Current and temporary previous HMAC secrets; required only for HS* verification and at least 32 bytes outside development

JWT_AUDIENCE / JWT_ISSUER

Required JWT claim validation values (amazon-mcp / better-auth in the example)

JWT_EXPIRES_IN / JWT_MAX_TOKEN_LIFETIME_SECONDS

Issuer token lifetime and maximum accepted exp - iat lifetime (default 3600)

JWT_JWKS_CACHE_MAX_AGE_SECONDS

Maximum age of cached public keys before refresh (default 600)

DATABASE_URL

Postgres/Neon connection string; required outside development and takes precedence over file storage

DATABASE_FILE

Single-process local JSON store, or :memory: for tests; not a production fallback

EBAY_APP_ID / EBAY_CERT_ID

eBay keyset for live Browse/Taxonomy calls

EBAY_MARKETPLACE_ID

eBay marketplace, default EBAY_US

EBAY_MOCK

Set true to explicitly enable the deterministic offline catalog

MCP_TRANSPORT_TYPE

stdio, http, or dual; omitted development defaults to stdio, omitted production defaults to http

PORT / HOST

HTTP listener settings; production defaults to 3000 / 0.0.0.0 when omitted

ENABLE_CORS / CORS_ALLOWED_ORIGINS

CORS opt-in and exact comma-separated HTTP(S) origin allowlist; wildcard origins are rejected

SHOPPING_TAX_RATE

Decimal tax rate used in checkout, for example 0.0725

SHOPPING_FULFILLMENT_MODE

Must be set explicitly outside development; only demo is implemented and external refuses to start

SHOPPING_QUOTE_TTL_SECONDS

Checkout quote lifetime, default 600

SHOPPING_FEATURED_ITEM_IDS / SHOPPING_FEATURED_QUERY

Curated item list, or the fixed query used by shopping://featured-products

EBAY_MAX_RETRIES / EBAY_RETRY_BASE_MS

Bounded exponential backoff for transient eBay failures only

EBAY_CATEGORY_MAX_DEPTH / EBAY_CATEGORY_MAX_NODES

Bound a taxonomy response so a full tree cannot overflow a client

EBAY_QUOTA_FALLBACK

reject (default) or local when the shared quota counter is unreachable

TRUSTED_FORWARDED_HOSTS / REQUIRE_HTTPS

Reverse-proxy header policy; an X-Forwarded-Host outside the allowlist is rejected

HEALTH_DETAILS

Include storage mode and applied migrations in /readyz

OAUTH_ENABLED

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

search_products

Public

Search the eBay catalog

get_product

Public

Read current item details

get_categories

Public

Read the marketplace category tree or subtree

add_to_cart

JWT + shopping:write

Add or increment a user cart item

view_cart

JWT + shopping:read

Read the authenticated user cart

update_cart_item

JWT + shopping:write

Set quantity; 0 removes the item

checkout

JWT + shopping:write

Create a ten-minute quote with live price/availability checks

place_order

JWT + shopping:write

Persist an order from an unexpired quote and clear the cart

get_order

JWT + shopping:read

Read one order owned by the authenticated user

order_history

JWT + shopping:read

List the authenticated user’s orders

cancel_order

JWT + shopping:write

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=EdDSA and JWT_JWKS_URI=https://<frontend>/api/auth/jwks (recommended)

  • Or JWT_ALGORITHM=HS256 and JWT_SECRET when the issuer is explicitly configured to mint HMAC tokens

  • JWT_AUDIENCE=amazon-mcp

  • JWT_ISSUER=better-auth

  • JWT_EXPIRES_IN=1h (the issuer controls the actual exp claim)

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:

  1. Generate a new random secret and deploy it as JWT_SECRET.

  2. Move the old value to JWT_SECRET_PREVIOUS in the same deployment.

  3. Keep the previous value for at least the maximum token lifetime (and any clock-skew/rollout buffer).

  4. Remove JWT_SECRET_PREVIOUS in 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_order

Resources and prompt

  • shopping://catalog-guide

  • shopping://featured-products

  • shopping://categories

  • shopping://cart-guide

  • shopping://order-guide

  • shopping://order-statuses

  • metrics://shopping

  • health://checks

  • widget://examples

  • shopping_assistant prompt 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 build

Postgres 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:postgres

Correctness guarantees

  • Cart contents come from the server. add_to_cart accepts only item_id and quantity; 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_cart calls 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_order returns 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_id acts 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_URL the 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 @Cache wraps @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:

  1. Set NODE_ENV=production and explicitly choose MCP_TRANSPORT_TYPE=http (or dual only when stdio is intentionally needed).

  2. Set HOST=0.0.0.0, DATABASE_URL, TLS settings, JWT_SECRET, and live eBay credentials through the secret manager.

  3. Set SHOPPING_FULFILLMENT_MODE=demo explicitly; startup fails without it outside development.

  4. Keep EBAY_MOCK=false for live access and verify health://checks reports the database and eBay as up.

  5. Run pnpm verify, and pnpm verify:live once against the eBay sandbox with real credentials.

  6. Put the HTTP transport behind TLS. Set TRUSTED_FORWARDED_HOSTS to the public host and REQUIRE_HTTPS=true when a proxy terminates TLS. Leave CORS disabled for non-browser clients, or set ENABLE_CORS=true with an exact CORS_ALLOWED_ORIGINS allowlist; wildcard CORS is not supported.

  7. 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 tools
add_to_cartAdd to cartC

Add a product to the authenticated user cart. Never pass a user ID; it comes from the JWT subject.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleNoOptional title snapshot from get_product
item_idYeseBay item ID from get_product
currencyNoOptional ISO currency code
quantityYesNumber of units to add
conditionNoOptional item condition
image_urlNoOptional product image URL
unit_priceNoOptional displayed price snapshot
item_web_urlNoOptional eBay item URL

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
order_idYesOrder ID to cancel

TDQS

A4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
shipping_addressNoOptional address used to calculate the checkout quote

TDQS

A3.9/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
category_idNoCategory ID, or 0 for the complete tree0

TDQS

A4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
order_idYesOrder ID returned by place_order

TDQS

B3.3/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
item_idYeseBay item ID, for example v1|123|0

TDQS

A4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of orders to return
statusNoOptional status filter

TDQS

A3.8/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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

The description uses a specific verb 'List' and resource '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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
checkout_idYesCheckout ID returned by checkout
shipping_addressNoOptional address to save on the order

TDQS

A3.7/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
sortNoOptional eBay sort order
limitNoNumber of products to return
queryYesWords to search for, such as wireless headphones
offsetNoNumber of products to skip
category_idNoOptional eBay category ID

TDQS

B3.1/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
item_idYeseBay item ID already in the cart
quantityYesNew quantity; 0 removes the item

TDQS

A3.7/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents 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.

Purpose5/5

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.

Usage Guidelines3/5

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

The description implies usage context by 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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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

A3.7/5.0
Disambiguation5/5

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.

Naming Consistency3/5

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.

Tool Count5/5

11 tools is well-scoped for a shopping domain, covering discovery, cart, checkout, and order management without unnecessary redundancy or bloat.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo issues

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

Related MCP Servers

Latest Blog Posts

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