The Trundler server enables agent-driven grocery shopping across multiple New Zealand providers (Countdown, New World, Pak'nSave), running locally on your machine to avoid bot detection.
Authentication
Log in via browser to capture a session for a shopping provider
Check whether a stored session is still authenticated
Product Discovery
Search products by keyword, with filters for in-stock, specials, and max results
Browse products by department (e.g. fruit-veg, pantry, frozen) with optional aisle/specials filters
Retrieve current specials/deals with automatic pagination
Store Management
List available stores for providers with per-store pricing (e.g. New World)
Select and persist the active store for a provider
Cart Management
View current cart contents and totals
Add, update quantity, or remove items by SKU
Note: cart mutations require user approval
Order History (requires login)
List past orders with dates, totals, and status (filterable by time range)
Browse past order items sorted by purchase frequency, name, or price
Retrieve all items from a specific past order by order ID
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., "@trundler search for milk at countdown"
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.
A desktop app that lets you have a dialogue with an agent while it shops for you.
The agent's brain runs either locally (Ollama) or in the cloud (Claude); either
way, all the actual grocery I/O happens on your own machine and residential connection
via trundler-mcp
(source), so there's no
bot-detection or hosting problem to solve. It's a normal npm dependency of this app —
you don't install it separately.
Cloud brain, local hands. Bot detection only cares about the requests hitting the grocery sites — those are made by trundler-mcp on your machine. The model that decides what to fetch can run wherever you like.
Electron main (Node) Renderer (React)
├── TrundlerMcp ──stdio──► trundler-mcp ──► grocery sites (residential IP)
├── Agent loop (shared) ├── chat + streamed tokens
│ ├── OllamaBackend (local) ├── product grid (from tool results)
│ └── AnthropicBackend (cloud) ├── live cart panel
└── IPC + approval gate ◄──── approve/deny ──┤ approval modal (cart mutations)One shared agent loop (src/main/agent/loop.ts) drives
the conversation. It's parameterised by a Backend, so switching Ollama ↔ Claude is a
dropdown, not a rewrite.
Tools come from MCP, so both brains inherit trundler's own product-listing instructions (letter labels, price-per-unit, cheapest-first).
Cart mutations require approval — cart_add / cart_update / cart_remove pop an
approval modal before they run.
Structured tool results become UI: product results render as a card grid; cart tools refresh the live cart panel.
Auth is first-class: a status chip shows whether you're signed in to Countdown, with Log in / Log out buttons in the top bar (no need to discover it via an error).
Related MCP server: Willys MCP Server
Node ≥ 20 (dev has 22).
Ollama running locally with a tool-capable model:
ollama pull llama3.1:8b # fast, good enough for dev
ollama pull qwen3:14b # stronger tool use, slowerThat's it — the grocery data layer (@auckland-ai-collective/trundler-mcp) is a
dependency and installs automatically. No second repo to clone or build.
npm install # also pulls trundler-mcp (no browser download; that's lazy — see below)npm run smoke -- "find jasmine rice on special" # stdio round-trip via the MCP + Ollama
npm run libcheck # in-process (buildServer) round-tripBoth resolve the MCP from the installed package, run a real tool call, and print the result — use them to confirm your model works before launching the app.
npm run dev # launches the Electron app with HMRBuild a distributable:
npm run build # compile main/preload/renderer into out/
npm run dist # + package a Windows installer (electron-builder)Countdown/Woolworths needs a login for cart and order history. Two ways:
In the app: click Log in in the top bar — a real browser window opens; sign in there and the app captures the session. The first sign-in downloads a browser (~150 MB, one-time) — the app shows a banner while that happens.
From the CLI: npx trundler login (the package ships a trundler bin).
Log out (in the app) clears the stored session and forces re-authentication. New World and Pak'nSave need no login (anonymous, read-only).
Brain (Ollama/Claude) and provider are quick switches in the top bar. The ⚙︎ drawer
holds the rest — model, Ollama host, Claude API key, MCP server path, and the
cart-approval and debug-logging toggles — and edits there apply only when you press
Save (Cancel discards). Defaults can also come from env vars — see
.env.example. Settings persist to config.json in the app's userData
directory.
MCP path: by default the app resolves the server from the installed
@auckland-ai-collective/trundler-mcp package automatically — no path to set. Override
with TRUNDLER_MCP_PATH (or the ⚙︎ field) only if you're pointing at a local checkout.
Provider | id | Cart | Notes |
Countdown |
| ✅ | Needs login — use the Log in button. |
New World |
| ❌ | Read-only; pick a store first (agent does this). |
Pak'nSave |
| ❌ | Read-only; per-store pricing. |
Trundler writes a structured JSONL session log capturing the whole interaction:
the user's prompt, the model/backend in use, every MCP tool call and its result,
cart state, approvals, and errors. One file per app run in the app's
userData/logs/ directory (use the open logs button in the debug footer, or
shell reveal).
Off by default. Turn it on with the Debug logging toggle in ⚙︎ Settings; the footer line (with an open logs button) appears only while it's on.
--debug or TRUNDLER_DEBUG=1 force it on regardless of the setting, so a user can
capture and send you logs without touching Settings:
Trundler.exe --debugEach line is one JSON event, e.g.:
{"t":"2026-07-05T…","type":"user-message","text":"add A to cart","backend":"ollama","model":"llama3.1:8b","provider":"countdown"}
{"t":"2026-07-05T…","type":"mcp-call","name":"cart_add","args":{"sku":"601342","quantity":1}}
{"t":"2026-07-05T…","type":"mcp-result","name":"cart_add","ok":true,"provider":"countdown","data":{…}}
{"t":"2026-07-05T…","type":"cart-state","provider":"countdown","itemCount":1,"detailedItems":0,"total":null}The debug log is what let us pin down real bugs — e.g. detailedItems: 0 with a
non-zero itemCount was the fingerprint of a cart-detail mapping bug in trundler-mcp
(#1, now fixed).
The cart panel still tolerates sparse data defensively in case a provider returns it.
src/
shared/types.ts shared types (domain types re-exported from the MCP package)
main/
index.ts window, IPC, orchestration, approval + auth gate
config.ts config + MCP path resolution (from the installed package)
mcpClient.ts trundler-mcp stdio client (spawn + reconnect)
logger.ts JSONL session logger
agent/
loop.ts shared tool loop
ollamaBackend.ts local model (streaming + tools)
anthropicBackend.ts Claude (streaming SSE + tools)
system.ts system prompt (+ MCP instructions)
preload/index.ts contextBridge API
renderer/ React chat UI
scripts/smoke.mjs headless stdio MCP + Ollama check
scripts/lib-check.mjs headless in-process (buildServer) checkOnly the Ollama path is exercised by the smoke test; the Claude path shares the same loop and is wired but needs an API key to try.
The app spawns the MCP as a subprocess with Electron's bundled Node
(ELECTRON_RUN_AS_NODE). The package also exposes a library entry (buildServer), so a
packaged build can instead mount the MCP in-process (in-memory transport) to avoid
subprocess/path issues — validated by npm run libcheck.
MIT © 2026 Michael Wells <mike@aaic.nz> — see LICENSE.
An open-source project. Contributions welcome.
Browse products by department. Departments: fruit-veg, meat-poultry, fish-seafood, fridge-deli, bakery, frozen, pantry, beer-wine, drinks, health-body, household, baby-child, pet.
| Name | Required | Description | Default |
|---|---|---|---|
| aisle | No | Aisle filter, e.g. "fresh-deals". | |
| pageSize | No | Products per API request (default: 120). | |
| provider | No | Shopping provider id (default: "countdown"). | |
| department | Yes | Department slug, e.g. "fruit-veg". | |
| maxProducts | No | Max products to return (default: all). | |
| specialsOnly | No | Only specials (default: false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It only lists departments and does not disclose behavioral traits such as pagination (pageSize), results limit (maxProducts), filtering (specialsOnly, aisle), or that it returns a list of products. This is insufficient for a tool with six parameters.
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 extremely concise: one sentence plus a list of departments. It is front-loaded and every element is relevant. No wasted text.
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 has six parameters and no output schema, the description is incomplete. It does not mention that the tool returns products, that filters like pageSize or specialsOnly exist, or how results are limited. More detail is needed for effective agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no extra meaning beyond listing departments, which is part of the department parameter. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Browse products by department' and lists available departments, making the verb and resource specific. It distinguishes from siblings like search_products and get_specials by focusing on browsing by department.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for browsing products by department but provides no explicit guidance on when to use this tool versus alternatives like search_products or get_specials. No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an item to the cart.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | Yes | Product SKU. | |
| unit | No | Pricing unit (default: Each). | |
| provider | No | Shopping provider id (default: "countdown"). | |
| quantity | No | Quantity (default: 1). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description provides no behavioral details such as idempotency, error handling, or side effects (e.g., does it create a new cart if none exists?). This is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded with the action, but it could include more information without sacrificing conciseness.
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 lack of an output schema and the presence of sibling tools, the description is insufficient. It does not explain return values or confirm what happens after adding an item, leaving the agent with incomplete 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 100%, so the schema already documents all parameters. The description adds no additional meaning beyond the schema, placing it at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and the resource 'item to the cart', which distinguishes it from sibling tools like cart_get or cart_remove. However, it lacks any additional context that could further clarify the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as cart_update or cart_remove. There is no mention of prerequisites or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current cart contents and totals.
| Name | Required | Description | Default |
|---|---|---|---|
| provider | No | Shopping provider id (default: "countdown"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'Get current cart contents and totals' without disclosing authentication requirements, behavior for new users, or any side effects.
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 concise at one sentence, front-loading the purpose. It could add slightly more detail without becoming verbose.
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 no output schema, the description should explain return format or behavior. It mentions 'contents and totals' but lacks detail. Also no notes on user-specific context or login requirements.
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% for the single parameter 'provider', which is already described. The tool description adds no additional meaning beyond what the schema provides, but meets baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves current cart contents and totals, using a specific verb 'Get' and resource 'current cart'. It effectively distinguishes from sibling tools like cart_add, cart_remove, cart_update which modify the cart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving the current cart state but does not explicitly state when to use this tool versus alternatives like cart_add or cart_remove. No guidance on prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove an item from the cart.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | Yes | Product SKU. | |
| unit | No | Pricing unit (default: Each). | |
| provider | No | Shopping provider id (default: "countdown"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully convey behavior. It only states a mutation occurs without mentioning side effects, reversibility, or required state (e.g., item must exist in cart).
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, clear sentence with no extraneous information; every word is necessary.
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 removal tool with well-described schema and no output schema expected, the description is nearly complete. It could explicitly state that the item is identified by sku.
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 description adds no extra meaning beyond what the schema provides for sku, unit, and provider roles.
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 'Remove an item from the cart' uses a specific verb and resource, clearly distinguishing from sibling tools like cart_add, cart_update, and cart_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., cart_update to set quantity to zero) or any prerequisites like being logged in or having an active cart.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the quantity of an item in the cart.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | Yes | Product SKU. | |
| unit | No | Pricing unit (default: Each). | |
| provider | No | Shopping provider id (default: "countdown"). | |
| quantity | Yes | New quantity (must be > 0; use cart_remove to remove). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only states the action but does not disclose side effects, authorization needs, or behavior when quantity is set to 0 (though the schema hints that removal is for cart_remove). The description is insufficient 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 a single, clear sentence with no wasted words. It is appropriately concise, though could be expanded slightly to include key usage notes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal for a tool with 4 parameters and no output schema or annotations. It does not explain return values (e.g., updated cart state), prerequisites (e.g., item must exist in cart), or behavioral details like recalculation of totals.
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 no additional meaning beyond what the input schema already provides for parameters like sku, quantity, unit, and provider.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'update' and the resource 'quantity of an item in the cart'. It distinguishes from siblings like cart_remove and cart_add by specifying that it updates quantity, but does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like cart_add (to add items) or cart_remove (to remove items). The description lacks any context about prerequisites or appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether the stored session for a provider is still authenticated.
| Name | Required | Description | Default |
|---|---|---|---|
| provider | No | Shopping provider id (default: "countdown"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey all behavioral traits. It states the core behavior but does not describe the return value (e.g., boolean, error) or any side effects. This leaves some ambiguity for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the core purpose without extraneous information. It is well-front-loaded but could be slightly more structured with a note about the return type.
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 simple input schema and no output schema, the description is minimally complete. It lacks explanation of what 'stored session' means or what providers are valid, but this may be understood from the broader tool 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 coverage is 100% and the parameter description in the schema is adequate. The tool description adds no additional meaning beyond the schema, so it meets the baseline but does not enhance understanding.
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 checks if a stored session is still authenticated, which directly corresponds to the tool name. The sibling tools include 'login', so this distinguishes itself as a verification 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 context for using this tool is implied: verify authentication status before making authenticated requests. It does not explicitly state when not to use it, but the purpose is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all items from a specific past order. Requires login.
| Name | Required | Description | Default |
|---|---|---|---|
| orderId | Yes | The order ID. | |
| provider | No | Shopping provider id (default: "countdown"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only mentions the login requirement, but does not state whether the operation is read-only, what side effects exist, or any limitations. This is insufficient for a tool that retrieves data.
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, no wasted words. The first sentence states the core purpose, the second adds a necessary condition. Very efficient.
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 2 parameters and no output schema, the description could be more helpful by hinting at the return format or specifying the difference from sibling list_past_order_items. It lacks necessary context for an agent to fully understand behavior.
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% with both parameters having descriptions. The tool description adds no extra meaning beyond the schema. Baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get all items') and the resource ('specific past order'). It is specific and uses a strong verb. However, it does not distinguish from the sibling tool list_past_order_items, which could be synonymous, reducing clarity.
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 only guideline is 'Requires login,' which is a prerequisite but not guidance on when to use this tool versus alternatives like list_past_orders or list_past_order_items. No context for choosing among siblings is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current specials/deals with automatic pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| pageSize | No | Products per API request (default: 120, max 120). | |
| provider | No | Shopping provider id (default: "countdown"). | |
| maxProducts | No | Max products to return (default: all). |
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 mentions automatic pagination, which is a behavioral trait, but does not disclose whether the operation is read-only, safe, or has any side effects. It is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose and key feature (automatic pagination). No wasted words.
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 has 3 parameters, no output schema, and no annotations, the description is somewhat incomplete. It covers pagination but lacks details on return format, error handling, or typical use cases, making it adequate but not thorough.
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% with descriptions for all 3 parameters. The description adds no additional meaning beyond the schema, just mentions 'automatic pagination,' which is already implied by the pagination-related parameters. 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 clearly states 'Get current specials/deals' with a specific verb and resource, and mentions 'with automatic pagination' which differentiates it from sibling tools like browse_products and search_products.
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 implicitly suggests using this tool to fetch specials with pagination, but provides no explicit guidance on when to use it versus alternatives, no exclusions, and no context on prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List products from past orders, sorted by purchase frequency. Requires login.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default: 1). | |
| sort | No | Sort order. | |
| maxPages | No | Max pages to fetch (default: 1). | |
| provider | No | Shopping provider id (default: "countdown"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It only states that login is required and items are sorted by purchase frequency. Does not mention whether it modifies data, rate limits, pagination behavior, or data freshness. With no annotations, this is insufficient.
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 pack essential information without waste. Front-loaded with the action and resource, then the prerequisite. No redundant phrases.
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 4 parameters and no output schema, the description should provide more behavioral context. Lacks details on return format, error conditions, or limitations (e.g., how far back 'past orders' goes). Minimal completeness.
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% with descriptions for all 4 parameters, so description's added value is limited. It clarifies default sort order (frequency) and login requirement, which adds some context beyond the schema. Baseline 3 due to high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'list', resource 'products from past orders', and adds sorting criterion. Distinguishes from sibling tools like list_past_orders (orders vs items) and get_order_items (context of past vs current).
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?
Only mentions 'Requires login' as a prerequisite. No guidance on when to use this tool versus alternatives (e.g., get_order_items or browse_products). No when-not-to-use or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List past orders with dates, totals, and status. Requires login.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Time filter: days-30, days-180, year-2025, all (default: days-180). | |
| provider | No | Shopping provider id (default: "countdown"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavior. It states login is required but does not disclose whether it is read-only, destructive, or any rate limiting. Minimal disclosure beyond that.
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?
Description is a single sentence with no wasted words. However, it could include more details (e.g., return format, pagination) without becoming verbose.
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 no output schema, description partially covers return content (dates, totals, status). Missing details on pagination, sorting, error handling, and what happens if not logged in. Adequate but incomplete.
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% (both parameters have descriptions). The tool description adds no new information beyond what the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'List' and resource 'past orders', and mentions included fields (dates, totals, status). It distinguishes itself from siblings like 'get_order_items' but does not explicitly differentiate from 'list_past_order_items'.
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?
Only mentions 'Requires login' but gives no context on when to use vs alternatives like 'get_order_items' or 'search_products'. No when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a provider's stores (for providers with per-store pricing, e.g. New World). Optionally filter by name. Use set_store to choose one before searching.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Filter stores by name, e.g. "auckland". | |
| provider | No | Shopping provider id (default: "countdown"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It mentions optional filtering and default provider behavior. Lacks disclosure of pagination, error handling, or what happens if provider does not use per-store pricing.
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 purpose. Every sentence adds value: purpose, optional filter, and next step via sibling tool. No wasted words.
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 low complexity (2 optional params, no output schema), description covers purpose, usage context, and next step. Could mention return format but not critical for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. Description adds context about per-store pricing but does not add meaning beyond schema for parameters. Some extra context about default provider is present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states specific verb 'List', resource 'a provider's stores', and context 'for providers with per-store pricing, e.g. New World'. Distinguishes from sibling 'set_store' by mentioning it in usage guidance.
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?
Explicitly says to use 'set_store' after listing to choose a store. Provides context for when this tool is relevant (per-store pricing). Does not explicitly state when not to use, but guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a browser window to sign in to a shopping provider. Complete the login in the window; the session is captured and stored locally. Run this once, or again when the session expires.
| Name | Required | Description | Default |
|---|---|---|---|
| provider | No | Shopping provider id (default: "countdown"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: opens a browser window, captures session locally, needs re-run on expiration. Lacks mention of potential side effects like invalidating previous sessions, but adequate for a simple auth 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?
Two concise sentences, front-loaded with the core action, no wasted words.
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?
Covers all essential aspects: action, method (browser window), session management, and repetition. No output schema needed; simple tool fully 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% and the description does not add meaning beyond the schema for the 'provider' parameter. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (sign in) and the resource (shopping provider), and distinguishes from sibling tools focused on browsing, cart, orders, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to use ('Run this once, or again when the session expires'), but does not explicitly mention alternatives like check_login or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for products by keyword.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query, e.g. "eggs", "jasmine rice". | |
| provider | No | Shopping provider id (default: "countdown"). | |
| inStockOnly | No | Only in-stock items (default: false). | |
| maxProducts | No | Max products to return (default: 48). | |
| specialsOnly | No | Only items on special or multi-buy (default: false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavioral traits. It only states the basic action ('search by keyword') and omits critical behaviors such as pagination, authentication requirements, result format, or any side effects. This is insufficient for an agent to predict tool 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?
The description is a single concise sentence that efficiently states the tool's purpose. It is front-loaded but could benefit from additional detail without becoming verbose.
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 has 5 parameters, no output schema, and no annotations, the description is too minimal. It does not explain what the tool returns, how to interpret results, or any constraints (e.g., provider, stock status). The description should provide more context for the agent to use the tool effectively.
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 100% description coverage, so the parameters are already well-documented. The description adds no additional meaning beyond the schema, meeting the baseline expectation of 3.
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 searches for products by keyword, which is a specific action on a resource. However, it does not differentiate from the sibling tool 'browse_products', leaving ambiguity about when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'browse_products' or 'get_specials'. There is no mention of prerequisites, exclusions, or appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Select the active store for a provider with per-store pricing. Persisted for future calls. Get store ids from list_stores.
| Name | Required | Description | Default |
|---|---|---|---|
| storeId | Yes | Store id from list_stores. | |
| provider | No | Shopping provider id (default: "countdown"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the selection is 'persisted for future calls,' which is key behavioral information. However, it does not mention whether login is required, if the previous selection is overwritten, or any side effects. With no annotations, the description carries full burden and could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of three concise sentences: purpose, persistence, and prerequisite. Every sentence adds value with no fluff. Front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, persistence, and a prerequisite. For a simple tool with two parameters and no output schema, it is mostly complete. However, it does not describe the return value or error cases, which could be helpful 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?
Schema coverage is 100%, so the description adds limited value beyond the schema. It restates the storeId source and adds context about per-store pricing, but does not elaborate on the provider parameter's default or meaning. The description adequately complements the schema without major gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Select' and the resource 'active store' for providers with per-store pricing. It distinguishes from sibling tools like browsing or cart operations, though it does not explicitly state what it does not do.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context ('for a provider with per-store pricing') and directs users to get store IDs from list_stores, a sibling tool. It does not explicitly mention when not to use this tool, but the context is sufficient for most uses.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: browsing vs searching, separate cart operations, distinct login and order history tools. No overlap.
All tools follow a consistent snake_case verb_noun pattern (e.g., browse_products, cart_add, list_past_orders).
14 tools is well-scoped for a shopping service, covering browsing, cart management, login, and order history without being excessive.
Notably missing a place_order or checkout tool, which is critical for the shopping domain. Agents can build a cart but cannot complete a purchase, leaving a dead end.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Unlock the power of food transparency with our Open Food Facts MCP server. Easily look up any food
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
MCP server for Product Management
Federated commerce search across independent WooCommerce merchants. Keyless, read-only MCP server.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/auckland-ai-collective/trundler'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
