Search for cocktails by name. Returns matching cocktails with their ingredients.

Get detailed information about a specific cocktail by ID or slug.

List and filter cocktails. Use to browse or audit the collection.

Filters:

• name: substring match on the cocktail name.

• favorites_only: only favorited cocktails.

• tag_id / ingredient_id / method_id / glass_id / collection_id: restrict by tag, an ingredient used, prep method, glass, or collection (IDs from the matching list_* tools).

• parent_cocktail_id: only variants/riffs of a given cocktail.

• abv_min / abv_max: ABV bounds.

• missing_image_only: only cocktails with no image attached (audit helper).

• sort: "name" (default), "-name", "abv", "-abv", "average_rating", "total_ingredients", "created_at", "random".

Get cocktails that can be made with ingredients currently on the shelf.

Get user's favorite cocktails.

Search for ingredients by name.

Optional flags narrow the results (handy for cleanup work):

• specific_only: only specific bottles (leaf ingredients), skipping the generic category/parent ingredients.

• missing_image_only: only matches that have no image attached.

• exclude_commodities: drop non-bottle commodities (juices, syrups, produce, dairy, ice/salt). Combine with missing_image_only for a clean "bottles that still need artwork" list.

Get detailed information about a specific ingredient.

List and filter ingredients.

For an "incomplete entries" worklist (bottles missing an image / ABV / flavor profile), prefer bar_audit_ingredients — it already scopes to real bottles and groups the gaps. Use this tool for general browsing/filtering.

Filters:

• category: restrict to a category's whole subtree (recursive). Pass the category ingredient's ID — in Bar Assistant categories ARE ingredients (e.g. Rye Whiskey 347, London Dry Gin 384, Rhum Agricole 380). Returns every bottle filed anywhere under it.

• name: substring match on the ingredient name.

• specific_only: only specific bottles (leaf ingredients), excluding the generic category/parent ingredients themselves. NOTE: "leaf" is structural — it still includes commodity leaves (juices, syrups, produce). Add exclude_commodities for a real-bottle list.

• missing_image_only: only ingredients with no image attached — use this to find bottles whose artwork still needs filling in.

• exclude_commodities: drop non-bottle commodities (juices, syrups, produce, dairy, ice/salt). The combo specific_only + missing_image_only + exclude_commodities is the clean "real bottles still missing artwork" list.

• on_shelf_only: only ingredients currently in the bar's inventory.

• origin: substring match on origin (country/region).

• strength_min / strength_max: ABV bounds (e.g. strength_min=40).

• sort: "name" (default), "-name", "created_at", "strength", "total_cocktails", "-total_cocktails" (most-used first).

Output marks each ingredient's cocktail count and flags "NO IMAGE" so the list is directly actionable.

Get cocktails that use a specific ingredient.

Audit real bottles for incomplete data, so historical gaps can be cleaned up.

This is the canonical "what's incomplete" worklist — it reports real bottles, not commodity leaves. (For raw structural listing use bar_list_ingredients.)

Reports, per specific bottle (leaf ingredient — generic parent categories are skipped), which of these are missing:

• image — commodity leaves (juices, syrups, produce, dairy, ice) are excluded by default, so this is "bottles needing artwork".

• ABV / strength (only for bottles in a tracked spirit/liqueur category)

• flavor profile — only for bottles whose category supports flavor axes (gin, rye, bourbon, scotch, american_single_malt, aquavit, amaro, herbal_liqueur, rum, vermouth, fruit_liqueur). Bottles in categories with no axes are never flagged for a missing profile.

Axis support is seeded from a known map AND learned live from bottles that already have a profile, so it stays correct as the taxonomy grows.

Args:

• category: restrict to one category's subtree (pass the category ingredient's ID, e.g. 347 Rye). Strongly recommended — it makes the flavor scan far cheaper.

• on_shelf_only: only audit bottles currently in the bar.

• check_flavor: set False to skip the per-bottle flavor-profile scan (faster; reports only image/ABV gaps).

• include_uncategorized: also audit root-level leaves not filed under any category. Off by default.

• include_commodities: include commodity items (juices, syrups, produce…) in the missing-image list. Off by default.

Get ingredients currently on the user's shelf (what they have available).

Add ingredients to the shelf.

Remove ingredients from the shelf.

Get the user's shopping list.

Add ingredients to the shopping list.

List cocktail collections.

Get a specific cocktail collection with its cocktails.

List all cocktail tags.

List all glass types.

List cocktail preparation methods.

Get bar statistics (total cocktails, ingredients, etc).

Upload an image from a URL. Returns the image ID to use when creating cocktails or ingredients.

Upload an image from a local file path. Returns the image ID to use when creating cocktails or ingredients.

Create a new ingredient. Use parent_ingredient_id to place it in the hierarchy (e.g., under 'Gin' or 'Bourbon').

