Systembolaget

Single product, multiple stores. Use this tool only when comparing a single product across multiple stores. If you need more than one product, or only ONE store to check—do NOT use this tool. Call get_stock_balance_products once per store instead.

Check the stock of a single product across one or more stores. Use this when the user wants to know which stores have a specific product in stock. Returns stock availability per store with store details.

IMPORTANT — this tool resolves stores internally. Do NOT call search_stores first to look up store IDs. Just pass the store name or area directly in store_query (e.g., store_query='Bromma Blocks', city='Stockholm'). The tool handles store resolution, disambiguation, and geo-ranking automatically. Only use store_ids when you already have them from a previous result in the same conversation.

Parameters: product_number: A single product number (e.g., '756401'). Use productNumber, NOT productId. product_query: Text query describing a single product by name or style (e.g., 'Absolut Vodka'); for several products, provide explicit product_numbers. store_ids: List of store IDs to check. Only use when IDs are already known from a previous result — do NOT call search_stores just to get IDs. store_query: Text query to find stores — use ONLY the neighborhood, area, store name, or street (e.g., 'Bromma Blocks', 'Odenplan', 'Stora torget'). NEVER include a city name in this field; use the city parameter instead. city: City name for filtering store results (e.g., 'Stockholm', 'Linköping'). Use when you know the city from conversation context to ensure the correct store is matched. Can be used alone without store_query to find stores. search_type: Search strategy for product_query. Use 'quick' ONLY for specific product names (e.g., 'Apothic Red', 'Absolut Vodka'). Use 'natural_language' for categories or descriptive queries (e.g., 'red wine', 'fruity white wine for seafood').

Store resolution: Stores can be identified by store_ids, store_query, or just city alone. When only city is provided, the top stores in that city are used. Prefer store_ids over store_query when IDs are available from a previous result.

Store limit: This tool returns up to 20 of the closest matching stores. Inform the user that more stores may carry the product and suggest narrowing the search area or specifying a different location.

If no results are found, try again with a more specific query.

Single store, multiple products. Use this tool when you need several products at exactly one store. It only accepts ONE store per call; if you have multiple stores, call this tool once per store and include all products for that store.

Check the real-time stock balance of one or more products at a specific store. Provides information about current stock quantity, section and shelf location (parsed from the shelf string), and whether the products are in the store's assortment. Returns a list of stock balance results, one for each product.

IMPORTANT — this tool resolves stores internally. Do NOT call search_stores first to look up a store ID. Just pass the store name or area directly in store_query (e.g., store_query='Bromma Blocks', city='Stockholm'). The tool handles store resolution, disambiguation, and geo-ranking automatically. Only use store_id when you already have it from a previous result in the same conversation.

Parameters: store_id: Single store ID (e.g., '0123') when you already know the exact store from a previous result. Do NOT call search_stores just to get an ID. store_query: Store name, neighborhood, area, or street to find the store (e.g., 'Bromma Blocks', 'Odenplan', 'Stora torget'). NEVER include a city name in this field; use the city parameter instead. city: City name for filtering store results (e.g., 'Stockholm', 'Linköping'). Use when you know the city from conversation context to ensure the correct store is matched. Can be used alone without store_query to find stores. product_numbers: List of product numbers (e.g., ['756401']). Use productNumber, NOT productId. product_query: Text query describing a single product (e.g., 'Absolut Vodka'). To check several products together, enumerate their numbers in product_numbers. search_type: Search strategy for product_query. Use 'quick' ONLY for specific product names (e.g., 'Apothic Red', 'Absolut Vodka'). Use 'natural_language' for categories or descriptive queries (e.g., 'red wine', 'fruity white wine for seafood').

Store resolution: Stores can be identified by store_id, store_query, or just city alone. When only city is provided, the nearest store in that city is used. Prefer store_id over store_query when you already have the ID from a previous result.

This tool checks one store at a time. For multiple stores, make one call per store. If no results are found, try again with a more specific query.

Get detailed opening hours for Systembolaget stores matching a search query. Should be used when the user wants to know when specific stores are open, including today's hours, weekly schedules, and any special holiday hours. Returns formatted opening times with current status (open/closed) indicators.

Parameters: query: Text search query — neighborhood, area, street, or store name. NEVER include city names in the query; use the city parameter instead. city: City name for filtering (e.g., "Stockholm", "Göteborg"). Use when you know the city from conversation context to ensure correct store matching. store_ids: List of store IDs (e.g., ['0132']). Preferred when you already have store IDs from a previous search result — skips the search entirely and avoids disambiguation issues. Always prefer this over query when IDs are available from earlier in the conversation.

Store limit: Results are limited to the 150 best-matching stores. If the user asks for a broad area (e.g., all of Sweden), inform them that you're showing the 150 closest matches and ask if they'd like to narrow down to a specific area.

Provide store_ids, query, or at least a city. If both store_ids and query are given, store_ids takes precedence.

Search for products in the Systembolaget database using quick or natural language search.

