This server lets an LLM agent shop at Rami Levy (Israeli supermarket) through its real API: search products, manage a shared cart, and reorder from purchase history.
rami_levy_search_products(query, limit?) — search the real catalog for productId, name, price.
rami_levy_add_item(productId, name, price, qty?) — add a product to the cart and sync it to the Rami Levy account; quantities add to existing items.
rami_levy_view_cart() — show the local cart, running total, and checkout URL (not the website's browser cart).
rami_levy_remove_item(productId) — remove one product and re-sync the remaining cart.
rami_levy_clear_cart() — empty the cart locally and on the real account.
rami_levy_reorder_from_history(numOrders?, minOccurrences?) — add frequent past-order items at median quantity/previous price.
rami_levy_suggest_reorder(numOrders?, minOccurrences?) — preview what a reorder would add, read-only.
rami_levy_list_orders(page?) — browse past orders (newest first).
rami_levy_view_order(orderId) — get full order details, including lines usable for re-adding items.
rami_levy_check_status() — verify API connectivity (search + authenticated order history) and report cart size.
All tools return structured results without throwing; cart mutations sync to the live account, handle checkout resets, and report both local and authoritative server totals.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@rami-levy-mcp search for cottage cheese and add the cheapest 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.
An MCP server that lets an LLM agent shop at Rami Levy (an Israeli supermarket chain): search products, manage a cart, and reorder from purchase history — talking to Rami Levy's real API directly.
Rami Levy's site is behind Cloudflare, which blocks requests that don't look
like they're coming from a real Israeli browser. This package makes the
request; getting that request to actually reach Rami Levy's origin without
being challenged is your infrastructure's job — a residential/mobile
proxy, a VPN, a box that's actually in Israel, whatever gets you there. If
rami_levy_check_status reports blocked_by_cloudflare, see the error table
below: recapture first, suspect your egress only if a fresh capture still fails.
Related MCP server: Shufersal MCP Server
Node >= 22.13. The cart store uses Node's built-in node:sqlite — there is
no native addon to compile. Build with:
npm ci && npm run buildThree required, three optional:
Env var | What it is |
| The |
| A separate JWT, sent as the |
| Must match whatever browser the above were captured from |
| The full cookie string. Measured live (2026-09-18) from an Israeli residential IP: neither the orders API ( |
| Store id (default |
| Where the cart's SQLite file lives (default |
Capturing the bundle: log into rami-levy.co.il in a real browser, go to
/he/dashboard/orders, open DevTools → Network, find the request to
www-api.rami-levy.co.il/api/v3/site/orders, right-click it → Copy → Copy as
cURL, and pull Authorization, ecomtoken, and User-Agent out of the
copied headers. That single request carries everything needed — no separate
capture of the catalog search is required. Only add RAMI_LEVY_COOKIE if you
later see blocked_by_cloudflare and need to supply cf_clearance.
These expire. An expired bearer/ecom session shows up as auth_expired.
If you do supply a cookie with cf_clearance, that's a short-lived anti-bot
cookie (hours to a few days) and an expired one most likely shows up as
blocked_by_cloudflare (a challenge page). Either way, repeat the capture
above first.
rami_levy_suggest_reorder(numOrders?, minOccurrences?) — what a reorder
would add, without touching the cart. Same selection as
reorder_from_history, but each candidate carries occurrences, qty
(median) and lastPrice, so the user can be shown why something is
proposed and drop what they don't want before anything is added. Read-only.
rami_levy_list_orders(page?) — one page of past orders, newest first:
orderId, createdAt, supplyAt (delivery slot), status, and total
(what was charged, delivery fee included). The response carries page,
lastPage and totalOrders; a real account runs to 140 orders over 24
pages, 6 per page. Read-only.
rami_levy_view_order(orderId) — one order in full: every line with
productId, name, unit price, qty (decimal for weight-based items)
and lineTotal, plus the order's total, deliveryPrice, status and
slot. A value the order data doesn't carry is null, never 0.
productId is what add_item takes, so a line can be re-added directly —
at the price paid then, not today's. Read-only.
rami_levy_search_products(query, limit?)
rami_levy_add_item(productId, name, price, qty?)
rami_levy_view_cart() — this tool's own list of what it has put in the
cart since the last checkout, not a read of the website cart (see below).
The response carries a scope field saying so.
rami_levy_remove_item(productId)
rami_levy_clear_cart()
rami_levy_reorder_from_history(numOrders?, minOccurrences?) — adds onto
whatever is already in the cart, it does not replace it. A newly reordered
product is priced at the last price paid — the price from the most recent
order line that carried it — which may differ from today's price. view_cart's
total is therefore only an estimate until the cart is synced; serverTotal
(returned by every cart-mutating tool) is the authoritative number. It shares
its selection with suggest_reorder — one implementation, so the preview and
the write can't disagree — and writes to the real account immediately, so
prefer previewing first unless a blind reorder was asked for.
rami_levy_check_status() — probes both the catalog search and page 1 of
the order history (which needs the logged-in session); returns the first
failure, else { ok: true, cartSize }.
Every cart-mutating tool (add_item, remove_item, clear_cart,
reorder_from_history) syncs the whole cart to the real account and returns
cartTotal (local estimate), itemCount, and serverTotal (Rami Levy's own
total from the sync response, null if it gave none). If the sync fails at
the transport level (auth_expired, blocked_by_cloudflare,
network_error), the local cart is rolled back: ok: false means nothing
changed, so retrying is safe. If the response carries
resetAfterOrder: {orderId, createdAt}, the cart was cleared after a checkout
before the change was applied (see below).
Rami Levy stores the last-synced cart server-side, per account. The website
keeps its own copy of the cart in the browser, and merges the server cart
into it only when the checkout page (/he/dashboard/checkout) loads. The
home page's cart icon shows the browser's copy alone, so it won't reflect
anything this server added until the checkout page has been opened once.
Point people at the checkoutUrl that rami_levy_view_cart returns.
(Measured live on 2026-09-18.)
Because the merge runs on page load, a checkout page that was already open
when the cart changed keeps showing the pre-change contents — which reads
like the add silently failed. view_cart returns a checkoutHint field
saying to reload it, and the cart-mutating tools' descriptions say the same,
so the agent volunteers it instead of sending the user to a stale page.
(Hit for real on 2026-09-20: an item added seconds after the checkout page
loaded was absent in the browser and present in the account cart.)
Because that step is a merge, removals don't propagate. If the browser
already holds a product, remove_item or clear_cart deletes it from the
server cart, but the browser's copy brings it back the next time checkout
loads. Adds and quantities from this server always show up.
The server keeps its own cart in SQLite and pushes the whole thing to the account on every change. Rami Levy's API has no endpoint to read the cart back, so the local cart can drift from the real one whenever the cart changes outside this tool:
Checkout. After an order is placed, the site's cart is empty, but the
local cart still holds everything that was bought, and the next sync would
put the whole order back. So before every cart change (add_item,
remove_item, clear_cart, reorder_from_history), if the local cart isn't
empty, the server fetches page 1 of the order history. If any order was
created after the last successful sync, those items were bought: the local
cart is cleared first, then the change is applied, and the response includes
resetAfterOrder: {orderId, createdAt} so the agent can tell the user the
cart started fresh. If the order history can't be fetched, the change is
not made: the tool returns the usual ok: false reason. It never skips the
check. The last-sync time lives in the same SQLite file (a meta table,
added automatically to an existing DB); a cart from before this upgrade
has no sync time, so the check starts working after its first sync.
Edits made on the website. Anything added, removed, or emptied in the
browser is invisible to this server. view_cart shows only what this tool
has put in the cart since the last checkout, and says so in its scope
field.
Timezones: the last-sync time is stored as a UTC instant, and an order's
created_at is resolved to one before they're compared. Live (measured
2026-09-20) that field is zoned ISO-8601 — "2026-09-08T05:59:37.000000Z" —
and is taken at its word. A naive Israel-time string ("2026-09-08 10:15:00",
no offset) is also accepted, and converted with the real Asia/Jerusalem
rules from Intl (UTC+2 in winter, UTC+3 in summer), never a fixed offset.
Every tool responds with { ok: false, reason, ... } instead of throwing.
Reasons and what to do about each:
Reason | When | What to do |
| A JSON response came back 401/403 | Re-capture the token bundle above |
| The response wasn't JSON, at any HTTP status | Recapture the bundle first ( |
| Fetch failed, the body was invalid JSON, the response shape was unexpected (including an order | Check connectivity; if it persists, the API may have changed (see below) |
| The cart sync succeeded but the server dropped some products ( | They were removed from the local cart too; search for alternatives |
|
| Check |
|
| Pass |
| An unexpected exception was caught at the tool boundary | Inspect the |
Search wire format, order response nesting, and the cart sync response were
all verified against the real API on 2026-09-18 with fresh logged-in
captures from an Israeli IP, and match what the client parses. One thing to
know about the cart response: Rami Levy adds its own delivery-fee line to
items server-side (e.g. {id, name: "מחיר משלוח", price, quantity}); this
tool ignores it (it's never matched to a local cart product), and the
top-level price — surfaced as serverTotal — excludes it, so serverTotal
is the product total only, not what checkout will actually charge.
RAMI_LEVY_COOKIE is optional (see above) — leave it unset and the Cookie
header below is just empty, which the real API accepts fine.
curl -s -X POST "https://www.rami-levy.co.il/api/catalog" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RAMI_LEVY_BEARER_TOKEN" \
-H "ecomtoken: $RAMI_LEVY_ECOM_TOKEN" \
-H "Cookie: $RAMI_LEVY_COOKIE" \
-H "User-Agent: $RAMI_LEVY_USER_AGENT" \
-d '{"q":"milk","store":"412"}' | head -c 600It works only if the response echoes "q":"milk" (not "q":null) and
contains product data. A 200 with "q":null means the query was ignored
(the wire format is wrong). An HTML body, at any status, is a Cloudflare
challenge: recapture the bundle and retry before blaming your egress.
skills/rami-levy-shop/SKILL.md carries the workflow the tools deliberately
don't: preview with suggest_reorder before writing, present the candidates
and let the user cut them, then add what survived — plus the cart/website
distinction, the Hebrew-search rule, and what to do about each error reason.
The tools stay mechanism; the skill is policy, so changing how a shop is run
doesn't mean shipping code.
For Claude Code, point a user skill at it:
ln -s "$PWD/skills/rami-levy-shop" ~/.claude/skills/rami-levy-shopA symlink rather than a copy, so git pull updates the skill too.
This ships as an Agent Plugins 1.0.0 plugin
(plugin.json + mcp.json) — copy this directory into a group's
plugins/rami-levy/, fill in the real values for the placeholder env vars
in that group's stored MCP server config, and restart the group.
Add a product to the shared cart. productId, name, and price all come from a prior rami_levy_search_products result — never guessed, and never re-fetched (there is no "get one product" endpoint). If this product is already in the cart, qty is ADDED to what's there, not overwritten. Syncs the whole cart to the real Rami Levy account immediately. Returns cartTotal (local estimate) and serverTotal (Rami Levy's own total — authoritative). ok:false with a transport reason means nothing changed. reason items_rejected means the server refused the listed products; they have been removed from the cart too, so tell the user and pick alternatives. If resetAfterOrder {orderId, createdAt} is present, an order was placed since the last sync, so the items from before it were treated as bought and cleared first; tell the user the cart started fresh after that order.
| Name | Required | Description | Default |
|---|---|---|---|
| qty | No | ||
| name | Yes | ||
| price | Yes | ||
| productId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure and delivers exceptionally: immediate whole-cart sync to the real account, additive qty semantics, rejection behavior (items removed from cart), the ok:false transport meaning 'nothing changed,' and the resetAfterOrder edge case where prior items are cleared as bought. It even tells the agent what to communicate to the user in each failure and reset scenario.
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?
Every sentence earns its place — the transport-vs-items_rejected error modes and resetAfterOrder edge case are dense but necessary given the tool's complexity. However, it is a single unbroken paragraph of roughly 150 words; light structural breaks would improve scannability, though information density is high and no filler exists.
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?
Despite having no annotations and no output schema, the description fully covers input provenance, return values (cartTotal estimate vs authoritative serverTotal), both error modes with prescribed agent actions, and the post-order cart-reset scenario with explicit user-facing instructions. An agent could invoke this tool safely and handle every documented outcome with no additional information.
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 0%, so the description must compensate, and it contributes the most critical semantic: all three required parameters must come verbatim from a prior search result, never guessed or re-fetched. It also explains qty as additive rather than overwriting. It stops short of specifying qty's default value or price's currency/units, leaving the 0%-coverage schema not fully compensated.
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 opening sentence, 'Add a product to the shared cart,' names a specific verb and resource, immediately distinguishing it from siblings like rami_levy_remove_item, rami_levy_clear_cart, and rami_levy_view_cart. The action ('add') and scope ('shared cart') leave no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly binds the tool to an upstream workflow: 'productId, name, and price all come from a prior rami_levy_search_products result — never guessed, and never re-fetched,' and it clarifies the duplicate-product rule (qty is ADDED, not overwritten). However, it never explicitly names sibling alternatives or states when NOT to use this tool, leaving some differentiation to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether the Rami Levy connection is working: probes the catalog search and the (session-authenticated) order history, returning the first failure if either fails, else the current cart size. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it delivers: it explicitly states the operation is read-only, reveals that two subsystems are probed, acknowledges the order history requires a session, and specifies the failure/fallback return behavior. This is unusually transparent for a tool definition.
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 front-loads the purpose and then packs in the probe targets, return semantics, and read-only guarantee. Every clause earns its place with no redundant wording.
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 diagnostic tool, the description is complete: it states what is checked, what the possible outcomes are, and the read-only nature. Without an output schema, the description still conveys the return shape well enough for an agent to invoke and interpret the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema covers 100% of them, so the description need not add parameter detail. The baseline of 4 applies, and the description appropriately focuses on behavior rather than nonexistent inputs.
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 names a specific verb ('Check whether') and a clear resource (the Rami Levy connection), and it details exactly what is probed: catalog search and session-authenticated order history. This distinguishes it from sibling tools like view_cart or add_item, which perform concrete shopping operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use case is clear: verify that the Rami Levy connection is working. It does not explicitly list alternative tools or exclusion conditions, but the health-check framing makes it obvious when this tool is appropriate versus the sibling operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Empty the cart completely, both locally and on the real Rami Levy account. Returns cartTotal (local estimate) and serverTotal (Rami Levy's own total — authoritative). ok:false with a transport reason means nothing changed. reason items_rejected means the server refused the listed products; they have been removed from the cart too, so tell the user and pick alternatives. If resetAfterOrder {orderId, createdAt} is present, an order was placed since the last sync, so the items from before it were treated as bought and cleared first; tell the user the cart started fresh after that order.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral burden. It discloses that both local and server carts are emptied, that transport failures mean nothing changed, that items_rejected removes products and requires user follow-up, and that resetAfterOrder changes the starting cart state.
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 dense but every sentence earns its place: main action, return semantics, failure modes, and the resetAfterOrder edge case. It is front-loaded with the core purpose and avoids repeating schema or annotation information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description must explain return values and edge cases, and it does so thoroughly. It covers what each return field means, what to do when items are rejected, and how to interpret resetAfterOrder, making the tool safely callable.
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 there is nothing for the description to document. The baseline of 4 applies, and the description instead usefully explains the return envelope and outcome semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb and resource: 'Empty the cart completely, both locally and on the real Rami Levy account.' It clearly distinguishes this from siblings like remove_item and view_cart by emphasizing complete cart clearing.
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 tool's scope obvious: use it to empty the entire cart, with detailed handling for ok:false and items_rejected results. It doesn't explicitly name remove_item as the alternative for partial removals, but the context and sibling list make that distinction clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove one product from the cart by productId, then re-syncs the remaining cart to the real account. Returns cartTotal (local estimate) and serverTotal (Rami Levy's own total — authoritative). ok:false with a transport reason means nothing changed. reason items_rejected means the server refused the listed products; they have been removed from the cart too, so tell the user and pick alternatives. If resetAfterOrder {orderId, createdAt} is present, an order was placed since the last sync, so the items from before it were treated as bought and cleared first; tell the user the cart started fresh after that order.
| Name | Required | Description | Default |
|---|---|---|---|
| productId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers thoroughly: it discloses the re-sync side effect, distinguishes local cartTotal from authoritative serverTotal, and explains two distinct failure modes (transport reason vs items_rejected) plus the resetAfterOrder edge case where prior items were treated as bought and cleared. This is exceptional disclosure for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: core action, return totals, transport-failure semantics, items_rejected handling, and the post-order reset state. It is front-loaded with the primary action, though it is a single wall of text that light paragraph breaks would improve.
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, no output schema, and no annotations, the description covers the core action, return fields, error semantics, and an edge-case state. An agent has enough information to invoke it correctly and interpret every plausible result.
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 0% and the only parameter is productId (string, minLength 1). The description states that productId selects the product to remove, which is the essential semantic the bare schema lacks. It does not mention where productId comes from, but for a single string parameter the description is adequately compensating.
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 ('Remove'), resource ('product from the cart'), and selection method ('by productId'), then clarifies the follow-up re-sync to the real account. The single-item scope clearly distinguishes it from siblings like rami_levy_clear_cart or rami_levy_add_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys side effects and post-conditions of removal so an agent understands what happens when it runs, but it never explicitly says when to choose this tool over alternatives (e.g., it does not name clear_cart for bulk removal or view_cart for inspection-first). Usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look at the last numOrders (default 10, max 50) real orders, find items that appear in at least minOccurrences (default 3) of them, and add each at its median past quantity. ADDS onto whatever is already in the cart — it does not replace it. Returns cartTotal (local estimate) and serverTotal (Rami Levy's own total — authoritative). ok:false with a transport reason means nothing changed. reason items_rejected means the server refused the listed products; they have been removed from the cart too, so tell the user and pick alternatives. If resetAfterOrder {orderId, createdAt} is present, an order was placed since the last sync, so the items from before it were treated as bought and cleared first; tell the user the cart started fresh after that order.
| Name | Required | Description | Default |
|---|---|---|---|
| numOrders | No | ||
| minOccurrences | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly: it discloses the add-not-replace behavior, the distinction between local cartTotal and authoritative serverTotal, the 'nothing changed' ok:false case, the items_rejected removal side effect, and the resetAfterOrder scenario. This is excellent behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence carries essential operational information: the algorithm, the critical add-vs-replace distinction, return semantics, error handling, and reset behavior. It is front-loaded with the core action before the caveats.
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 complexity and the absence of annotations or output schema, the description is remarkably complete. It covers parameters, defaults, side effects, return values, error reasons, and post-order state changes. Nothing essential is missing for an agent to call it safely and interpret results.
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 0% description coverage, so the description must compensate. It explains both parameters with defaults (numOrders default 10 max 50, minOccurrences default 3) and their behavioral meaning. No parameter meaning is left unexplained.
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 operation (reorder items from past order history), names the exact algorithm (last numOrders, minOccurrences threshold, median quantity), and explicitly contrasts itself with replacing the cart. This clearly distinguishes it from siblings like add_item or clear_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 gives clear context for when to call it: the user wants items that recur across recent orders. It also clarifies that it adds to the existing cart rather than replacing it, which is important for choosing it over clear_cart or add_item. It does not explicitly name alternatives, but the usage context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Rami Levy's real catalog. Returns productId, name, price for each hit. Call this before rami_levy_add_item — a productId is never invented.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns productId, name, and price, and that it accesses a 'real catalog' (implying authoritative data). However, it doesn't explicitly state that it's read-only or has no side effects, though this is implied by the search nature. It adds useful context without contradicting anything.
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 compact and efficiently organized. It opens with the core action, then lists the return fields, and closes with a crucial usage note. Every sentence adds value without 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 search tool with no output schema, the description provides essential information: what is returned (productId, name, price) and when to use it (before add_item). The missing detail of the 'limit' parameter is a minor gap, but since it's in the schema and optional, it doesn't compromise the overall completeness. The description is sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'limit' parameter at all. The 'query' parameter is obvious from the tool name and description ('Search'), but the description fails to mention that 'limit' constrains the number of results, its range, or its optionality. The description does not compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it searches Rami Levy's real catalog and returns productId, name, and price for each hit. It distinguishes itself from siblings like rami_levy_add_item by explicitly noting that a productId is never invented, making it clear this is the source for valid product IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage guidance: 'Call this before rami_levy_add_item'. This tells the agent when to use this tool, and the phrase 'a productId is never invented' reinforces that this is the only way to obtain a valid productId for adding items. This is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show this tool's own list of what it has put in the cart since the last checkout, with a running total and the checkout URL. This is NOT a read of the Rami Levy website cart: the API has no way to read the cart back, so anything added, removed or emptied on the website is not visible here (see scope). Reads local state only — no network call. Give the user the checkout URL: the Rami Levy site shows these items once its checkout page loads, not on the home-page cart icon.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description fully carries the behavioral burden. It reveals that the tool makes no network call, reads only local state, and cannot see website-side cart mutations. It also clarifies the checkout URL behavior on the Rami Levy site, providing substantial transparency for a stateful cart tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary purpose and then adds crucial caveats and user-facing guidance. Every sentence earns its place: purpose, scope limitation, and checkout URL behavior. There is no filler or redundant 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 no-parameter, no-output-schema tool, this description is unusually complete. It tells the agent what the tool returns, what state it operates on, what it cannot see, and what to communicate to the user. The only minor ambiguity is the reference to 'scope', but this does not undermine practical 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?
There are zero parameters, so the empty input schema fully covers parameter needs. The baseline for 0-parameter tools is 4, and the description adds no unnecessary parameter information while still providing relevant context about the tool's local scope.
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 ('Show'), a precise resource (this tool's own cart list since the last checkout), and the key outputs (running total, checkout URL). It also explicitly distinguishes itself from a read of the Rami Levy website cart, making its purpose unambiguous and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: it reads local state only and is not a website-cart read. It clearly explains the limitation that website-side changes are invisible, but it does not explicitly name alternative tools or say 'use X instead' in this situation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0rami_levy_add_itemrami_levy_check_statusrami_levy_clear_cartrami_levy_remove_itemrami_levy_reorder_from_historyrami_levy_search_productsrami_levy_view_cartScored across 7 tools
Each tool targets a distinct operation: searching, adding, removing, clearing, viewing the local cart, checking connectivity, and reordering from history. The only possible overlap is check_status returning cart size, but it is clearly framed as a health check, not a cart read.
All tools follow a consistent rami_levy_<verb>_<noun> pattern, e.g. search_products, add_item, remove_item, clear_cart. The naming convention is uniform and predictable across the entire set.
Seven tools is well-scoped for a grocery cart integration: search, add, remove, clear, view, status, and reorder each earn their place. There is no redundancy or bloat.
The cart lifecycle is well covered with search, add, remove, clear, local view, and reorder-from-history. Minor gaps like no direct order-history listing and no quantity-update operation are workarounds but do not break core workflows.
Agentic commerce gateway: discovery, search, checkout across Shopify/Woo/Odoo/PrestaShop.
Product search for AI agents: Amazon + Shopify, cart-to-checkout buy path. Pay-per-call, no API key.
AI-powered commerce API for luxury skincare shopping. Enables AI agents to search products, browse collections, manage shopping carts, and generate checkout URLs for the Regenique Elegance Shopify store.
Directory of APIs, merchants, and tools AI agents can actually use.
