TilbudsTrolden is an MCP server for Nordic grocery shopping across Denmark, Norway, Sweden, and Finland. You can:
Search and compare grocery deals: search offers by keyword, browse a specific store's weekly offers, list available stores, and view the best deals from your preferred stores (including expiring items and biggest savings).
Manage household configuration: set country (DK/NO/SE/FI), household size, dietary restrictions, preferred stores, and default serving sizes; view or update these settings.
Manage pantry items: view items you already have, and add or remove them so they are excluded from shopping lists.
Manage recipes: view, add, update, or remove recipes with ingredients, search terms, complexity, cuisine, and protein type.
Plan meals: score recipes against current deals, generate an optimal weekly meal plan with constraints (no repeating proteins/cuisines, slow-cook day restrictions, dietary exclusions), and get a combined shopping list.
Generate smart shopping lists: build deal-optimized shopping lists from chosen recipes or planned meals, aggregating shared ingredients, excluding pantry items, and grouping items by store.
Track meals and spending: log cooked meals and grocery spending, view meal history and spending history with weekly averages and totals.
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., "@TilbudsTrolden Find the best deals on pasta this week"
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.
The deal troll that lives under the bridge between your fridge and your wallet.
An MCP server for Nordic grocery shopping. It finds the best deals across supermarkets in Denmark, Norway, Sweden, and Finland, plans your weekly dinners around what's cheap, and builds shopping lists grouped by store. You talk to your AI assistant about dinner; the troll does the legwork.
Works with any MCP-compatible client: Claude Desktop, Claude Code, VS Code, Cursor, Windsurf, ChatGPT, and others.
Search current deals across grocery chains in Denmark, Norway, Sweden, and Finland. Compare unit prices (kr/kg for Scandinavian kroner, €/kg for Finnish euros) side by side. Check what's on offer at a specific store, or get a combined view from all your preferred stores at once.
Ships with 32 starter recipes (Danish households) spanning Danish, Italian, Asian, Mexican, and Swedish cuisines. Deals are matched to ingredients automatically. Add your own recipes in your local language, remove ones you don't like, or tweak the defaults. Norwegian, Swedish, and Finnish households start with a clean slate for adding recipes with local search terms.
Plan your week's dinners. The planner checks current deals, picks the cheapest combination of recipes, and makes sure you're not eating chicken four nights in a row. You set the rules: no pork, slow-cook only on weekends, at least 3 Asian dishes this week. It handles the rest.
Get a shopping list from any set of recipes. Shared ingredients are added up across recipes (8 carrots, not "2 for this + 3 for that + 3 for the other"). Pantry items are excluded. Current deals are matched per ingredient and grouped by store.
Tell the assistant which country you're in (DK, NO, SE, or FI), how many people you're cooking for, which stores you prefer, and any dietary restrictions. Everything else follows from that: deals from your stores rank higher, pork disappears if you said no pork, and shopping lists scale to your household. Country defaults to Denmark if not set.
Tell the assistant what you already have at home. Those items get skipped in shopping lists, so you don't come home with a third bottle of soy sauce.
Record what you cooked and what you spent. The planner keeps track so you don't end up eating lasagne every Tuesday.
Related MCP server: mealplan-mcp
Denmark: Netto, Meny, Lidl, REMA 1000, Foetex, Bilka, Spar, Kvickly, 365discount
Norway: REMA 1000, KIWI, Meny, Coop Prix, Extra, Bunnpris, Obs, Spar, Joker
Sweden: ICA (Maxi/Kvantum/Supermarket/Nara), Willys, Hemkop, City Gross, Coop, Stora Coop, Tempo
Finland: S-market, K-Market, K-Supermarket, K-Citymarket, Prisma, Lidl, Tokmanni, Alepa, Sale, Halpahalli, Minimani, Saiturinpörssi
All deal data is fetched via the etilbudsavis.dk (Tjek) API, which serves flyer data for all four countries. Coverage varies; Denmark has the deepest data, followed by Finland, Sweden, and Norway.
git clone https://github.com/olgasafonova/tilbudstrolden-mcp.git
cd tilbudstrolden-mcp
npm install
npm run buildPick your client below. All use stdio transport; no API keys or auth required.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"tilbudstrolden": {
"command": "node",
"args": ["/absolute/path/to/tilbudstrolden-mcp/dist/server.js"]
}
}
}Restart Claude Desktop after saving.
claude mcp add tilbudstrolden node /absolute/path/to/tilbudstrolden-mcp/dist/server.jsAdd to your workspace .vscode/mcp.json:
{
"servers": {
"tilbudstrolden": {
"command": "node",
"args": ["/absolute/path/to/tilbudstrolden-mcp/dist/server.js"]
}
}
}Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"tilbudstrolden": {
"command": "node",
"args": ["/absolute/path/to/tilbudstrolden-mcp/dist/server.js"]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"tilbudstrolden": {
"command": "node",
"args": ["/absolute/path/to/tilbudstrolden-mcp/dist/server.js"]
}
}
}In Settings > MCP Servers, click "Add Server" and enter:
Name: tilbudstrolden
Command: node
Arguments: /absolute/path/to/tilbudstrolden-mcp/dist/server.js
TilbudsTrolden uses stdio transport. Point your client at:
command: node
args: ["/absolute/path/to/tilbudstrolden-mcp/dist/server.js"]Optional environment variable:
TILBUDSTROLDEN_DATA=/custom/path/to/data.jsonTool | What it does |
| Search current offers across stores by keyword (DK/NO/SE/FI) |
| List this week's offers from a specific store |
| Show the best deals from your preferred stores, with expiring items and biggest savings |
| List available grocery chains with dealer IDs |
Tool | What it does |
| View current household config |
| Set country (DK/NO/SE/FI), household members, dietary restrictions, preferred stores, servings |
| View pantry contents |
| Add or remove pantry items (excluded from shopping lists) |
Tool | What it does |
| List all saved recipes |
| Save a new recipe with ingredients, search terms (in your language), complexity, cuisine, and protein type |
| Delete a recipe by name |
Tool | What it does |
| Score all recipes against current deals, ranked by deal coverage |
| Score, plan a week, and generate a shopping list in one step |
| Build a shopping list from specific recipes, with deals matched per ingredient |
Tool | What it does |
| Record what you cooked and when |
| View past meals |
| Record grocery spending |
| View spending history |
TilbudsTrolden ships with 32 recipes that work out of the box. They're loaded on first use and fully editable; add your own or remove any you don't need.
Danish (13): Frikadeller, Brændende Kærlighed, Kylling i Karry, Laks i fad, Flæskesteg, Tomatsuppe, Hakkebøffer med bløde løg, Kartoffelsuppe, Fiskefilet med remoulade, Biksemad, Koteletter i fad, Bagt kylling med ovnkartofler, Pølsegryde
Italian (6): Spaghetti Bolognese, Lasagne, Spaghetti Carbonara, Tomatrisotto, Salsiccia Pasta, Marry Me Chicken
Asian (7): Wok med kylling, Nudelsuppe med kylling, Uncle Roger's Egg Fried Rice, Nasi Goreng, Chow Mein, Uncle Roger's Adobo, Maangchi's Bulgogi
Mexican (2): Chili con Carne, Tacos med kylling
Swedish (4): Kajsas Kycklingfile med senap och rosepeber, Grillet laks med tomatsmor, Sagas Krydderisauce, Fransk grillet kylling med dragonsauce
Complexity ranges from quick (15-20 min) through medium (30-45 min) to slow (1+ hour). Proteins cover chicken, beef, pork, fish, egg, and vegetarian.
Real examples of how you'd talk to your AI assistant with TilbudsTrolden running.
You: We're 3 people, no pork, and we shop at Netto, REMA 1000, and Meny.
The assistant saves your setup. From now on, deals from Netto, REMA, and Meny get priority, and pork recipes are excluded from meal plans.
You: Switch me to Finland. We shop at Prisma, K-Supermarket, and Lidl.
Country becomes FI, stores update, and deals now come from Finnish chains. Prices show in €/kg instead of kr/kg.
You: What's on sale at my stores this week?
You get a summary per store: expiring deals that need action, biggest savings, and highlights.
You: Find me the cheapest hakket oksekoed.
Found 6 deals for "hakket oksekød":
1. Hakket okse- eller grisekød - 99 DKK (76.15 kr/kg) @ Bilka
2. Hakket oksekød 8-12% - 36.66 DKK (91.65 kr/kg) @ Fleggaard
3. Velsmag hakket oksekød 7-10% - 45 DKK (112.50 kr/kg) @ Netto
...You: Plan next week's dinners. No pork except Tuesday, mix of Asian and other.
You get a 7-day plan with no consecutive protein or cuisine repeats, plus a shopping list for the whole week.
7-day meal plan (3 people)
Mon: Tomatrisotto (Italian, vegetarian)
Tue: Chow Mein (Asian, pork)
Wed: Laks i fad (Danish, fish)
Thu: Maangchi's Bulgogi (Asian, beef)
Fri: Fiskefilet med remoulade (Danish, fish)
Sat: Lasagne (Italian, beef)
Sun: Nudelsuppe med kylling (Asian, chicken)
Shopping list (58 items)
Buy at Netto: hakket oksekød 45 DKK, kyllingebrystfilet 49 DKK, ...
Buy at REMA: oksemørbrad 129.95 DKK, remoulade 10 DKK, ...
Buy at regular price: mozzarella, parmesan, kokosmælk, ...You: Save a recipe for chicken tikka masala: 500g kyllingebryst, 200g yoghurt, tikka masala paste, hakkede tomater, piskefloede, ris. Medium, Indian, chicken.
The recipe is saved. It shows up in meal plans and deal matching from now on.
You: Make a shopping list for bolognese and tacos, 4 people.
Shared ingredients (like onions used in both) are aggregated. Pantry items are excluded.
You: We have rice, soy sauce, and sesame oil at home.
These items get skipped in future shopping lists.
You: We made the bulgogi tonight, spent 185 kr at REMA.
No bulgogi for a while.
Nordic grocery deals bundle products in creative ways ("Rejer, kold- eller varmroget laks"). TilbudsTrolden tells raw ingredients apart from processed products using language-specific food terminology for Danish, Norwegian, Swedish, and Finnish. Searching for "laks" as a cooking ingredient won't match roget/rokt/rokt laks or palaeg/palegg/palagg, and searching for "jauheliha" in Finland won't match savustettu makkara. Your preferred stores get priority in results.
The scoring engine uses locale-specific indicators for each country: processed meat terms (roget/rokt/rokt/savustettu), raw meat terms (fersk/fersk/farsk/tuore), non-food filters, and dietary exclusion patterns. All four languages have full coverage for pork, beef, lamb, fish, shellfish, dairy, gluten, beans, nuts, and egg exclusions.
The meal planner won't repeat the same protein or cuisine more than twice in a week, and you can restrict slow-cook recipes to specific days.
All data lives in a single JSON file: ~/.tilbudstrolden.json. Override the path with the TILBUDSTROLDEN_DATA environment variable.
Everything lives there: household config, recipes, pantry, meal history, and spend log. Created automatically on first use. No database, no cloud service, no account required.
npm install # install dependencies
npm run dev # watch mode with tsx
npm run build # compile TypeScript
npm run lint # run Biome linter
npm run typecheck # strict TypeScript check
npm test # run tests (Vitest)Node.js 18 or later
No API keys needed. Deal data is fetched via the etilbudsavis.dk (Tjek) public API, which serves all four Nordic markets.
Deal data fetched via the etilbudsavis.dk (Tjek) API.
Starter recipe ingredient lists adapted from valdemarsro.dk. Uncle Roger recipes from Nigel Ng's YouTube (Egg Fried Rice, Adobo). Bulgogi recipe from Maangchi. Swedish family recipes from jarfors.com by Mikael Jarfors.
Check out my other MCP servers:
Server | Description | Stars |
Access GLEIF LEI database. Look up company identities, verify legal entities. | ||
Connect AI to any MediaWiki wiki. Search, read, edit wiki content. | ||
Control Miro whiteboards with AI. Boards, diagrams, mindmaps, and more. | ||
Access Nordic business registries. Look up companies across Norway, Denmark, Sweden. | ||
Talk to your ProductPlan roadmaps. Query OKRs, ideas, launches. | ||
Go library for SEP-2127 Server Cards. Pre-connect discovery for MCP servers. |
Add or update a recipe for meal planning and deal scoring. USE WHEN: saving a new recipe or updating an existing one. TIP: searchTerms defaults to [ingredient name] and category defaults to 'other' if omitted, reducing input friction. Overwrites existing recipe with same name. Returns confirmation with recipe name, complexity, cuisine, protein, and ingredient count.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Recipe name | |
| servings | No | Servings (default 4) | |
| complexity | Yes | quick (<30min), medium (30-60min), slow (60min+) | |
| cuisineType | Yes | e.g. asian, danish, italian, mexican | |
| ingredients | Yes | Ingredients | |
| proteinType | Yes | e.g. chicken, beef, pork, fish, vegetarian |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavior: 'Overwrites existing recipe with same name' and return format. However, no annotations are present, and the description does not cover authentication, error handling, or idempotency, which would be helpful 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?
Three focused sentences: purpose, usage tip, and behavior. Each sentence serves a distinct role with no redundancy. Front-loaded with 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?
Given no output schema, the description adequately explains return fields. It covers purpose, parameters (with defaults), and overwrite behavior. Would benefit from error handling notes, but is sufficient for typical 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 coverage is 100%, so baseline is 3. The description adds value by noting default behaviors for 'searchTerms' and 'category', reducing friction. This extra context justifies a 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?
Clearly states 'Add or update a recipe for meal planning and deal scoring', using specific verb and resource. Distinguishes from sibling tools like 'remove_recipe' and 'get_recipes'.
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 states 'USE WHEN: saving a new recipe or updating an existing one', providing clear context. Lacks explicit exclusion or alternative tool mentions, but the usage instructions are unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the best current deals from your preferred stores. USE WHEN: browsing what's cheap this week, deciding what to cook based on deals ('what's on sale?'). NOT FOR: searching for a specific product (use search_deals). Requires household stores to be configured via update_household.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max deals per store (default 30) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as whether the tool is read-only, requires authentication, or has any side effects. The description only states what it shows, not its 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: purpose, use when/not for, and prerequisite. Every sentence adds value; no wordiness.
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 is simple (1 param, no output schema), the description adequately covers purpose, usage, and prerequisite. It lacks explicit behavioral info but is otherwise complete for a query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'limit' is fully described in the input schema (max deals per store, default 30). The description adds no additional parameter information, so 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 clearly states it shows best current deals from preferred stores, and explicitly contrasts with sibling search_deals for specific product searches, making purpose distinct.
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 explicit 'USE WHEN' scenarios (browsing cheap items, cooking decisions) and a clear 'NOT FOR' exclusion with a sibling tool. Also mentions a prerequisite (household stores configured).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deal-optimized shopping list from specific recipes, grouped by store. USE WHEN: preparing to shop for chosen recipes ('shopping list for Bolognese and Chili'). Aggregates quantities across recipes, computes pack sizes, flags expiring deals. NOT FOR: deciding what to cook (use score_recipes or plan_and_shop first). Requires recipes to exist (see add_recipe).
| Name | Required | Description | Default |
|---|---|---|---|
| people | No | Household size (overrides stored household config) | |
| recipes | Yes | Recipe names | |
| excludePantry | No | Skip pantry items (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses key behaviors: 'Aggregates quantities across recipes, computes pack sizes, flags expiring deals.' This is informative, though it doesn't mention whether state is modified or if any side effects occur. However, for a list-generation tool, this is sufficient.
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 three sentences, front-loading the main purpose, followed by usage guidance and exclusions. 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 three parameters, no output schema, and 18 sibling tools, the description covers purpose, usage, exclusions, and key behaviors. It adequately informs an agent when to use this tool and what to expect.
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 has 100% description coverage for parameters. The description adds meaning beyond the schema by explaining that the tool groups by store, aggregates quantities, computes pack sizes, and flags deals, which are not in 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 starts with a clear statement: 'Deal-optimized shopping list from specific recipes, grouped by store.' It specifies the verb 'generate' (implied in name) and the resource 'shopping list', and distinguishes from siblings by stating 'NOT FOR: deciding what to cook (use score_recipes or plan_and_shop first).'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'USE WHEN: preparing to shop for chosen recipes' with an example, and provides clear exclusions: 'NOT FOR: deciding what to cook' with alternatives. It also notes a prerequisite: 'Requires recipes to exist (see add_recipe).'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get household config: people, dietary restrictions, preferred stores, servings. USE WHEN: checking current setup before meal planning, verifying store preferences. Returns onboarding guidance if not yet configured.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a key behavioral trait: 'Returns onboarding guidance if not yet configured.' It implies a read-only operation with no side effects, which is appropriate for a configuration retrieval tool. However, without annotations, it could further elaborate on potential latency or data freshness.
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 (two sentences) with no fluff. It front-loads the main action and purpose, then adds usage context. Every sentence contributes value, making it efficient for AI parsing.
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 absence of an output schema, the description fully explains the returned data (people, dietary restrictions, etc.) and the special case of unconfigured states. It covers all necessary details for a simple configuration read tool, requiring no additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema description coverage is 100%. The description adds value by explaining what the tool returns, compensating for the lack of parameters. It ensures the agent understands the output even without parameters.
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 household configuration, listing specific items like people, dietary restrictions, preferred stores, and servings. This distinguishes it from sibling tools like update_household (write) and get_pantry (different resource), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage scenarios: 'USE WHEN: checking current setup before meal planning, verifying store preferences.' This offers clear guidance on when to invoke this tool, and the context signals show no required parameters, simplifying decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent meal history for rotation planning. USE WHEN: checking what was cooked recently to avoid repetition, reviewing eating patterns. Returns meal entries with dates, recipe names, and who ate.
| Name | Required | Description | Default |
|---|---|---|---|
| weeks | No | Weeks back (default 4) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry the burden. It states the tool returns history (read-only behavior) and the output fields (dates, recipe names, who ate). It does not cover permissions, rate limits, or side effects, but for a simple read tool this is adequate.
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 with no fluff. The first sentence states purpose, the second provides usage guidance and output description. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema. The description adequately explains the return values. It could mention ordering or pagination, but for this use case it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'weeks' described as 'Weeks back (default 4).' The description adds no additional meaning beyond the schema, so 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 tool provides 'recent meal history for rotation planning' with specific use cases 'checking what was cooked recently to avoid repetition, reviewing eating patterns.' It distinguishes from siblings like log_meal and deals_this_week.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage guidance with 'USE WHEN: checking what was cooked recently to avoid repetition, reviewing eating patterns.' It does not mention alternatives explicitly but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List pantry items (excluded from shopping lists). USE WHEN: checking what's already stocked before generating a shopping list. Returns list of pantry item names.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It clarifies that pantry items are excluded from shopping lists, a behavioral trait. It doesn't mention permissions, side effects, or return format details beyond 'list of pantry item names,' which is adequate for this simple tool but not richly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with the core purpose, then use case and return info. 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?
Given no output schema and zero parameters, the description is complete: it states what the tool does, when to use it, and what it returns. No additional information is needed for this simple 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?
There are no parameters (schema coverage 100%), so the description has no burden to add parameter meaning. Baseline is 4 per instructions, and the description doesn't attempt to add anything beyond, which 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 'List pantry items' with a specific verb and resource. It distinguishes from siblings by noting 'excluded from shopping lists' and provides context for use before generating a shopping list, differentiating it from sibling tools like generate_shopping_list.
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 includes 'USE WHEN: checking what's already stocked before generating a shopping list,' providing explicit context for when to use the tool. However, it does not explicitly name alternatives or when not to use it, so it's slightly below the top tier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List saved recipes with ingredients, metadata, and search terms. USE WHEN: reviewing recipe library, checking what's available for meal planning. Returns onboarding guidance if no recipes exist yet.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description fully covers behavior: it lists recipes and returns onboarding guidance if none exist. It does not mention pagination or side effects, but for a zero-parameter list tool, this is adequate.
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 main purpose, followed by usage guidance and a special return case. 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?
For a parameterless listing tool with no output schema, the description fully explains what is returned and notes a special case (onboarding guidance). It is complete for the tool's complexity.
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 has no parameters, so the description does not need to add parameter details. With 100% schema coverage and zero parameters, the baseline of 4 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 verb 'List' and the resource 'saved recipes' with details on what is included (ingredients, metadata, search terms). It distinguishes from siblings like 'add_recipe' and 'remove_recipe'.
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 provides when-to-use scenarios ('reviewing recipe library, checking what's available for meal planning') but does not include when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Spending history with weekly averages and totals. USE WHEN: reviewing grocery budget, tracking spending trends. Returns spending entries with totals and weekly averages.
| Name | Required | Description | Default |
|---|---|---|---|
| weeks | No | Weeks back (default 8) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It states the return includes 'spending entries with totals and weekly averages,' which is adequate. But it doesn't disclose whether the tool is read-only, has side effects, or any required permissions. A 3 is appropriate as it covers the basics but lacks depth.
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 core purpose then usage advice. No fluff, every sentence adds value. Ideal for quick comprehension.
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 explains the return structure. The single parameter is optional with default, so no missing detail. For a simple retrieval tool, this is nearly complete; missing only explicit mention of read-only nature (though implied).
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% (the single 'weeks' parameter has a description). The description adds context about output format (totals, weekly averages) but does not enhance parameter semantics beyond the schema. Baseline 3 is correct.
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 returns 'spending history with weekly averages and totals,' which is a specific verb+resource combination. It distinguishes from siblings like 'log_spend' (input) and other grocery tools by focusing on historical data. The use case mention further clarifies 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?
Explicitly tells when to use: 'reviewing grocery budget, tracking spending trends.' This provides clear context. However, it does not exclude when not to use or mention alternatives, though the sibling list exists and the context is sufficient for this simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List current offers from a specific store. USE WHEN: browsing what's on sale at one store ('what's at Netto this week'). NOT FOR: searching across all stores (use search_deals) or checking best deals from all preferred stores (use deals_this_week). Returns offers with prices, unit prices, store name, and expiry dates.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results | |
| store | Yes | Store name or dealer ID. Use list_stores to see available stores for your country. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It discloses that the tool returns offers with prices, unit prices, store name, and expiry dates. For a read-only list operation, this is adequate.
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 plus a short list of return fields. Front-loaded with action, every sentence serves a purpose. 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?
For a simple list tool with no output schema, the description lists all relevant return fields and provides enough context for correct invocation. Complements the input schema well.
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 has 100% coverage, but the description adds value by advising to use list_stores for available stores. The limit parameter is self-explanatory; minimal extra context 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?
Description starts with 'List current offers from a specific store,' which is a specific verb+resource. It distinguishes from siblings like search_deals and deals_this_week by explicitly contrasting use cases.
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 explicit WHEN to use ('browsing what's on sale at one store') and WHEN NOT to use ('searching across all stores' and 'checking best deals from all preferred stores') with direct sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List grocery chains with dealer IDs for your country (DK/NO/SE/FI). USE WHEN: finding store IDs for get_store_offers or setting up household preferred stores via update_household. NOT FOR: seeing deals (use search_deals or deals_this_week). Returns store names and dealer IDs. Full directory available for DK; NO/SE/FI show curated grocery chains.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Include non-grocery stores too | |
| query | No | Filter by name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the tool returns store names and dealer IDs, and importantly differentiates behavior per country (full directory for DK, curated for NO/SE/FI). This adds value beyond the schema. Slight deficiency: no mention of authentication or pagination, but acceptable for a simple listing 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?
Four sentences, each serving a distinct purpose: purpose/scope, use cases, exclusions, and behavior/return info. Front-loaded, every sentence is necessary and adds value. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 optional parameters, no output schema) and 18 sibling tools, the description covers purpose, usage guidelines, alternatives, behavior variations by country, and return format. It is complete for an agent to decide when and how to use it.
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 baseline 3. The description adds context about country-specific results and return format (names and dealer IDs), which enhances understanding of how parameters affect output. It doesn't elaborate on 'all' or 'query' beyond schema, but the real-world usage context compensates.
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 lists grocery chains with dealer IDs for specific countries (DK/NO/SE/FI). It distinguishes itself from siblings by explicitly stating it is not for deals (use search_deals or deals_this_week) and specifying use cases for get_store_offers and update_household.
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 explicit 'USE WHEN' and 'NOT FOR' guidance, including alternative tool names (search_deals, deals_this_week). It also clarifies the country scope, giving the agent clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a cooked meal for rotation tracking. USE WHEN: logging what was cooked to avoid repeating meals in future planning. Deduplicates by date + recipe name. Returns confirmation with date, recipe, and people logged.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | YYYY-MM-DD | |
| people | Yes | Who ate | |
| recipe | Yes | Recipe name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral traits. It reveals deduplication by date+recipe and returns confirmation with date, recipe, and people. This is adequate for a simple logging tool, though it doesn't mention side effects like whether duplicates are ignored or updated.
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 plus a USE WHEN clause, zero wasted words. Information is front-loaded and every sentence earns its place. Excellent 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?
The tool has 3 parameters with full schema coverage and no output schema. The description explains what it returns (confirmation fields). It could mention error handling or behavior on duplicate, but for a simple mutation tool, it is reasonably complete.
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 decent descriptions for each parameter. The description adds value by explaining deduplication logic involving date and recipe, clarifying their role beyond the schema. This is slightly above 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 tool records a cooked meal for rotation tracking, with specific verb and resource. It distinguishes from siblings like add_recipe (adding new recipes) and get_meal_history (viewing history). However, it could be more explicit about how it differs from other logging 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?
Includes explicit 'USE WHEN: logging what was cooked to avoid repeating meals in future planning', which guides the agent on when to invoke. Does not provide when-not-to-use or name alternatives, but the context is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record grocery spending for budget tracking. USE WHEN: logging what was spent after a shopping trip. Returns confirmation with amount, store, date, and item count.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | YYYY-MM-DD | |
| items | Yes | Items bought | |
| notes | No | ||
| store | Yes | Store name, e.g. 'Netto' or 'Føtex' | |
| estimatedTotal | Yes | Amount spent in local currency |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the tool returns a confirmation with key fields, which is good, but does not disclose side effects, error conditions, idempotency, or authentication needs. The behavioral description is minimal and could be more comprehensive.
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, front-loading the purpose and providing immediate usage guidance. Every word adds value, making it 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 tool's simplicity and high schema coverage, the description covers the key behavior (return confirmation) and usage context. It lacks output schema but mentions return fields. Missing details on optional parameters like 'notes', but overall sufficient for a basic logging 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 coverage is high (80%), so baseline is 3. The description mentions parameters (amount, store, date, item count) but adds little beyond the schema descriptions. It does not clarify the 'notes' parameter or format nuances.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Record') and resource ('grocery spending'), and distinguishes it from siblings like 'get_spend_log' (retrieval) and 'log_meal' (different domain). The return value is also specified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('USE WHEN: logging what was spent after a shopping trip'). It does not mention alternative tools or when not to use, but the context with siblings makes the usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score recipes, optimize a weekly meal plan, and generate a shopping list in one step. USE WHEN: 'plan my week', 'what should we eat?', 'make a meal plan with shopping list'. This is the main entry point for weekly dinner planning. NOT FOR: shopping for specific pre-chosen recipes (use generate_shopping_list). Returns meal plan (day-by-day with costs) followed by deal-optimized shopping list grouped by store.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Days to plan (default 7) | |
| people | No | Household size (overrides stored config) | |
| maxSlowDays | No | Max slow-cook days (default 2) | |
| maxPerCuisine | No | Max same cuisine in plan (default 2) | |
| maxPerProtein | No | Max same protein in plan (default 2) | |
| preferCuisines | No | Soft cuisine preferences: {"asian": 3} = prefer at least 3 Asian dishes | |
| slowOnlyOnDays | No | Restrict slow recipes to these days (1-indexed). E.g. [6, 7] | |
| excludeProteins | No | Dietary exclusions, e.g. ["pork", "dairy"]. Also scans ingredient names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the return structure (meal plan day-by-day with costs, deal-optimized shopping list grouped by store). No annotations exist, so description carries the burden; it could explicitly state if the plan is saved or if it's read-only, but it sufficiently communicates the main 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?
Three sentences front-loading the core purpose, then usage guidance, then return details. No wasted words; each sentence adds unique value.
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?
No output schema but the description explains the return format. Covers main inputs, but lacks details on error handling or edge cases. Given complexity (8 params, nested objects), it is mostly complete.
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 each parameter fully described. The description does not add additional semantic value beyond the schema, so 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?
Clearly states the tool scores recipes, optimizes a weekly meal plan, and generates a shopping list in one step. Provides example usage phrases like 'plan my week' and distinguishes itself from generate_shopping_list.
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 states 'USE WHEN' with specific queries and 'NOT FOR' with an alternative sibling tool (generate_shopping_list), giving clear guidance on when to invoke this tool vs others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a recipe by name. USE WHEN: cleaning up the recipe library. Case-insensitive name matching. Returns confirmation or 'not found' message.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Recipe name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description discloses case-insensitive matching and return type. Sufficient for a simple removal 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?
Four concise clauses, no wasted words. Each sentence adds distinct value: action, usage, matching behavior, return info.
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 tool with one parameter and no output schema, description covers action, usage, parameter details, and return behavior completely.
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 describes 'name' as 'Recipe name'; description adds 'by name' and 'case-insensitive matching', enhancing understanding beyond 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?
Clearly states verb 'Remove', resource 'recipe', and method 'by name'. Distinguishes from siblings like add_recipe and get_recipes.
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 'USE WHEN: cleaning up the recipe library', providing clear context. No mention of when not to use, but scenario is specific.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score all saved recipes against current deals, optionally optimize a weekly meal plan. USE WHEN: deciding what to cook based on current deals ('what's cheapest this week'), comparing recipe costs. NOT FOR: generating a shopping list (use generate_shopping_list or plan_and_shop). Shows deal coverage %, estimated cost, and confidence levels per ingredient.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Days to plan (default 7) | |
| optimize | No | Also generate optimal weekly plan | |
| maxSlowDays | No | Max slow-cook days in plan (default 2) | |
| maxPerCuisine | No | Max same cuisine in plan (default 2) | |
| maxPerProtein | No | Max same protein in plan (default 2) | |
| preferCuisines | No | Soft cuisine preferences: {"asian": 3} = prefer at least 3 Asian dishes. Best-effort, won't fail if impossible. | |
| slowOnlyOnDays | No | Restrict slow recipes to these days only (1-indexed). E.g. [6, 7] for weekends | |
| excludeProteins | No | Dietary exclusions. Checks both recipe type and individual ingredients. E.g. ["pork"] also catches bacon in vegetarian recipes. Options: pork, beef, lamb, fish, shellfish, dairy, gluten, beans, nuts, egg | |
| allowProteinOnDays | No | Per-day exceptions for excluded proteins (1-indexed). E.g. {"pork": [2]} = allow pork on day 2 (Tuesday) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It does not explicitly state whether the tool is read-only or if 'optimize' modifies data. The description reveals output details but lacks side-effect warnings.
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 essential information: purpose, usage guidance, and output summary. No wasteful words, front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While usage and guidelines are clear, the description lacks a comprehensive explanation of the return value. With no output schema, it only vaguely mentions 'deal coverage %, estimated cost, and confidence levels' without specifying structure or format.
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?
With 100% schema coverage, the description adds significant value beyond the schema by explaining behavior (e.g., 'excludeProteins checks both recipe type and individual ingredients', 'preferCuisines is best-effort'). This compensates for complex parameters.
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 ('score') and resource ('saved recipes against current deals') and distinguishes from siblings by explicitly stating what it is not for (generating shopping list) and naming alternatives (generate_shopping_list, plan_and_shop).
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 explicit USE WHEN context ('deciding what to cook based on current deals') and NOT FOR conditions with alternative tools, giving clear guidance on when to invoke this tool versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search grocery deals across stores by keyword. Supports Denmark (DK), Norway (NO), Sweden (SE), and Finland (FI) based on household country setting. USE WHEN: finding specific products, checking prices, comparing stores. NOT FOR: browsing one store's catalog (use get_store_offers) or generating a shopping list (use generate_shopping_list). Returns deals sorted by relevance with unit prices.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 20) | |
| query | Yes | Search term in local language, e.g. 'hakket oksekød' (DK), 'kjøttdeig' (NO), 'köttfärs' (SE), 'jauheliha' (FI) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description compensates by disclosing supported countries, sorting by relevance, and return of unit prices. It doesn't mention potential side effects, but none are expected for a search 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 well-structured sentences with clear USE WHEN/NOT FOR sections, no redundant information, efficient use of 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?
Comprehensive for a simple search tool with two parameters: explains scope, sorting, and usage context. Lacks mention of pagination or max results beyond the limit parameter, but not critical.
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%, but description adds value by providing example search terms in multiple local languages, aiding parameter formulation 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?
Clearly states it searches grocery deals by keyword across stores in specific countries, and distinguishes from sibling tools like get_store_offers and generate_shopping_list with explicit use cases.
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 provides USE WHEN and NOT FOR conditions, naming alternative tools for different tasks, helping the agent decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set household members, dietary restrictions, preferred stores, country, servings. USE WHEN: first-time setup or changing household config. Required before shopping lists can filter by preferred stores. TIP: use list_stores to find dealer IDs. Set country to change market: DK, NO, SE, FI. Returns updated config summary: country, people count, store count, default servings.
| Name | Required | Description | Default |
|---|---|---|---|
| people | No | People in household | |
| stores | No | Preferred stores | |
| country | No | Country code: DK, NO, SE, FI. Defaults to DK. Changes which stores and deals are shown. | |
| defaultServings | No | Default servings |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It correctly states this is an update operation and describes returned config summary. However, it does not clarify if the tool replaces or merges household members/stores, which is a behavioral detail an agent might need.
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 clear sentences: first states what it does, second gives usage context, third provides tips and return info. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, description explains return structure (country, people count, store count, default servings). All parameters are covered by schema. Complete for a tool with 4 params and clear purpose.
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 baseline is 3. Description groups parameters and adds context (e.g., country codes) but does not add meaning beyond what the schema already provides.
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 verbs like 'set' and lists specific resources: household members, dietary restrictions, preferred stores, country, servings. Clearly distinguishes from siblings like get_household (read-only) and other 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?
Explicitly states when to use ('first-time setup or changing household config'), provides a prerequisite ('Required before shopping lists can filter by preferred stores'), and offers a tip to use list_stores for dealer IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add or remove pantry items (excluded from shopping lists). USE WHEN: updating stock after shopping or noting staples you always have. Items are matched case-insensitively. Returns updated pantry item list.
| Name | Required | Description | Default |
|---|---|---|---|
| add | No | Items to add to pantry | |
| remove | No | Items to remove from pantry |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses mutation (add/remove) and case-insensitive matching. However, no annotations exist, and description omits details like idempotency, error behavior on duplicate add or missing remove, and limits. Adequate but not fully 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?
Three sentences with no waste. Front-loaded purpose, then usage guidance, then behavioral detail and return. Each 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 tool with two array params and no output schema, the description covers purpose, usage, behavior, and return. Could mention duplicate/missing handling, but overall complete for its complexity.
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 covers 100% of parameters with basic descriptions. Description adds value by explaining case-insensitive matching (relevant for remove) and the context that pantry items are excluded from shopping lists. Slightly above 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?
Description starts with 'Add or remove pantry items', clearly specifying verb and resource. It distinguishes from siblings like get_pantry (read-only) and generate_shopping_list (different purpose) by noting pantry items are excluded from shopping lists.
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 states 'USE WHEN: updating stock after shopping or noting staples you always have', providing clear usage context. Does not explicitly mention when not to use or alternatives, but the guidance is sufficient for typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.5.1add_recipedeals_this_weekgenerate_shopping_listget_householdget_meal_historyget_pantryget_recipesget_spend_logget_store_offerslist_storeslog_meallog_spendplan_and_shopremove_recipescore_recipessearch_dealsupdate_householdupdate_pantryEach tool has a clearly distinct purpose and scope. Even overlapping areas like deals are well-differentiated: deals_this_week shows best deals from preferred stores, search_deals searches across stores by keyword, and get_store_offers shows offers from a specific store. Descriptions include clear USE WHEN / NOT FOR guidance, minimizing ambiguity.
All tools follow a consistent verb_noun pattern in snake_case (e.g., add_recipe, get_recipes, log_meal, update_household). Multi-word names like deals_this_week and generate_shopping_list still adhere to the pattern. No mixing of camelCase or other conventions.
18 tools is well-scoped for a meal planning and grocery deal optimization server. It covers all necessary operations (CRUD for recipes, household, pantry; logging for meals and spend; multiple deal query methods; combined planning) without unnecessary redundancy. The number feels appropriate and each tool serves a clear purpose.
The tool surface covers the full lifecycle of meal planning based on deals: recipe management, household configuration, pantry tracking, meal history, spend tracking, deal discovery, recipe scoring, shopping list generation, and combined planning. There are no obvious gaps; for example, add_recipe also handles updates, and update_pantry can both add and remove items. The domain is fully addressed.
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
Skiplagged MCP Server for flight search, hotel booking, and travel planning
MCP server for real-time product search by barcode (EAN, UPC, GTIN) or keyword on ean-search.org
MCP server for generating rough-draft project plans from natural-language prompts.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/olgasafonova/tilbudstrolden-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