Parameters:

• search_query: The search query string
• search_type: Choose between 'quick' or 'natural_language'
• 'quick': Fast keyword-based search. ONLY for specific product names/references.
• 'natural_language': AI-powered search with filters. Use for everything else.
• store_id: Numeric store ID (e.g., '0151') ONLY when you already have it

from a previous result. Do NOT pass store names here.

• store_query: Store name, neighborhood, area, or street to find the store

(e.g., 'Bromma Blocks', 'Odenplan'). NEVER include a city name in this field; use the city parameter instead.

• city: City name for filtering store results (e.g., 'Stockholm', 'Göteborg').

Use when you know the city from conversation context.

IMPORTANT — this tool resolves stores internally. Do NOT call search_stores first to look up a store ID. Just pass the store name or area directly in store_query (e.g., store_query='Bromma Blocks', city='Stockholm'). The tool handles store resolution automatically. Only use store_id when you already have it from a previous result in the same conversation.

Guidelines for choosing search type:

• Use 'quick' ONLY when: User references a specific product by name

(e.g., 'Apothic Red', 'Heineken', 'Absolut Vodka').

• Use 'natural_language' for ALL other queries: categories (e.g., 'red wine'),

descriptions (e.g., 'fruity white wine for seafood'), filtered searches (e.g., 'american wine', 'Italian red wine under 200 kr'), or any query that is not a specific product name. This ensures filters are applied correctly.

Important for natural language search:

• Avoid vague price ranges like 'cheap' or 'expensive' (results in error).
• Avoid vague quality references like 'good' or 'bad'
• Try to phrase the search query in Swedish when using natural language
• Make sure that you search for one concept or product at a time
• CRITICAL for food pairing queries: When the user asks for a drink to

pair with food (e.g., 'wine to pizza', 'vin till lax'), pass the query as close to the user's original wording as possible. Do NOT add your own wine recommendations (grapes, regions, styles) to the query. The search engine has built-in dish matching — adding specifics overrides it. Good: 'rött vin till pizza', 'vitt vin till grön sparris med parmesan' Bad: 'vitt vin Sauvignon Blanc Loire till grön sparris' (added specifics) Bad: 'torrt vitt vin hög syra' (food reference removed entirely)

Food pairing disambiguation:

• When the result includes a dish_disambiguation section, it means the search

engine did NOT find an exact dish match. The closest dish was used instead.

• In this case, the VERY FIRST thing you write (before any other text) must be:

" {dish_name} är den mest liknande maträtten jag hittade på Systembolaget." and if alternatives are included, IMMEDIATELY follow with: "Det finns också {alt1}, {alt2} och {alt3}, om någon av dem passar bättre?" (list all alternatives inline, comma-separated with "och" before the last one).

• Do NOT write any introduction, greeting, or other text before the dish message.

The dish disambiguation message must be the absolute first line of your response.

• If the user picks a different dish, re-search with that specific dish name.
• When there is NO dish_disambiguation section, the match was exact — show

results silently without any extra messaging.

Chaining with other tools:

• Each product in the result has a productNumber (e.g., '9206001'). This is

the stable identifier to use in follow-up calls like stock balance lookups.

• When the user refers to products from this result (e.g., 'the first two',

'that wine'), always map back to the exact productNumber — never guess from name memory or list position assumptions.

Search for Systembolaget store locations by name, city, or address. Should be used when the user wants to find stores near them or in a specific location. Can optionally include Google location predictions for more accurate results. Returns matching stores with addresses, contact information, and basic opening hours.

Query guidelines:

• NEVER include city names in the query — use the separate city parameter instead.

Adding a city to the query (e.g., "Kungsholmen Stockholm") causes the API to return ALL stores in that city, losing neighborhood precision.

• Use only the neighborhood, area, street, or store name in query

(e.g., "Kungsholmen", "Odenplan", "Stora torget").

• If the user only asks for stores in a city (e.g., "butiker i Linköping"),

leave query empty and pass the city in city.

• If you already have store IDs from a previous result, prefer using the

get_store_hours tool with store_ids instead of searching again.

City parameter:

• If you know the city from the conversation, pass it in city (e.g., city="Stockholm").

This filters results after the API search, keeping precision intact.

• If the user hasn't mentioned a city and the area name could exist in multiple

cities, ask the user BEFORE calling this tool.

Store limit: Results are limited to the 150 best-matching stores. If the user asks for a broad area (e.g., all of Sweden), inform them that you're showing the 150 closest matches and ask if they'd like to narrow down to a specific area.

Disambiguation: The response includes a query_analysis object with:

• ambiguous (bool): True if results span multiple cities.
• citiesFound (list): All cities in the result set.
• inferredCity (str|null): The city inferred from Google Predictions context.
• needsClarification (bool): True if the user should be asked to specify location.

If ambiguous is true, ask the user which city they mean (e.g., "Hötorget finns i Stockholm och Göteborg — vilken menar du?").