Only create a NEW specific bottle when a recipe genuinely needs that brand (see the server instructions' "Generic vs. specific" rule); for ordinary base-spirit slots, reuse the existing generic category instead of adding a brand.

Fill a new specific bottle in COMPLETELY — don't leave historical gaps:

• set strength (ABV; look it up), description, and origin;

• upload and attach an image (bar_upload_image / bar_upload_image_file);

• if its category supports flavor axes (gin, rye, bourbon, scotch, american_single_malt, aquavit, amaro, herbal_liqueur, rum, vermouth, fruit_liqueur), score a flavor profile with bar_set_flavor_profile right after creating it. Run bar_audit_ingredients to find existing bottles still missing any of these.

Create a new cocktail recipe with ingredients, instructions, and optional image.

For each ingredient slot, prefer the GENERIC category (e.g. Rye Whiskey, London Dry Gin, Tequila Blanco) over a specific bottle — see the server instructions' "Generic vs. specific" rule. Only use a specific brand when the recipe names it, the brand defines the drink (Fernet-Branca, Chartreuse, Campari, Luxardo Maraschino), or Erik asks.

Update an existing cocktail. Only provide fields you want to change.

Delete a cocktail by ID or slug.

Update an existing ingredient. Only provide fields you want to change.

Delete an ingredient by ID or slug.

List the flavor axes defined for a category (e.g. 'gin').

Axes are per-category and integer-scored. Gin uses The Gin Is In's 7-axis 0–3 system. Use this to discover valid axis names before setting profiles or slot constraints.

Return the flavor profile recorded for an ingredient (specific bottle).

Profiles are per-axis integer scores on the category's scale (gin: 0–3 on juniper/citrus/floral/heat/spice/herbal/fruited). Returns provenance too (source = tgii / llm_from_description / manual; confidence; notes).

Set or update the flavor profile for an ingredient.

Partial updates are supported: profile may contain only the axes you want to change — they're merged over the existing profile before saving. If the ingredient has no profile yet, you must pass category (and ideally the full axis set for that category).

Args: ingredient_id: BA ingredient_id of the specific bottle. profile: dict of axis → integer score (0–3). Merged over existing axes. category: required only when the ingredient has no profile yet (e.g. "gin", "amaro"). See bar_list_flavor_axes for valid axes. source: provenance — "tgii", "llm_from_description", "manual", etc. confidence: "high" | "medium" | "low" | None. notes: free-text reasoning. suggestable_for_classics: set False for novelty/allocated bottles the matcher should never surface even if their profile fits.

List a cocktail's ingredient slots with their sort index and current ingredient.

Each line shows the sort index (the canonical slot identifier), the ingredient currently in the slot, and whether the slot has flavor constraints declared in the flavor DB. Use this to find the right slot_sort before calling bar_alternatives_for_slot or constraint setters.

Declare the category + tolerance for a recipe slot.

Required before setting axis constraints. sort is the 1-based BA sort index of the ingredient in the recipe (see bar_describe_slots).

Args: cocktail_id: BA cocktail_id. sort: BA sort index of the slot (1-based). category: e.g. "gin", "rum", "whiskey". tolerance: "exact" (named bottle required) | "style" (match by vector) | "any" (any in-category bottle works). exact_ingredient_id: required when tolerance="exact". also_accept_categories: list of other categories that can sub here (e.g. ["bourbon"] on a rye slot). Cross-category subs get a small flat penalty so in-category ranks first. proof_min / proof_max: enforce a proof range (US proof).

Set a Band constraint on one axis of a recipe slot.

Band = "acceptable range; zero penalty inside, graded penalty outside." Use Band for the forgiving axes of a slot — most slots are wide on most axes. Set hard=True for the one or two axes that truly disqualify a candidate (e.g. Negroni gin → floral Band(0,2,hard=True): aggressive floral fights Campari).

For gin axes are 0–3; lo/hi are inclusive integer bounds.

Set a Point constraint on one axis of a recipe slot.

Point = "exact-ish target; penalty grows with distance." Use Point for the exposed axes of a slot — where the spirit's level on that axis genuinely matters (e.g. Martinez gin → juniper Point(2): we want a moderately juniper-forward but not over-the-top gin).

For gin axes are 0–3; value is an integer.

Remove a single axis constraint from a recipe slot.

List all flavor constraints declared for a cocktail's slots.

Rank bottles by fit for a recipe's slot.

The killer feature: given a recipe slot (declared via bar_set_slot_meta + bar_set_band_constraint / bar_set_point_constraint), rank in-stock bottles of the appropriate category by how well their flavor profiles match the slot's constraints. Includes "off-pattern" picks (disqualified by hard bands) when include_strays=True, with explanations.

Args: cocktail_id: BA cocktail_id. sort: 1-based slot index (see bar_describe_slots). on_shelf_only: if true, restrict to bottles currently on shelf. include_strays: surface hard-disqualified picks too, with reasons. top_n: max bottles to return.

Given a bottle, list recipes (with declared slot constraints) that welcome it.

Useful when a new bottle arrives — find which existing constrained recipes welcome it before adding the bottle to your shelf.

Find recipe slots where the best in-stock bottle is a stretch — the shopping list.

Loads constrained slots (all by default, or the subset matching cocktail_ids), pits them against in-stock bottles, and reports any slot whose best match is hard-disqualified or accumulates penalty ≥ threshold. Sorted worst-gap-first.

Args: cocktail_ids: restrict to these cocktails; None = every constrained slot. threshold: penalty above which a slot counts as a gap (defaults to 3.0, roughly "two-axis miss or one hard-cap brush").