This server lets an AI assistant shop the Woolworths New Zealand catalogue and manage a signed-in trolley over MCP.
Search products by keyword, with paging, sorting, department filtering, and optional out-of-stock results.
Batch search multiple queries in one call, grouped by query.
Get product details by SKU: price, description, ingredients, allergens, nutrition, origins, health star rating, and purchasing unit.
Get product label photos to read packaging when ingredient/allergen data is missing.
Browse departments, aisles, and shelves, and list products in any category.
Get specials with was/current pricing, optionally filtered by department.
Find pick-up stores by name or suburb.
Check and set the delivery location, which determines prices and availability.
Check auth status and sign-in instructions; actual sign-in happens via a real browser with npm run login.
Read the trolley, including lines, quantities, and totals.
Set, batch-set, or remove trolley lines, with quantity adjustments handled transparently.
Retrieve past purchases and order history for the signed-in account.
All catalogue tools are read-only and need no account; cart and history tools require the signed-in session. No checkout, payment, or delivery booking is possible.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@woolies-mcp Find free range eggs and add a dozen to my trolley"
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 for shopping the Woolworths New Zealand catalogue: keyword search, product detail, and the delivery location those answers depend on.
The catalogue tools are read-only and need no account. Once signed in it can also read and fill your trolley — but it never places an order, pays, or books a delivery slot.
Authentication is human-driven. A browser window opens and you sign in there, as you would on the website — the server never sees your password and stores no credentials. It keeps only the resulting session, whose cookie Woolworths dates 7 days ahead. See DESIGN.md for the API facts and the rules the server holds to.
This is an unofficial project, not affiliated with Woolworths — please read Unofficial, and what this is not before using it.
Related MCP server: Trader Joe's MCP Server
Tool | What it does |
| Keyword search. Returns products with the |
| Several searches in one call, grouped by query. |
| One product by SKU: ingredients, allergens, nutrition panels, warnings, barcode, and every way it is sold. |
| The product's own image URLs. The site does not say which, if any, shows the label. |
| Where the cart is being delivered, and the account's other saved addresses. |
| The browse tree: one node with its children. Each carries the key |
| Products in a category, by the key |
| What is on special, optionally narrowed to one promotion type. |
| Delivery and pick-up windows with their fee bands. Read-only: no tool books one. |
| Pick-up locations nearest the cart's delivery address, with how far away each is. |
| set_location(addressId) | Moves the cart to another of the account's saved addresses. Books nothing. |
Tool | What it does |
| Whether the account tools work, demonstrated by a real call. Read-only. |
| Reports how to sign in; the server cannot do it unattended (see below). |
| What is in the cart, with the totals and anything blocking checkout. |
| Sets a line to an absolute quantity; 0 removes it. Decimals for |
| Several lines in one call, with a per-item outcome. |
| Removes a product from the cart, whichever pricing it is held under. |
| The site's "Buy it again" list, frequency-ordered. Not the full purchase history. |
| Past or in-flight orders, with their fulfilment slots and totals. |
Sign-in happens in a real browser. Auth0 challenges non-browser clients with a captcha, so
npm run login opens a window, you sign in, and the captured session is handed to the server,
which persists it and reloads it at boot. The session cookie is dated 7 days ahead, which is the
longest it can last rather than a guarantee: signing out elsewhere, a password change or a
security event ends it sooner. auth_status makes real account calls and reports what it
demonstrated, so it cannot claim access the tools do not have.
Woolworths is moving the site from its old REST API to a new GraphQL one. This server has followed it completely: every call it makes is GraphQL. The catalogue still works without an account — the site serves a guest — so search, browse, specials and product detail need no sign-in. Everything about your shop does: the cart, where it goes, the windows offered there, and your history.
An expired session does not make the cart look empty. The new API answers an unauthenticated caller with an empty guest cart at HTTP 200 rather than an error. Every cart call here proves whose cart it is on the same request, so an empty cart these tools report is genuinely empty.
No checkout, ever. There is no tool for placing an order, paying, or booking a delivery slot, and the upstream endpoints for those are deliberately left unbound. A person reviews the cart and places the order on the website.
Quantities can change on the way in. Woolworths rounds weight-priced products up to a whole number of items, so 0.3 kg of loose bananas becomes 0.5 kg. Cart writes return
requestedQuantityandappliedQuantityseparately and setadjustedwith an explanation when they differ. Report what was applied, never what was asked for.
npm run smoke:account runs the cart sequence and restores the cart; npm run check:login
checks the sign-in chain without credentials; npm run check:adjustment and
npm run check:graphql-cart check the quantity-adjustment wording and the GraphQL cart contract
offline.
Node 20 or newer. The catalogue tools need no account; the cart tools need npm run login.
npm install
npm run build
npm start # stdio; speaks JSON-RPC on stdout, logs on stderrnpm run check runs typecheck, lint, format check and build — the pre-push command. npm run lint:fix and npm run format apply what is fixable. CI runs the same four on Node 20 and 22.
npm run smoke exercises the live API end to end against its own anonymous session, throttled to
one request per second, and prints a pass/fail line per check. npm run typecheck covers src
and scripts.
From anywhere, after npm install && npm run build in this directory:
claude mcp add woolies --scope user -- node /absolute/path/to/woolies-mcp/dist/index.jsDrop --scope user to register it for the current project only. Check it with
claude mcp list, and remove it with claude mcp remove woolies.
The tools alone leave the caller to work out the order of operations. skills/woolies/ is an
Agent Skill that supplies it: check the delivery location before
quoting prices, resolve each list item, batch the cart write, and report ambiguous picks
instead of choosing silently. Worth adding once the server is connected.
ln -s "$PWD/skills/woolies" ~/.claude/skills/woolies # Claude CodeCopy it instead of symlinking if you want to tailor it — pointing it at wherever you keep your shopping lists and preferences is the main thing worth changing. For claude.ai, upload it in the skills settings; its frontmatter is limited to the Agent Skills spec so it uploads unchanged.
Then ask for the shopping in the normal way, or invoke it directly with /woolies.
Two entry points share one createServer:
Entry | Command | Used for |
stdio |
| local use, launched by an MCP client |
Streamable HTTP |
| remote use over HTTP |
node dist/http.js serves the same tools over Streamable HTTP, which is what a hosted MCP client
connects to. Any host that runs Node or Docker will do; the sections below describe one
arrangement, and none of it is required for local stdio use.
The HTTP transport serves MCP only at /mcp/$MCP_PATH_TOKEN. /healthz returns a version
string with no secrets, and every other path returns 404 with an empty body. The token is an
unguessable path, not authentication. It guards a session that can read and fill the signed-in
trolley, so treat the token as a credential.
Copy .env.example to .env and fill it in. Generate the token with openssl rand -hex 24.
docker-compose.yml builds the image, reads .env, and binds to 127.0.0.1:8480 — a reverse
proxy or tunnel is expected to publish it, not the port itself. Create data/ next to the compose
file and chown 1000:1000 it: the container runs as the unprivileged node user and stores the
signed-in session there.
docker compose up -dOne convenience path, not a requirement — any host that runs docker compose works, by whatever
means you already use.
Prerequisites:
DSM 7 with Container Manager installed, which provides docker and compose v2.
SSH enabled, and an ssh alias with key auth for a user with passwordless sudo. Docker needs sudo on DSM.
The deploy directory created on the NAS, containing a data/ subdirectory owned by 1000:1000.
The container runs as the unprivileged node user and stores the signed-in session there.
For Funnel only: the Tailscale package sideloaded from pkgs.tailscale.com — the Package Center build lags badly — with HTTPS certificates and Funnel enabled for the tailnet.
Set DEPLOY_SSH_HOST to the ssh alias and DEPLOY_REMOTE_DIR to the deploy directory, then:
npm run deploy # or: npm run deploy -- my-nasIt ships HEAD as a tarball over SSH rather than using scp, because DSM disables SFTP and this way
the NAS needs no git credentials. It copies .env only when the NAS has none, builds the image
there, and waits for /healthz. It refuses to run with a dirty tree, since HEAD is what ships.
Non-login SSH on DSM has a minimal PATH, so docker is called by absolute path with sudo;
DEPLOY_DOCKER_PATH overrides that for other hosts.
A hosted MCP client calls the endpoint from the internet, so a LAN address will not do. Funnel gives the host a public HTTPS URL with no open ports, no domain and no certificates:
tailscale funnel --bg 8480Enable HTTPS certificates and Funnel once for the tailnet in the Tailscale admin console; the
first funnel run prints an approval link if the policy has not been set. The resulting hostname
is <node>.<tailnet>.ts.net — put it in PUBLIC_BASE_URL.
Whole-port Funnel is safe here because the app serves MCP only at /mcp/$MCP_PATH_TOKEN and 404s
everything else. Anything else that reaches port 8480 gets nothing.
Verify from outside:
npm run check:http <public-base-url> <token>Then sign in once, which the cart tools need:
npm run login -- --server <public-base-url>/mcp/<token>Substitute the PUBLIC_BASE_URL and MCP_PATH_TOKEN values from your .env; these commands do
not read it for you.
One session, one request per second, a single retry with backoff, and an automatic re-bootstrap
when the edge rejects the session. This is one shopper's traffic and must stay that way; the
throttle lives in WoolworthsClient so no tool can route around it.
src/
index.ts stdio entry point
http.ts Streamable HTTP entry point
server.ts tool registration, transport-agnostic
config.ts environment parsed once, at startup
session-store.ts the signed-in session on disk, shared by both entry points
tools/ MCP adapters: argument schemas, descriptions, JSON responses
woolworths/
session.ts cookie jar, browser headers, bootstrap
graphql-client.ts the client, the session upgrade, and errors as exceptions
graphql-documents.ts the operations sent, and the variant-key encoding
graphql-cart.ts every operation, with the guest-cart and wrong-cart guards
auth.ts sign-in state; the handover itself is scripts/login.ts
schemas.ts zod schemas for the site's payloads
mappers.ts raw JSON to the compact shapes a client sees
api.ts the Woolworths operations, in domain terms
scripts/
login.ts browser sign-in handover
smoke.ts live catalogue check
account-smoke.ts live cart check, signed in
browser-fetch.ts a fetch backed by a real browser's cookies, for the sign-in probes
cart-fixtures.ts canned GraphQL carts, so the offline checks stay offline
deploy.ts ship, build and start on a remote hostThis repository plus one git-ignored .env recreates the deployment. The only state worth
keeping is the signed-in session under /data; losing it costs one npm run login.
For the local stdio server: git clone, npm install, npm run build, and register it with your
client (the claude mcp add line above, for Claude Code).
To rebuild the NAS deployment from nothing:
git clone this repository on the machine you deploy from.
cp .env.example .env and paste MCP_PATH_TOKEN back from your password manager. Reusing the
same token keeps the existing connector URL working; a new one changes the URL and every client
must be updated.
On the NAS, create the deploy directory's data/ and chown 1000:1000 it — the
container runs as the unprivileged node user and stores the session there.
npm run deploy — ships HEAD to DEPLOY_REMOTE_DIR, builds, starts, waits for health.
sudo /var/packages/Tailscale/target/bin/tailscale funnel --bg 8480 on the NAS, if the serve
config was lost too.
npm run check:http <public-base-url> <token>.
npm run login -- --server <public-base-url>/mcp/<token> to sign in again.
Keep copies of every secret in your password manager; none belongs in this repository.
Not affiliated with, endorsed by, or connected to Woolworths New Zealand or Woolworths Group. All trademarks belong to them.
It automates one person's own account for their own household shopping: the same actions a shopper takes in the browser, at a shopper's volume. It is not a scraper, a price-harvesting tool, or a data-collection service, and the code is built so it cannot drift into being one — a single shared session, roughly one request per second enforced in the HTTP client where no tool can bypass it, no bulk crawling, and no redistribution of catalogue or price data. Results are fetched on demand for the person asking and are not stored or republished.
It intentionally cannot place orders, pay, or book delivery slots. Those endpoints exist upstream and are deliberately left unbound. Filling a trolley is as far as it goes; a person opens the website to check out.
The project and its author collect nothing. There is no telemetry and no phoning home. Your
session cookies, .env and any personal data stay in your own deployment, on your own machine.
You are responsible for complying with Woolworths' Terms of Service — read them and decide for yourself whether this use fits. It drives the website's own internal API, which carries no compatibility promise and can change without notice; the schemas are strict so an upstream change surfaces as an error rather than as wrong data. Use at your own risk. Provided as-is, with no warranty of any kind.
MIT licensed.
Report whether this session is signed in to a Woolworths account, and whether signing in is possible at all. The catalogue tools work signed out and are unaffected; the cart and purchase-history tools need a signed-in session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a read-only operation, and the description adds useful behavioral context beyond that: it clarifies that catalogue tools are unaffected by auth state and that cart/purchase-history tools depend on it. It also discloses that the tool reports whether sign-in is possible at all, not just current status.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose, followed by a relevant scoping note about which tool families are affected. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless status tool, the description fully covers what the call reports and why it matters. Since there is no output schema, the wording 'Report whether...' adequately implies a boolean or status-style response, and nothing needed to invoke the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is vacuously 100%, so the description does not need to explain parameter meaning. It still contributes by framing the no-input call as a session-level status check.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Report') and names the exact resource being queried: whether this session is signed in to a Woolworths account and whether sign-in is possible. This clearly differentiates it from the sibling sign_in tool, which performs the action rather than reporting status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context by explaining that catalogue tools work signed out while cart and purchase-history tools need a signed-in session, which implies when auth_status is useful. It does not explicitly state 'use this before cart tools' or name exclusions, but the context is strong enough for an agent to infer the right moment to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the products in a department, aisle or shelf, using the slugs from list_categories. A narrower level needs the wider ones too. Returns one page: read coverage before answering anything about the cheapest, the best, or whether something exists, and page until a page comes back short if you need the full set. Prices and availability are per delivery location; call get_location to see the current one and set_location to change it.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page of results; 40 per page. | |
| sort | No | Result order. CUPAsc uses the site's raw cup price, whose measure varies per product ($/L, $/100g, $/1ea), so it ranks meaningfully only within one category and is absent for many products. | Relevance |
| aisle | No | Aisle slug within the department, e.g. 'wine'. | |
| shelf | No | Shelf slug within the aisle, e.g. 'rose-wine'. | |
| department | Yes | Department slug, e.g. 'beer-wine'. Required. | |
| includeOutOfStock | No | Include products that cannot be bought at the current location. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description explains single-page returns, the need to read 'coverage' before making existence or best/cheapest claims, and the pagination termination rule. It also discloses location-dependent prices and availability, which is valuable behavioral context not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four compact, front-loaded sentences carry the purpose first, then essential operational caveats. Every sentence adds information needed for correct invocation, with no filler or repetition of schema content.
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?
With no output schema, the description explains the most important output-related behaviors: one page at a time, a coverage field, and how to detect the final page. It could say more about the exact product fields returned, but the operational guidance is sufficient for the main use cases described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the dependency between department, aisle, and shelf slugs, and by tying prices/availability to the current delivery location. It does not need to restate the schema's already detailed parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List the products in a department, aisle or shelf', and further clarifies that slugs come from list_categories. This cleanly distinguishes browse_category from search_products and get_product without opening any schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit guidance on when to use the tool: after list_categories, with the caveat that narrower levels require wider slugs. It also points to get_location/set_location for location-dependent pricing. It does not explicitly state when to prefer search_products over browse_category, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Woolworths New Zealand pick-up locations, filtered by a name or address fragment. Read coverage: an unfiltered call returns only a sample, so do not conclude a town has no store without searching for it. Each store appears once, with every region it is listed under in areas. These are collection points; the delivery location that sets prices is separate and is managed with get_location and set_location.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Store or suburb name fragment, e.g. 'Ponsonby'. Omit to sample the first 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint and openWorldHint, and the description adds valuable behavioral detail beyond them: unfiltered results are only a sample, each store appears once, and the 'areas' field contains every region under which the store is listed. It also clarifies the relationship to the delivery-location concept, which the annotations do not cover.
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 front-loaded with the core purpose, then adds the critical sampling caveat and the distinction from the delivery-location tool. Every sentence conveys necessary operational context with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter, the description covers everything needed to invoke it correctly: what it lists, how filtering works, the sample behavior, the uniqueness of stores, the 'areas' field, and the separation from delivery-location tools. No output schema exists, but the description provides enough field context ('areas') and behavioral expectations for the agent.
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 input schema already documents the only parameter, 'query', with meaning and an example. The description adds 'name or address fragment' but this largely restates the schema description. With 100% schema coverage, the description does not need to compensate, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a specific resource ('Woolworths New Zealand pick-up locations'), and the filtering behavior ('by a name or address fragment'). It also explicitly distinguishes these collection points from the separate delivery-location tool, making its purpose unmistakable.
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 concrete usage guidance: an unfiltered call returns only a sample, so the agent must search before concluding a store does not exist. It also names the alternative tools for the delivery location ('get_location and set_location') and explains why they are separate, effectively telling the agent when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the trolley. Returns lines (one per distinct product), lineCount (how many distinct products), totalQuantity (the quantities summed, so 19 lines can be 23 items), and totals with the money as the site formats it: subtotal, savings, deliveryFees, bagFees and totalIncludingDeliveryFees. Needs a signed-in session; run npm run login where the server runs, or call sign_in for the details.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details the response shape (`lines`, `lineCount`, `totalQuantity`, `totals`) and explains aggregation semantics with a concrete example of 19 lines summing to 23 items. It also discloses the authentication requirement, complementing the readOnlyHint annotation without contradicting it.
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 contributes: purpose, return payload semantics, and the session prerequisite. It is compact, front-loaded, and free of filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with no output schema, the description fully compensates by enumerating the return fields and their meaning, plus the login prerequisite. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the empty schema fully covers this dimension. With zero parameters, the baseline is 4; there is nothing more the description could add about parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List the trolley,' a specific verb and resource, and then elaborates on the exact returned fields. It is unmistakably about reading the current cart, separate from product search or cart mutation siblings.
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 clearly states the key precondition for use: a signed-in session, with concrete instructions to run `npm run login` or call sign_in. It does not explicitly name alternative tools, but the purpose and prerequisite strongly frame when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the delivery location this session is shopping from: suburb, fulfilment method and store id. Every price and availability answer from the other tools is for this location, so check it before trusting a result.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description does not contradict them. It adds useful behavioral context by explaining that the returned location affects every other tool's results and enumerating the returned fields, which goes beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The main purpose is front-loaded, and the second sentence earns its place by telling the agent when the result matters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with a simple return concept, the description is complete. It names the exact return components and explains how the output should be used in the larger workflow, with no output schema required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully covers parameter semantics and the baseline is 4. The description adds no param details, but none are needed; it instead clarifies what the response will contain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Report' and names the exact resource: the delivery location for the current session, including suburb, fulfilment method, and store id. It clearly separates this from sibling tools like set_location by characterizing it as the source of truth for all other pricing and availability tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance on when to call this tool: before trusting any price or availability result, since all other answers are scoped to this location. It does not explicitly mention when not to use it or name alternatives such as set_location, so it falls just short of the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the account's past orders with their references, dates, fulfilment slots, statuses and totals. Read coverage: the site returns only its default recent window, so an order's absence is not evidence it was never placed. Needs a signed-in session; run npm run login where the server runs, or call sign_in for the details.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses a key behavioral trait: the site returns only its default recent window, so an order's absence is not evidence it was never placed. It also states the authentication prerequisite, which is not covered by readOnlyHint or openWorldHint.
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 short, front-loaded with the main purpose, and every sentence earns its place: the listing statement, the coverage caveat, and the authentication instruction. There is no redundancy or filler.
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 parameterless, read-only, open-world tool, the description is complete: it specifies the returned data fields, warns about incomplete data, and provides the auth prerequisite. No output schema exists, but the field list adequately covers return expectations.
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 explain beyond what the schema shows. The baseline of 4 for a parameterless tool is appropriate, and no additional parameter detail is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('the account's past orders') and enumerates the returned fields: references, dates, fulfilment slots, statuses and totals. It is clear but does not explicitly distinguish it from the sibling get_past_purchases, so an agent must infer the difference from context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: it requires a signed-in session and tells the agent how to achieve that (run npm run login or call sign_in). It also warns about the default recent window caveat, but it does not explicitly state when to prefer this over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the site's previously-purchased sections, kept separate and labelled. ONLY the section with isPurchaseHistory true reflects what this shopper actually bought; the other section is retailer advertising and must never be described as their purchases, habits or preferences. Read each section's coverage before concluding anything about what the shopper does or does not buy. Needs a signed-in session; run npm run login where the server runs, or call sign_in for the details.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and openWorld annotations, the description discloses a critical behavioral trap: one section is retailer advertising and must never be described as the shopper's purchases, habits, or preferences. It also instructs the agent to read each section's coverage before drawing conclusions, which is highly valuable non-obvious behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler: the purpose is front-loaded, followed by the essential data-integrity warning, and finally the actionable auth prerequisite. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with no output schema, the description covers how to authenticate, what the returned sections mean, which section reflects real purchases, and how to use coverage before drawing conclusions. Nothing essential is missing for correct invocation and interpretation.
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 100% schema description coverage, so the input schema already covers everything. The description's references to isPurchaseHistory and coverage are output semantics, not parameter semantics, and there is nothing more the description needs to add here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: it returns the site's previously-purchased sections and immediately clarifies that these are separated and labelled. The isPurchaseHistory caveat distinguishes this tool from a plain order-history lookup and from siblings like get_order_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the prerequisite of a signed-in session and gives actionable auth steps. It also explains how to interpret the returned sections correctly. However, it does not explicitly name alternative sibling tools or state when this tool should not be used, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one product by SKU, with its price, size, unit price (a formatted string whose measure varies per product, and absent for many), availability, category breadcrumb, description, ingredients, allergens, claims, nutrition, origins and health star rating. purchasingUnit ('Each' or 'Kg') is what the cart tools need for pricingUnit, and canBuyByWeight says whether 'Kg' with a decimal quantity is allowed. IMPORTANT: allergens and ingredients are often not published. When either reports status 'notStated' that means Woolworths said nothing, NOT that the product is free of allergens — products whose own ingredients are milk come back with allergens empty. Never present 'notStated' as an allergy assurance; use get_product_label to read the packaging, and say the data is unavailable. Prices and availability are per delivery location; call get_location to see the current one and set_location to change it.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | Yes | Woolworths product SKU, e.g. '462559'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite readOnlyHint and openWorldHint annotations, the description adds substantial behavioral context: allergens/ingredients are often not published, 'notStated' means absence of data rather than safety, 'purchasingUnit' maps to cart tool requirements, and prices are per delivery location. These details materially change how an agent should use the result and are not available from annotations or schema.
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 operational value: the first sentence names the resource and payload, and the following sentences address the non-obvious caveats that an agent must know before presenting results. It is well-structured, front-loaded with the core purpose, and contains no filler.
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?
With no output schema, the description carries the full burden of explaining what the agent can expect. It lists the returned fields and clarifies the ambiguous ones: unit_price may be absent, purchasingUnit and canBuyByWeight affect downstream cart behavior, allergen/ingredient statuses require careful interpretation, and location affects price/availability. This is sufficient context for correct invocation and interpretation.
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 input schema is fully covered at 100% and already documents the single 'sku' parameter with an example. The description's mention of 'by SKU' reinforces this but adds no additional parameter-specific semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource — 'Fetch one product by SKU' — and enumerates the exact data fields returned. This clearly distinguishes get_product from search-oriented siblings like search_products and from get_product_label, which is mentioned as a packaging-reading alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing guidance: use get_product_label when packaging-level allergen information is needed, and use get_location/set_location because prices and availability are location-dependent. It also warns against treating 'notStated' as allergy assurance, which functions as a clear when-not-to-interpret instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the product's packaging photo as an image, for reading details the API does not publish — most importantly ingredients and allergens, which are frequently absent from get_product. Call this when get_product reports allergens or ingredients as 'notStated' and the answer matters. Images are token-expensive, so request them one product at a time and only when needed. A photo may still not show the panel, and reading a label from a photo is not a substitute for the physical packaging for allergy decisions.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | Yes | Woolworths product SKU. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish readOnlyHint and openWorldHint, so the description adds non-obvious behavioral context: images are token-expensive, the photo may not show the panel, and label reading is not a substitute for physical packaging. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the purpose and trigger condition, followed by cost and reliability caveats. Every sentence earns its place; nothing is redundant or filler.
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 one-parameter read-only tool, the description covers what it returns, why to use it, when to call it, and important limitations. It does not specify the exact image response format, but the description's clarity is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter 'sku' is already fully described in the schema with 100% coverage, so the description does not need to repeat parameter details. It adds usage context around ordering one product at a time but no additional parameter semantics, matching the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return') and resource ('product's packaging photo'), and explains its purpose: to surface details the API does not publish, especially ingredients and allergens. This clearly differentiates it from get_product and other siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger condition: call when get_product reports allergens or ingredients as 'notStated' and the answer matters. It also provides cost-driven usage constraints (one product at a time, only when needed) and a caution that photos may not be sufficient for allergy decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List products currently on special, optionally narrowed to one department. Each product carries wasPrice alongside the current price. Returns one page: read coverage before claiming anything is the best or only special available. Prices and availability are per delivery location; call get_location to see the current one and set_location to change it.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page of results; 40 per page. | |
| sort | No | Result order. CUPAsc uses the site's raw cup price, whose measure varies per product ($/L, $/100g, $/1ea), so it ranks meaningfully only within one category and is absent for many products. | Relevance |
| department | No | Department slug from list_categories, e.g. 'meat-poultry'. | |
| includeOutOfStock | No | Include products that cannot be bought at the current location. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description builds on them rather than repeating them: it discloses pagination ('Returns one page'), the wasPrice return field, and the open-world caveat in actionable form ('read coverage before claiming anything is the best or only special available'). It also surfaces the non-obvious location-dependence of prices and availability. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, roughly 60 words, every one earning its place: purpose first, then return shape, pagination caveat, and location dependency. The most important operational traps (coverage, location) are stated explicitly with no filler and no repetition of schema content.
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 moderate-complexity tool with no output schema, the description covers the risky behaviors: single-page results, the coverage field, per-location pricing, and the wasPrice field, while the schema handles the sort and page quirks. It slightly underspecifies what coverage actually contains (e.g., total specials count), but nothing critical is left to guesswork.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (page, sort, department, includeOutOfStock) already carry descriptions, including a thorough note on the CUPAsc quirk. The description adds only the department-narrowing mention ('optionally narrowed to one department'), so it sits at the baseline 3 without needing to compensate.
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 states a specific verb and resource ('List products currently on special') plus the optional narrowing condition (department). The scope — current specials rather than general product search — distinguishes it from siblings like search_products, browse_category, and get_product from the first clause.
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: use this when you need current specials, optionally per department, and it warns that results are location-scoped, advising get_location/set_location as prerequisites. It stops short of explicitly naming alternatives (search_products, browse_category) and stating when to prefer them, so it misses the top of the scale.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The browse tree. With no argument, lists the 13 departments and their slugs. With a department slug, lists that department's aisles and shelves. Use the slugs it returns as the arguments to browse_category.
| Name | Required | Description | Default |
|---|---|---|---|
| department | No | Department slug, e.g. 'beer-wine'. Omit to list the departments. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and open-world behavior, so the safety profile is established. The description adds meaningful behavioral detail: the tool is hierarchical, has exactly 13 departments at the top level, and switches output granularity based on the presence of the department argument. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each with a distinct purpose: orient the user, describe the no-argument behavior, describe the slug behavior, and explain how to use the output. There is no redundancy or filler, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must explain the return shape, and it does: departments and slugs at the top level, aisles and shelves at the department level. It also provides the natural next step (browse_category). For a simple read-only tool with one optional parameter, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the optional department parameter, so the baseline is 3. The description adds the key semantic that providing a slug changes the result to that department's aisles and shelves, which is not explicit in the schema description. This lifts it to 4.
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 the tool lists the Woolworths browse tree: with no argument it returns 13 departments with slugs, and with a department slug it returns aisles and shelves. This is a specific verb and resource, and the pointer to browse_category distinguishes it from that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly explains both invocation modes: omit the argument for top-level departments, or pass a department slug to get its aisles and shelves. It also tells the user to feed the returned slugs into browse_category. It does not explicitly name alternatives or state when not to use the tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a line from the trolley entirely, the same as setting its quantity to 0. No pricing unit is needed: a removal has none. Needs a signed-in session; run npm run login where the server runs, or call sign_in for the details.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | Yes | SKU of the line to remove. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool destructive and idempotent; the description adds the signed-in session requirement and explains that a removal requires no pricing unit. This meaningfully supplements the structured metadata without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each adding distinct value: the operation and its effect, the pricing-unit exception, and the authentication prerequisite. Information is front-loaded and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter mutation with annotations covering idempotence and destructiveness, the description covers the operation, its effect, authentication, and a special condition for invocation. It does not mention the response or error cases, but the absence of an output schema and the low complexity make this a minor gap.
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 already documents sku with 100% coverage, so the baseline is 3. The description adds useful context by clarifying that the SKU identifies the line to remove and that no pricing unit is needed, which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Remove a line from the trolley entirely,' and clarifies the exact effect by comparing it to setting quantity to 0. This also distinguishes it from sibling tools like set_cart_quantity.
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 statement 'the same as setting its quantity to 0' plus 'No pricing unit is needed' gives clear context for when this tool is appropriate versus a quantity-setting alternative. It does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Woolworths New Zealand catalogue by keyword. Returns products for this page, matchesAvailable for the whole query, and a coverage sentence saying whether this is everything — read it before answering cheapest/only/none questions. Extra query words are ANDed, including sizes, and the site's ranking pads pages with loosely related products, so check each name. unitPrice is a formatted string whose measure varies per product and is absent for many, so compare it only within a category. Prices and availability are per delivery location; call get_location to see the current one and set_location to change it.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page of results; 40 products per page. | |
| sort | No | Result order. CUPAsc uses the site's raw cup price, whose measure varies per product ($/L, $/100g, $/1ea), so it ranks meaningfully only within one category and is absent for many products. | Relevance |
| query | Yes | Search keywords, e.g. 'rose wine' or 'oat milk'. | |
| department | No | Department slug to keep only products from, e.g. 'fruit-veg'. Applied to the fetched page after the search runs, because the site's search does not accept a category filter; the coverage sentence says how much was actually examined. | |
| includeOutOfStock | No | Include products that cannot be bought at the current location. Off by default: an unbuyable product is not a useful answer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true, but the description adds substantial non-obvious behavior: the exact return fields, coverage semantics, ANDing of query words, ranking padding, unitPrice formatting and absence, and per-location prices. This goes well beyond what annotations or schema convey, with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is five dense sentences, each earning its place: purpose, return values, query ANDing and ranking caveat, unitPrice caveat, and location dependence. It is front-loaded with the core function and return shape, followed by high-value warnings. No filler.
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?
With no output schema, the description compensates by naming the return fields and explaining the coverage sentence, which is essential for correct reasoning. It also covers ranking padding, unitPrice comparability, and location context. An agent has what it needs to avoid common wrong answers when searching the catalogue.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents each parameter's purpose, including the department filter's post-search application and CUPAsc's unit caveat. The description reinforces unitPrice-related output caveats but adds little parameter-level meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Search the Woolworths New Zealand catalogue by keyword.' This clearly identifies what the tool does. It does not explicitly differentiate from the sibling search_products_batch, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool, especially the instruction to read the coverage sentence before answering cheapest/only/none questions and to call get_location/set_location for location-dependent prices. It does not mention search_products_batch as an alternative for batch or multi-query use, so it misses an explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run several catalogue searches in one call and get the results grouped by query, so finding many products costs one round trip. Every group carries its own coverage sentence and the same caveats as search_products: the ranking pads results, extra query words are ANDed, and a truncated group cannot answer cheapest/only/none questions. Prices and availability are per delivery location; call get_location to see the current one and set_location to change it.
| Name | Required | Description | Default |
|---|---|---|---|
| queries | Yes | The searches to run, e.g. ['paneer', 'limes', 'oat milk']. | |
| department | No | Restrict every query to this department slug. | |
| resultsPerQuery | No | How many top candidates to return per query. | |
| includeOutOfStock | No | Include unbuyable products. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and openWorld annotations, the description discloses substantive behavior: ranking pads results, extra query words are ANDed, truncated groups cannot answer cheapest/only/none questions, and prices/availability depend on delivery location, with pointers to get_location and set_location. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: main purpose first, then per-group behavior and caveats, then location context. There is no filler or repetition of schema details.
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?
With no output schema, the description still tells the agent results are grouped by query and that each group carries its own coverage sentence. It also covers ranking, truncation, AND semantics, and location dependence, making the tool safely callable without missing critical context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining how queries are interpreted (extra words ANDed) and that truncated results affect question-answering, which enriches the queries and resultsPerQuery parameters beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Run several catalogue searches in one call and get the results grouped by query.' This clearly distinguishes the tool from the single-query search_products sibling and matches the title's promise of searching several things at once.
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 first sentence states the batching rationale — 'so finding many products costs one round trip' — making it clear the tool is for multiple searches. It references search_products for caveats but does not explicitly say 'use search_products for a single query,' so the guidance is strong but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set many products' trolley lines in one call. Quantity is absolute, not a delta: the value you pass becomes the line's new quantity, and 0 removes the line. For pricingUnit, use the product's purchasingUnit field from search_products or get_product verbatim — it is 'Each' or 'Kg'. Only pass 'Kg' with a decimal quantity when the product's canBuyByWeight is true; sending 'Kg' for a counted item orders a kilogram of it. Each item is reported separately as written or failed with a reason; one failure never removes an item from the results, so check every entry. Written entries carry requestedQuantity and appliedQuantity: where adjusted is true the site substituted its own quantity and adjustment says how, so summarise what was actually added. Needs a signed-in session; run npm run login where the server runs, or call sign_in for the details.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | The lines to set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing that quantity is absolute and 0 removes the line, that results report each item as written or failed, that a failure never drops items from results, and how `adjusted` and `adjustment` fields work. It also warns about the `Kg`/`canBuyByWeight` edge case, which is exactly the behavioral nuance an agent needs.
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 main purpose is front-loaded, then the most important quantity semantics, pricing unit constraints, result handling, adjustment behavior, and auth prerequisite. It is dense but not bloated, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description compensates by explaining the per-item result shape, failure semantics, adjustment fields, and auth requirement. It covers enough edge cases that an agent can safely call this mutation tool without further lookups.
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?
Even though the schema already documents `sku`, `quantity`, and `pricingUnit`, the description adds crucial semantics beyond it: absolute-not-delta behavior, 0-removes semantics, using `purchasingUnit` verbatim, and the 'Kg' only-valid-with-`canBuyByWeight` rule. This materially improves correct invocation.
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 and resource: 'Set many products' trolley lines in one call.' It clearly differentiates from the singular sibling set_cart_quantity by emphasizing batch operation, and the title reinforces 'several trolley lines at once.'
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?
Clearly implies this is for setting multiple cart lines in one call rather than one at a time, and gives important prerequisites like needing a signed-in session and running `npm run login`. It does not explicitly name sibling alternatives or state when not to use it, so it falls just short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set one product's trolley line to an exact quantity, adding it if absent. Quantity is absolute, not a delta: the value you pass becomes the line's new quantity, and 0 removes the line. For pricingUnit, use the product's purchasingUnit field from search_products or get_product verbatim — it is 'Each' or 'Kg'. Only pass 'Kg' with a decimal quantity when the product's canBuyByWeight is true; sending 'Kg' for a counted item orders a kilogram of it. Returns requestedQuantity and appliedQuantity separately, because Woolworths silently substitutes its own quantity for some products (0.3 Kg of loose bananas becomes 0.5 Kg). When adjusted is true, adjustment says what the site did instead — report the applied amount to the shopper, never the requested one. Also returns trolleyTotalQuantity (quantities summed across the whole trolley, not a line count). To change several products, use set_cart_quantities instead. Needs a signed-in session; run npm run login where the server runs, or call sign_in for the details.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | Yes | Woolworths product SKU, from search_products. | |
| quantity | Yes | The line's new absolute quantity. 0 removes it. Decimals only for Kg. | |
| pricingUnit | No | 'Each' for counted items, 'Kg' for items priced by weight. | Each |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (idempotentHint=true, destructiveHint=false), the description discloses subtle behavior: quantity is absolute not a delta, 0 removes the line, Woolworths may silently substitute quantity and report it via adjusted/adjustment, and trolleyTotalQuantity is a sum across the whole trolley. This is rich behavioral context that genuinely helps an agent anticipate non-obvious outcomes.
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 long but every sentence carries substantive information: core behavior, parameter rules, return-value nuance, alternative tool, and auth requirement. It fronts the main behavior and then layers detail logically, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explains the important return fields (requestedQuantity, appliedQuantity, adjusted, adjustment, trolleyTotalQuantity) and what they mean. It covers auth, the source of pricingUnit, a caveat about weight purchases, and the sibling tool for multiple updates, making the tool fully usable by an agent.
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 already covers the parameters at 100%, which sets a baseline of 3. The description adds valuable semantics beyond the schema: sourcing pricingUnit from the product's purchasingUnit field, requiring canBuyByWeight for decimal 'Kg' quantities, and warning that 'Kg' for a counted item orders a kilogram. This clearly exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific action 'Set one product's trolley line to an exact quantity, adding it if absent,' clearly indicating the verb and resource. It also differentiates itself from the sibling set_cart_quantities by noting it handles one line rather than several.
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 explicitly says 'To change several products, use set_cart_quantities instead,' giving a direct alternative and selection criterion. It also states the auth prerequisite — 'Needs a signed-in session; run npm run login...' — and provides detailed usage rules for pricingUnit and canBuyByWeight.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Switch the session to a New Zealand suburb, which changes the serving store and therefore the prices and availability that search_products and get_product return. If the suburb name matches several places, the matches are returned instead and you should ask for a more specific name.
| Name | Required | Description | Default |
|---|---|---|---|
| suburb | Yes | Suburb name, e.g. 'Ponsonby'. Partial names match, so be specific. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing that the tool changes session state, alters the serving store, and directly affects the results returned by search_products and get_product. It also discloses the ambiguity behavior: matches are returned and the agent should ask for clarification. There is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences deliver the core purpose, the downstream effects, and the edge-case handling with no redundant wording. The main action is front-loaded, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter setter, the description covers the action, its impact, and the ambiguous-input behavior. It does not describe the exact success response format, but the tool has no output schema and the narrative 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?
The schema already fully documents the single 'suburb' parameter, including an example and a note that partial names match. The description reinforces the ambiguity-handling behavior but does not add substantially new parameter-level meaning beyond the schema. Given 100% schema description coverage, this is an appropriate baseline score.
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 ('Switch the session') and a clear resource ('a New Zealand suburb'), and it explains the consequence of changing the serving store. It is easily distinguished from sibling tools like get_location, which reads the current location rather than setting it.
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: to switch the session's delivery location and thereby affect product prices and availability. It also instructs the agent to ask for a more specific name when matches are returned, which is practical usage guidance. It does not explicitly name alternative tools, but the alternatives are structurally different read-type operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report whether the session is signed in, and if not, how to sign it in. Sign-in is not performed here and cannot be: it happens in a real browser via npm run login on the machine running the server, because Auth0 challenges non-browser sign-ins. This tool never sends credentials and never touches the account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral traits beyond the annotations: it never performs sign-in, cannot perform sign-in because of Auth0's non-browser challenges, never sends credentials, and never touches the account. The readOnlyHint being false is not contradicted because the description does not claim the operation cannot read or report local session state; it makes a stronger, consistent safety statement.
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 tightly structured: the core purpose is front-loaded, followed by the critical limitation and external alternative, then the safety guarantee. Every sentence carries necessary information and there is no filler.
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 tool with no output schema, the description is complete: it explains what the tool reports, what the caller should do if signed out, why sign-in cannot happen in-process, and that credentials are never touched. The 'report whether' phrasing sufficiently frames the expected result for an agent.
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 input schema has zero parameters and 100% coverage, so the description does not need to document parameter meaning. The baseline of 4 is appropriate because no parameter detail is missing or required.
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 that the tool reports signed-in status and explains how to sign in if needed, while explicitly saying sign-in is not performed here. This is a specific and useful definition, though it does not explicitly differentiate itself from the sibling auth_status tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: call it to report session status and sign-in instructions. It also gives a clear when-not-to-use condition and a named alternative: actual sign-in happens via `npm run login` in a real browser, not through this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools target a distinct resource, but sign_in and auth_status report nearly the same status, remove_from_cart duplicates set_cart_quantity(0), and search_products/search_products_batch are close variants. The descriptions clarify most boundaries, so selection is possible but not always obvious.
Tool names mostly follow a verb_noun snake_case pattern (get_cart, search_products, set_location). Minor deviations like auth_status (no verb), browse_category (singular), and search_products_batch (suffix) prevent a perfect score, but the pattern is predictable overall.
Eighteen tools is on the heavy side for a 3-15 tool well-scoped server, and several are redundant (auth_status vs sign_in, remove_from_cart vs set_cart_quantity, plus the batch search variant). The count is not chaotic, but it could be trimmed without losing functionality.
The surface covers catalogue browsing, product detail, search, specials, location, cart management, and order/purchase history. The main gap is the absence of checkout/order placement, but for a shopping-assistant domain the core workflows are present and workable.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Live Australian grocery prices from Woolworths, Coles, Aldi and Harris Farm.
Canadian grocery flyer deals and recipes by item, store, postal code, cuisine, or diet. No auth.
Grocery meal planning, budgets, and flyer deals for Canadian households. Auth required.
Signed US food & grocery data: Kroger prices, nutrition, allergens, recalls, diet filters.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/adrian-baker/woolies-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server