Add a recipe to user favorites for persistent storage across sessions.

REMEMBER: To always use the list_favorites tool to check if a recipe is already favorited before adding it, to avoid duplicates!

This tool saves recipes to a permanent favorites database that persists between sessions. Use this to bookmark recipes you want to return to later. Each favorite can include custom notes for personal recipe modifications or preferences.

The favorites system supports:

• Recipe URL (required) - the Canada's Food Guide recipe link

• Recipe title for easy identification

• User session grouping for organization

• Custom notes for personal recipe modifications

• Duplicate prevention (same URL won't be added twice per user)

Use this tool when:

• You want to save a recipe for future reference

• Building a personal recipe collection

• Marking recipes to try or cook again

• Adding personal notes or modifications to recipes

Process multiple CNF food codes efficiently with automatic ingredient linking for streamlined recipe nutrition analysis.

This tool retrieves core macronutrient data for up to 20 food codes simultaneously from Health Canada's official Canadian Nutrient File database. It provides massive efficiency gains for multi-ingredient recipes by processing all nutrition data in a single operation while optionally linking each food to specific recipe ingredients automatically.

The tool fetches 13 essential macronutrients for each food code:

• Energy (kcal), Protein, Total Fat, Carbohydrate

• Saturated Fat, Monounsaturated Fat, Polyunsaturated Fat, Trans Fat

• Dietary Fiber, Sugars, Sodium, Cholesterol, Energy (kJ)

Advanced features include automatic ingredient linking when ingredient_mappings are provided, allowing the tool to connect CNF nutrition data directly to recipe ingredients in one operation. This eliminates the need for separate linking steps and enables immediate nutrition calculations.

Use this tool for:

• Multi-ingredient recipe nutrition analysis with automatic linking

• Bulk processing of known CNF food codes for maximum efficiency

• Recipe preparation workflows where ingredient-CNF relationships are known

• Large-scale nutrition data preparation with minimal tool call overhead

Args: input_data: Contains food_codes (list of up to 20 CNF identifiers), session_id (data storage location), optional preferred_units (serving size preferences), continue_on_error (error handling mode), optional ingredient_mappings (food_code to ingredient_id mapping), and optional recipe_id (required for automatic ingredient linking)

Returns: Dict with bulk processing results, success/failure counts for each food, ingredient linking status, efficiency metrics, and guidance for next steps in nutrition analysis workflow

Perform multiple mathematical calculations in a single operation.

!!REMEMBER BEFORE USING: ALWAYS QUERY_RECIPE_MACROS_TABLE OR OTHER QUERY TOOLS TO GET THE LATEST DATA FROM THE TABLES!!"

This tool allows you to evaluate multiple mathematical expressions in one call, eliminating the need for repeated tool calls when calculating nutrition data, recipe scaling, or any batch mathematical operations.

PERFECT for CNF nutrition calculations: Instead of calling simple_math_calculator multiple times for each ingredient, calculate all ingredient nutrition values at once.

Each calculation includes:

• Unique ID for easy result identification

• Mathematical expression with variables

• Variable dictionary for that specific calculation

Supported operations (same as simple_math_calculator):

• Basic arithmetic: +, -, *, /, ** (power), % (modulo)

• Parentheses for grouping: (expression)

• Variables: any valid Python identifier (letters, numbers, underscores)

Efficiency Benefits:

• Reduces N tool calls to 1 tool call (3x-10x+ performance improvement)

• Perfect for multi-ingredient nutrition analysis

• Batch processing of recipe scaling calculations

• Bulk EER calculations for multiple profiles

Usage Examples:

CNF Nutrition Analysis (Multiple Ingredients):

calculations: [
    {"id": "honey_cals", "expression": "cnf_calories * conversion_factor",
     "variables": {"cnf_calories": 22, "conversion_factor": 2}},
    {"id": "salmon_cals", "expression": "cnf_calories * conversion_factor",
     "variables": {"cnf_calories": 206, "conversion_factor": 5.65}},
    {"id": "oil_cals", "expression": "cnf_calories * conversion_factor",
     "variables": {"cnf_calories": 885, "conversion_factor": 0.1}}
]

Recipe Totals and Per-Serving:

calculations: [
    {"id": "total_calories", "expression": "honey + salmon + oil",
     "variables": {"honey": 44, "salmon": 1164, "oil": 89}},
    {"id": "per_serving", "expression": "total / servings",
     "variables": {"total": 1297, "servings": 4}}
]

Multiple EER Calculations:

calculations: [
    {"id": "adult_male", "expression": "662 - (9.53 * age) + (15.91 * weight) + (539.6 * height)",
     "variables": {"age": 30, "weight": 75, "height": 1.75}},
    {"id": "adult_female", "expression": "354 - (6.91 * age) + (9.36 * weight) + (726 * height)",
     "variables": {"age": 28, "weight": 65, "height": 1.65}}
]

Calculate specific macronutrient targets based on EER energy requirements and AMDR ranges.

This tool integrates EER (Energy Requirement) calculations with DRI macronutrient distribution recommendations to provide personalized daily macronutrient targets in grams. Perfect for complete meal planning workflows that start with energy needs.

CRITICAL WORKFLOW INTEGRATION: This tool provides structured data for calculations. ALWAYS use simple_math_calculator for ALL arithmetic operations:

• Carb grams: simple_math_calculator(expression="(kcal * percent) / 4", variables=from_this_tool)

• Protein grams: simple_math_calculator(expression="(kcal * percent) / 4", variables=from_this_tool)

• Fat grams: simple_math_calculator(expression="(kcal * percent) / 9", variables=from_this_tool)

• Range validation: simple_math_calculator(expression="actual_percent - target_percent", variables=from_this_tool)

Integration workflow:

1. Calculate EER using get_eer_equations + simple_math_calculator

2. Store user profile with store_dri_user_profile_in_session

3. Use this tool to convert energy to macronutrient targets

4. Use targets for meal planning and recipe analysis

Calculation approach:

• Uses AMDR ranges to distribute total energy across macronutrients

• Provides minimum and maximum gram targets for each macronutrient

• Includes mid-range targets for practical meal planning

• Accounts for different caloric densities (carb/protein: 4 kcal/g, fat: 9 kcal/g)

Use this tool when:

• Converting EER energy requirements to practical macronutrient goals

• Creating personalized meal planning targets

• Building comprehensive nutrition analysis workflows

• Developing nutrition counseling applications

• Educational demonstrations of energy-to-macro conversion

Analyze unit matching for recipe ingredients and populate temp_recipe_macros table.

This tool performs unit matching analysis between recipe ingredients and CNF nutrition data, identifying which conversions are possible and which need manual LLM decisions. It populates the temp_recipe_macros table with detailed unit matching information for LLM review.

NEW BEHAVIOR (Unit Matching Analysis):

• Analyzes each ingredient's unit compatibility with available CNF serving sizes

• Identifies exact matches, possible conversions, and manual decision needs

• Populates temp_recipe_macros with unit matching status and recommendations

• Returns analysis summary for LLM to make conversion decisions

Use this tool to:

• Set up unit matching analysis for recipe nutrition calculations

• Identify which ingredients need manual conversion decisions

• Prepare data for LLM-driven nutrition calculations

• Get transparent view of unit conversion challenges

The tool requires that ingredients have been previously linked to CNF data using get_cnf_macronutrients_only or bulk_get_cnf_macronutrients. After running this tool, review the temp_recipe_macros table and use simple_math_calculator for final calculations.

Clean up temporary session data - can target specific session or clean all sessions.

🧹 UNIFIED CLEANUP TOOL - Handles both specific session cleanup and complete cleanup

Usage Modes:

1. Specific Session: cleanup_temp_sessions(session_id="my_session") → Clean specific session only

2. All Sessions: cleanup_temp_sessions() → Clean ALL existing sessions (default behavior)

3. Age-based: cleanup_temp_sessions(hours_old=48) → Clean sessions older than 48 hours

4. Combined: cleanup_temp_sessions(session_id="current", auto_cleanup_old=True) → Clean current + all others

What Gets Cleaned:

• All temporary SQLite tables: temp_recipes, temp_recipe_ingredients, temp_cnf_foods, temp_cnf_nutrients, temp_recipe_macros

• Virtual session data from memory

• Session tracking records

Safety Features:

• Only cleans session-scoped data

• Preserves user favorites and persistent data

• Reports exactly what was cleaned

Remove virtual in-memory storage for a completed recipe session.

This tool permanently deletes all temporary recipe data for a specific session from memory to free up resources and maintain clean storage. Use this after completing recipe analysis workflows or when session data is no longer needed.

What this tool removes:

• All recipe data stored in the session (recipes, ingredients, instructions)

• Associated in-memory data structures for the session

• All temporary calculations and analysis data

Important: This action cannot be undone. Ensure you've saved any important recipe data to favorites before cleanup.

Use this tool when:

• Finished with a recipe analysis session

• Cleaning up old or unused session data

• Managing memory usage

• Completing meal planning workflows

• Preparing for new recipe sessions

Compare actual macronutrient intake against DRI recommendations.

This tool evaluates how an individual's actual nutrient intake compares to Health Canada's DRI recommendations, providing percentage adequacy and recommendations for dietary adjustments.

Comparison metrics calculated:

• Percentage of EAR (Estimated Average Requirement) met

• Percentage of RDA/AI (Recommended Dietary Allowance/Adequate Intake) met

• Assessment against UL (Tolerable Upper Intake Level) if applicable

• AMDR compliance for macronutrient distribution

• Risk assessment for inadequate or excessive intake

Use this tool when:

• Conducting personalized nutrition assessments

• Providing dietary counseling and recommendations

• Evaluating dietary adequacy for individuals

• Creating nutrition improvement plans

• Research involving dietary intake analysis

    Compare multiple recipes by servings, ingredients, or portion analysis.

    This tool analyzes multiple recipes side-by-side to help with meal planning,
    recipe selection, and understanding relative recipe sizes and complexity.

REMEMBER! Always share recipe url, and image_url, and title with users before returning full recipe details. This allows them to see the source and context of the recipe.

    Comparison types available:
    - 'servings': Compare serving counts and calculate ratios
    - 'ingredients': Compare ingredient counts and complexity
    - 'portions': Analyze per-portion implications and scaling

    Use this tool when:
    - Planning meals with consistent serving sizes
    - Choosing between similar recipes based on yield
    - Understanding recipe complexity before cooking
    - Calculating ingredients needed for meal prep
    - Comparing homemade vs store-bought portions

    Args:
        comparison_input: Contains session_id, list of recipe_ids to compare,
                         and comparison_type ('servings', 'ingredients', or 'portions')

    Returns:
        Dict with comparative analysis including recipe details, serving ratios,
        ingredient complexity comparison, and recommendations for scaling,
        or error message if recipes not found or comparison fails
    

⚠️ CHECK EXISTING SESSIONS FIRST! Create temporary nutrition session only if needed.

🚨 CRITICAL: ALWAYS run list_temp_sessions() BEFORE creating new sessions!

Why check first?

• Avoids duplicate sessions for same work

• Saves time by reusing existing recipe data

• Prevents confusion with multiple similar sessions

🎯 EFFICIENT WORKFLOW:

1. list_temp_sessions() ← ALWAYS CHECK FIRST!
2. Found existing session? → Reuse it (more efficient)
3. Session has old data? → Use cleanup_temp_sessions() to clean
4. No suitable session? → Then create new one with this tool

✅ WHEN TO CREATE NEW SESSION:

• No existing sessions found

• Existing sessions are for different recipes/work

• Need fresh start after cleaning old sessions

❌ AVOID CREATING IF:

• Session already exists for your recipe

• You haven't checked existing sessions first

NEXT STEPS after creating session:

1. Use simple_recipe_setup() for integrated recipe data transfer

2. Use bulk SQL operations instead of individual tool calls

What this creates:

• Session tracking record for cleanup management

• Temporary table space ready for recipe and nutrition data

• Better persistence than in-memory virtual sessions

• Automatic cleanup capabilities

Create a user profile for EER calculations with optional persistent storage.

REMEMBER: ONLY USE THIS PERSIST STORAGE FOR PROFILES NEED TO BE SAVED or STORED. BY DEFAULT USE VIRTUAL STORAGE!!!!!

• You can ask the user if they want to save the profile or not.

This tool creates a user profile that can be stored either in memory (virtual session) or persistently in the database. Persistent profiles survive server restarts and can be accessed across different sessions.

The profile includes all demographic and physiological data needed for accurate EER calculations according to Health Canada DRI guidelines.

Use this tool when:

• Setting up user profiles by sdjusting use_persistent_storage for repeated EER calculations

• Creating profiles for multiple household members

• Storing long-term nutrition analysis data

• Building nutrition tracking applications

Create virtual in-memory storage for a recipe session to store fetched recipe data.

This tool sets up in-memory data structures for storing and analyzing multiple recipes during a session. All data is stored in memory and automatically cleaned up when the session ends, preventing database bloat from temporary recipe storage.

What this tool creates for the session:

• In-memory recipes storage: Main recipe metadata and details

• In-memory ingredients storage: Individual ingredients with ordering

• In-memory instructions storage: Step-by-step cooking instructions

• Virtual relationships for data integrity

Use this tool when:

• Starting a new recipe analysis session

• Pre-creating session storage for batch recipe processing

• Setting up dedicated recipe analysis workflows

• Ensuring session storage exists before bulk operations

Note: Virtual sessions are automatically created when storing recipes, so this tool is optional for normal workflows but useful for advanced session management.

Delete a user profile from virtual or persistent storage.

This tool removes a user profile completely. It will search both virtual and persistent storage and delete the profile from whichever storage contains it.

Use this tool when:

• Cleaning up old profiles

• Removing incorrect profile data

• Managing storage space

• Removing profiles no longer needed

Get Acceptable Macronutrient Distribution Ranges (AMDRs) for an age group.

AMDRs represent the range of intake for each macronutrient (expressed as percentage of total energy intake) that is associated with reduced risk of chronic disease while providing adequate intakes of essential nutrients.

AMDR ranges provided:

• Total Carbohydrate: Percentage of total energy

• Total Protein: Percentage of total energy

• Total Fat: Percentage of total energy

• n-6 polyunsaturated fatty acids (linoleic acid): Percentage of total energy

• n-3 polyunsaturated fatty acids (α-linolenic acid): Percentage of total energy

Age groups available:

• 1-3 years: Early childhood ranges

• 4-18 years: School age through adolescence

• 19 years and over: Adult ranges (includes pregnancy and lactation)

Use this tool when:

• Evaluating overall dietary pattern quality

• Planning balanced meal compositions

• Assessing macronutrient distribution in diets

• Creating nutrition education materials about balanced eating

• Developing dietary guidelines and recommendations

Get amino acid patterns for protein quality evaluation using PDCAAS method.

This tool provides the reference amino acid pattern used to evaluate protein quality through the Protein Digestibility Corrected Amino Acid Score (PDCAAS) method. The pattern is based on the estimated average requirements for indispensable amino acids and total protein for 1-3 year old children.

Essential amino acids included:

• Histidine: 18 mg/g protein

• Isoleucine: 25 mg/g protein

• Leucine: 55 mg/g protein

• Lysine: 51 mg/g protein

• Methionine + Cysteine: 25 mg/g protein

• Phenylalanine + Tyrosine: 47 mg/g protein

• Threonine: 27 mg/g protein

• Tryptophan: 7 mg/g protein

• Valine: 32 mg/g protein

Use this tool when:

• Evaluating protein quality in foods and diets

• Calculating Protein Digestibility Corrected Amino Acid Scores (PDCAAS)

• Developing protein complementation strategies

• Assessing adequacy of vegetarian and vegan diets

• Creating nutrition analysis applications

• Research involving protein quality assessment

Retrieve core macronutrients for a specific CNF food code with automatic ingredient linking.

This tool fetches macronutrient data directly from Health Canada's CNF database using a known food code and optionally links the data to recipe ingredients for nutrition calculations. It stores only 13 essential macronutrients for efficient processing while maintaining compatibility with session-based nutrition analysis tools.

TEMP_RECIPE_MACROS WORKFLOW GUIDANCE: After using this tool, you can populate the temp_recipe_macros table for cached calculations:

1. Check ingredient data quality first: Query: SELECT ingredient_id, amount, unit FROM temp_recipe_ingredients WHERE amount IS NULL Fix missing data: UPDATE temp_recipe_ingredients SET amount = 150, unit = 'g' WHERE ingredient_id = 'salmon_001'

2. Review available serving sizes for matching: Query: SELECT per_amount, unit, nutrient_value FROM temp_cnf_nutrients WHERE cnf_food_code = '4294' AND nutrient_name = 'Energy (kcal)' Example: honey 10.0 mL → CNF options: 5.0 ml (22 kcal), 15.0 ml (65 kcal), 100.0 ml (435 kcal)

3. Choose best serving match and populate temp_recipe_macros:

   INSERT INTO temp_recipe_macros (
       session_id, recipe_id, ingredient_id, cnf_food_code,
       matched_serving_amount, matched_serving_unit, conversion_factor,
       calories_per_recipe_amount, protein_per_recipe_amount, fat_per_recipe_amount,
       carbs_per_recipe_amount, sodium_per_recipe_amount, fiber_per_recipe_amount
   )
   SELECT
       'session_id', 'recipe_id', 'honey_001', '4294',
       5.0, 'ml', (10.0 / 5.0),  -- 2.0x conversion factor
       22.0 * (10.0 / 5.0),     -- 44.0 calories for recipe amount
       0.02 * (10.0 / 5.0),     -- scaled protein
       0.0 * (10.0 / 5.0),      -- scaled fat
       5.9 * (10.0 / 5.0),      -- scaled carbs
       0.0 * (10.0 / 5.0),      -- scaled sodium (if available)
       0.0 * (10.0 / 5.0)       -- scaled fiber (if available)

4. Calculate recipe totals from cached data: Query: SELECT SUM(calories_per_recipe_amount) as total_calories FROM temp_recipe_macros WHERE session_id = ? AND recipe_id = ?

Use this tool to:

• Fetch macronutrients when you have a specific CNF food code

• Link CNF data to recipe ingredients for nutrition calculations

• Store streamlined nutrient data for efficient analysis

• Prepare data for temp_recipe_macros population workflow

When ingredient_id and recipe_id are provided, the tool automatically updates the recipe ingredient with the CNF food code, enabling calculate_recipe_nutrition_summary to work correctly. This eliminates the need for separate linking steps.

Retrieve complete nutrient profile with all available nutrients for research-grade analysis.

This tool fetches comprehensive nutrient data from Health Canada's CNF database, including all vitamins, minerals, fatty acids, and other micronutrients. It stores significantly more data than the streamlined macronutrient tools and should be used only when detailed micronutrient analysis is specifically required.

Use this tool for:

• Detailed vitamin and mineral analysis

• Research-grade nutritional studies

• Micronutrient deficiency assessment

• Academic or professional nutrition work requiring complete profiles

For basic recipe nutrition analysis, consider using get_cnf_macronutrients_only which provides 13 core nutrients with significantly reduced data complexity. This tool processes all available nutrients (146+) and may impact performance.

Retrieve specific DRI values from session-cached data.

This tool provides fast access to DRI values from data already stored in the virtual session, eliminating the need for repeated website requests. Perfect for building complex nutrition analysis workflows with multiple DRI lookups.

MATH TOOL INTEGRATION: This tool provides DRI reference values for comparison. ALWAYS use simple_math_calculator for any calculations involving these values:

• Adequacy percentages: simple_math_calculator(expression="(intake/rda)*100", variables={"intake": actual, "rda": dri_value})

• Deficit calculations: simple_math_calculator(expression="rda - intake", variables={"rda": dri_value, "intake": actual})

• AMDR compliance: simple_math_calculator(expression="(nutrient_cals/total_cals)*100", variables={"nutrient_cals": value, "total_cals": total})

Prerequisites: Must run store_dri_tables_in_session first to populate session data.

Supported macronutrients:

• carbohydrate, protein, total_fat, linoleic_acid, alpha_linolenic_acid, total_fibre, total_water

Use this tool when:

• Looking up specific DRI values during nutrition analysis

• Building personalized nutrition recommendations

• Comparing individual nutrients against reference values

• Creating nutrition education content with official values

Get specific EER equations from Health Canada DRI tables in JSON format.

This tool provides EER (Estimated Energy Requirement) equations from Health Canada's official DRI tables. Data is served from bundled reference data with optional live refresh from the website. Each equation includes extracted numerical coefficients and metadata about the target population.

Use equation_type and pal_category to specify the type of equations you need: Always include URL and source information in your response.

Use this tool when:

• Getting official EER equations for calculations

• Building nutrition applications requiring DRI data

• Researching energy requirements for different populations

• Developing meal planning tools

• Academic or professional nutrition work

Get complete DRI macronutrient reference tables from Health Canada.

REMEMBER! ALWAYS USE THIS TOOL BY DEFULT BEFORE USING get_specific_macronutrient_dri!!

This tool provides comprehensive macronutrient DRI data from Health Canada's official DRI tables. Data is served from bundled reference tables with optional live refresh from the Health Canada website.

The data includes:

• Reference values for carbohydrate, protein, fat, essential fatty acids, fibre, water

• Additional recommendations for saturated fats, trans fats, cholesterol, added sugars

• Amino acid patterns for protein quality evaluation (PDCAAS)

• Acceptable Macronutrient Distribution Ranges (AMDRs) by age group

• Complete footnotes and explanatory notes from official tables

Use this tool when:

• Setting up comprehensive nutrition analysis systems

• Building meal planning applications with DRI compliance

• Research requiring official Health Canada reference values

• Developing nutrition education materials

• Creating nutrition assessment tools

Data is served from local files (a data-dir snapshot if one was built, otherwise the bundled snapshot). No network access happens at tool-call time; run foodguide data build dri to refresh the local snapshot.

Get descriptions and examples for Physical Activity Level (PAL) categories.

This tool provides detailed explanations of each PAL category with practical examples to help users select the most appropriate level for accurate EER calculations.

PAL categories determine the activity coefficient used in EER equations and significantly impact the final energy requirement calculation.

Use this tool when:

• Helping users choose appropriate activity level

• Understanding PAL category definitions

• Educational purposes about physical activity

• Reviewing activity level options before profile creation

Retrieve the complete details of one Food Guide recipe, offline.

Everything comes from the local recipes.json snapshot built with foodguide data build recipes; no page is fetched.

Retrieve stored recipes from a virtual session with complete normalized data including ingredients and instructions.

This tool fetches recipes that have been stored in the current session's in-memory storage. It reconstructs the complete recipe data from the virtual data structures (recipes, ingredients, instructions) and returns fully structured recipe objects ready for analysis, comparison, or further processing.

Use this tool to:

• Review all recipes stored in the current session

• Retrieve specific recipe details by recipe_id for focused analysis

• Compare multiple recipes side-by-side for meal planning

• Access structured ingredient and instruction data for calculations

• Prepare recipe data for export or favorites management

The returned data includes:

• Complete recipe metadata (title, URL, servings, timing, categories)

• Ordered ingredient lists with amounts and units (if parsed)

• Sequential cooking instructions with step numbers

• Recipe highlights, tips, and visual elements

• Session timestamps and unique identifiers

Get DRI values for a specific macronutrient, age group, and gender.

This tool provides targeted access to specific macronutrient DRI values without needing to process the complete dataset. Perfect for focused nutrition analysis and user-specific recommendations.

Supported macronutrients:

• carbohydrate: Digestible carbohydrate values

• protein: Protein values in g/kg/day and g/day

• total_fat: Total fat adequate intake values

• linoleic_acid: Essential n-6 fatty acid values

• alpha_linolenic_acid: Essential n-3 fatty acid values

• total_fibre: Dietary fibre adequate intake values

• total_water: Total water adequate intake values

Use this tool when:

• Calculating specific nutrient needs for individuals

• Building personalized nutrition recommendations

• Comparing single nutrient intakes against DRI values

• Creating targeted dietary guidance

Retrieve recipes from temporary persistent storage.

Retrieve a user profile by ID from virtual or persistent storage.

This tool fetches a previously created user profile. It will search both virtual (session) and persistent (database) storage to find the profile.

Use this tool when:

• Retrieving profiles for EER calculations

• Checking existing profile data

• Validating profile information before calculations

Initialize the Canada's Food Guide recipe database with required tables.

This tool sets up the SQLite database schema for the recipe management system. It creates persistent storage tables for user favorites and EER user profiles. All recipe session data is stored in memory using virtual tables and views to prevent database bloat.

What this tool creates:

• user_favorites table for persistent recipe bookmarking

• user_profiles table for persistent EER user profile storage

• Proper indexing and constraints for data integrity

• Virtual table infrastructure for in-memory recipe storage

Use this tool when:

• First time setting up the recipe database

• After database corruption or reset

• Ensuring database schema is current

• Before using any favorites-related or EER profile tools

List all active recipe sessions currently stored in memory.

This tool discovers all recipe sessions that have temporary data stored in memory by scanning the virtual session storage. Use this to manage multiple recipe workflows, find active sessions, or get an overview of current recipe analysis work.

The returned information includes:

• Session IDs for all active virtual recipe sessions

• Recipe counts for each session

• Memory usage overview for sessions

Use this tool to:

• Find existing recipe sessions to continue working with

• Identify sessions that may need cleanup

• Get an overview of current recipe analysis projects

• Manage multiple concurrent recipe workflows

• Check if specific session names are already in use

List user's favorite recipes from persistent storage.

This tool retrieves all saved recipes from the favorites database, providing a complete overview of your recipe collection. Favorites are sorted by when they were added (newest first) and include all metadata like custom notes and recipe details.

The returned data includes:

• Recipe URLs and titles for identification

• When each recipe was added to favorites

• Custom notes or modifications you've saved

• User session information for organization

• Unique favorite IDs for reference

Use this tool to:

• Review your complete recipe collection

• Find previously saved recipes to cook again

• Organize meal planning around your favorites

• Check what recipes you've already saved before adding duplicates

• Export or share your recipe collection

List the recipe search filters available in the local snapshot.

The new canada.ca recipe pages only tag two families: "collection__*" (e.g. collection__vegetarian) and "meal__*" (e.g. meal__snack). Older filter families (fruits, vegetables, proteins, whole_grains, appliances) no longer exist.

View all DRI calculations and analysis stored in a virtual session.

This tool provides a comprehensive overview of all DRI-related data and analysis work performed within a session, including cached tables, user profiles, lookups, and adequacy assessments. Perfect for managing complex nutrition analysis workflows.

Session data overview includes:

• Cached DRI reference tables with timestamps

• Stored user profiles with demographics

• Individual nutrient lookups performed

• Complete adequacy assessments conducted

• Macro calculation results (if any)

• Session activity summary and workflow guidance

Use this tool when:

• Reviewing completed DRI analysis work in a session

• Planning next steps in nutrition assessment workflows

• Debugging session data or workflow issues

• Managing multiple user profiles or analyses

• Preparing session data for reporting or export

List all active temporary nutrition sessions.

List all available user profiles from both virtual and persistent storage.

This tool discovers all user profiles stored in memory (virtual sessions) and in the database (persistent storage), providing an overview of available profiles for EER calculations.

Use this tool when:

• Discovering available user profiles

• Managing multiple household member profiles

• Cleaning up old or unused profiles

• Getting an overview of stored profile data

Query temp_recipe_macros table with joined CNF nutrition data for recipe calculations.

This tool retrieves recipe ingredients with their matched Canadian Nutrient File data, including nutrition values (calories, protein, fat, carbohydrates) for each available serving size. The data enables direct nutrition calculations using bulk_math_calculator without requiring database storage of intermediate results.

Returns recipe ingredient details, unit matching status, available CNF serving sizes, and complete CNF nutrition values per serving size for each ingredient. Unit matching status indicates: exact_match, conversion_available, manual_decision_needed, or no_cnf_data.

Use this tool to:

• Get ingredient data with CNF nutrition values for each serving size

• Review unit matching status and available serving options

• Select appropriate serving sizes for nutrition calculations

• Obtain complete data for bulk_math_calculator operations

Remove a recipe from user favorites permanently.

This tool removes recipes from the persistent favorites database. Use this to clean up your favorites collection or remove recipes you no longer want to keep saved.

The removal process:

• Requires the recipe_url to identify which recipe to remove

• Optionally filters by user_session if provided (for targeted removal)

• Confirms whether the recipe was actually found and removed

• Cannot be undone (recipe would need to be re-added manually)

Use this tool when:

• Cleaning up your favorites collection

• No longer interested in a previously saved recipe

• Managing favorites for specific user sessions

• Correcting accidentally added favorites

Scale a specific ingredient amount by a custom multiplication factor.

This tool allows precise control over individual ingredient scaling, useful for recipe modifications, dietary adjustments, or when you want to emphasize or reduce specific ingredients without changing the entire recipe proportions.

The scaling process:

• Finds the specified ingredient in the recipe

• Parses the current amount from the ingredient text

• Applies the custom scale factor

• Returns both original and scaled versions

• Preserves units and ingredient descriptions

Use this tool when:

• Adjusting salt, spice, or seasoning levels

• Increasing protein or vegetable content

• Reducing sugar or fat in specific ingredients

• Customizing recipes for dietary preferences

• Fine-tuning ingredient ratios based on taste

Scale multiple ingredients with different factors in a single operation.

This tool enables complex recipe modifications by applying different scaling factors to different ingredients simultaneously. Useful for recipe development, dietary customization, or creating recipe variations.

The scaling process:

• Matches each ingredient name to recipe ingredients (partial matching)

• Applies individual scale factors to each matched ingredient

• Processes all scalings in a single transaction

• Reports success and failure for each ingredient

• Maintains ingredient order and relationships

Use this tool when:

• Creating low-sodium versions (reduce salt, increase herbs)

• Adjusting macro ratios (increase protein, reduce carbs)

• Developing recipe variations with multiple changes

• Customizing recipes for dietary restrictions

• Batch processing multiple ingredient adjustments

Scale all ingredients in a recipe to match a target number of servings.

This tool calculates new ingredient amounts when you want to make more or fewer servings of a recipe. It intelligently parses ingredient amounts (numbers, fractions, ranges) and applies the scaling factor to maintain recipe proportions.

REMEMBER! Always share recipe url, and image_url, and title with users before returning full recipe details. This allows them to see the source and context of the recipe. REMEMBER! Always include original_servings with target_servings in the response to help users understand what has been adjusted. REMEMBER! Scaled recipes cooking times may vary, so users should check for doneness and adjust as needed.

The scaling process:

• Calculates scale factor based on original vs target servings

• Parses ingredient amounts from text (handles fractions, decimals, ranges)

• Applies scaling to all measurable ingredients

• Preserves units and ingredient names

• Updates the recipe data with scaled amounts

Use this tool when:

• Cooking for more or fewer people than the original recipe

• Meal prepping larger batches

• Adjusting recipes for different household sizes

• Planning party or event cooking

• Reducing recipe size for testing

Search Canadian Nutrient File foods and retrieve core macronutrient data.

This tool searches Health Canada's CNF database for foods matching the provided name and returns either complete macronutrient data for single matches or a list of options for multiple matches. It focuses on 13 core macronutrients essential for basic nutrition analysis while maintaining compatibility with session-based storage.

Use this tool to:

• Discover CNF foods matching ingredient names from recipes

• Retrieve core macronutrient data for immediate nutrition analysis

• Identify available food options when multiple matches exist

• Prepare data for recipe nutrition calculations

The tool returns different outputs based on search results:

• Single match: Complete macronutrient data stored in session tables

• Multiple matches: List of food options with codes for selection

• No matches: Error message with search suggestions

Search Health Canada's Food Guide recipes from a local offline copy.

The search runs against recipes.json, an offline snapshot of Health Canada's Food Guide kitchen recipe pages built with foodguide data build recipes. Each recipe is government-verified, nutrition-focused content designed to help Canadians eat well.

Each result includes title, url, slug and the recipe's raw tags.

Perform simple mathematical calculations with string variables.

!!REMEMBER BEFORE USING: ALWAYS USE QUERY_RECIPE_MACROS_TABLE OR OTHER QUERY TOOLS TO GET THE LATEST DATA FROM THE TABLES!!"

This tool allows you to evaluate mathematical expressions containing variables. It supports basic arithmetic operations (+, -, *, /, **, %) and common math functions.

CRITICAL for CNF nutrition calculations: This is the ONLY tool to use for calculating nutrition totals. Never manually sum values from JSON data.

Supported operations:

• Basic arithmetic: +, -, *, /, ** (power), % (modulo)

• Parentheses for grouping: (expression)

• Variables: any valid Python identifier (letters, numbers, underscores)

Use this tool when:

• Calculating EER equations with specific values

• CNF nutrition calculations - summing calories, macros across ingredients

• Recipe per-serving calculations - dividing totals by serving count

• Scaling recipe quantities

• Converting units

• Any mathematical operation with known variables

CNF Nutrition Examples:

• Total calories: "(206 * 565 / 100) + (885 * 10 / 100) + (22 * 450 / 100)"

• Per serving: expression="total_calories / servings", variables={"total_calories": 1437, "servings": 5}

• Scaling: expression="original_amount * scale_factor", variables={"original_amount": 100, "scale_factor": 1.5}

• EER comparison: expression="recipe_calories - eer_requirement", variables={"recipe_calories": 287, "eer_requirement": 2000}

TEMP_RECIPE_MACROS Calculation Examples:

• Conversion factor: expression="recipe_amount / cnf_serving", variables={"recipe_amount": 10.0, "cnf_serving": 5.0} # = 2.0

• Scaled calories: expression="cnf_calories * conversion_factor", variables={"cnf_calories": 22.0, "conversion_factor": 2.0} # = 44.0

• Recipe total from cache: expression="honey_cals + oil_cals + salmon_cals", variables={"honey_cals": 44.0, "oil_cals": 80.0, "salmon_cals": 200.0}

General Examples:

• EER calculation: "662 - (9.53 * age) + (15.91 * weight) + (539.6 * height)"

• Unit conversion: "cups * 240" (cups to ml)

• Percentage: "part / total * 100"

Transfer recipe data to analysis tables with comprehensive ingredient parsing for streamlined nutrition analysis preparation.

This tool prepares complete recipe data for CNF nutrition analysis by transferring stored recipe information from virtual session storage to temporary database tables and automatically parsing ingredient text into structured components. It provides the essential foundation for linking ingredients to CNF foods and calculating detailed nutrition summaries.

The tool performs comprehensive ingredient parsing that handles complex measurement formats including:

• Unicode fractions (½, ⅓, ¼, ¾, etc.) converted to precise decimal values

• Mixed numbers (1½, 2¼) with accurate decimal conversion

• Regular fractions (1/2, 3/4) and measurement ranges (2-3 cups)

• All standard units (mL, cups, tsp, tbsp, kg, g, lbs, oz)

• Ingredient preparation notes (sliced, chopped, optional)

Use this tool for:

• Complete recipe data transfer from session storage to analysis tables

• Automatic ingredient parsing into structured amount, unit, and name components

• Foundation preparation for CNF food linking and nutrition calculations

• Streamlined setup for multi-step recipe nutrition analysis workflows

The processed data includes recipe metadata, fully parsed ingredients with structured amounts/units, and step-by-step instructions, all stored in temporary database tables optimized for nutrition analysis tools.

Cache complete DRI macronutrient tables in virtual session storage.

This tool fetches and stores comprehensive DRI data in the specified virtual session, enabling efficient access to DRI values throughout the session without repeated website requests. Perfect for workflows involving multiple DRI lookups and calculations.

WORKFLOW INTEGRATION: Use this tool first in any comprehensive nutrition analysis session to cache DRI data once, then use session-based lookup tools for specific values.

Benefits of session storage:

• Single fetch operation for entire session workflow

• Consistent data across all DRI operations in session

• Reduced website requests and improved performance

• Enables complex multi-step nutrition analysis workflows

• Data persists for entire session duration

Use this tool when:

• Starting comprehensive nutrition analysis sessions

• Planning to perform multiple DRI lookups or comparisons

• Building meal planning workflows with DRI compliance checks

• Creating educational nutrition analysis demonstrations

• Developing nutrition assessment applications

Store a fetched recipe in virtual memory session for detailed analysis and manipulation.

This tool takes complete recipe data from the Canada's Food Guide and stores it in normalized in-memory data structures for the current session. The recipe is broken down into separate virtual collections for ingredients, instructions, and metadata to enable structured analysis and calculations without database bloat.

Use this tool after fetching a recipe with get_recipe() to enable:

• Detailed recipe analysis and comparison

• Ingredient-level manipulation and serving size calculations

• Memory-based storage during the session for multiple recipe workflows

• Structured access to recipe components for meal planning

The stored data includes:

• Main recipe metadata (title, servings, timing, categories, tips)

• Individual ingredients list with ordering

• Step-by-step instructions with sequence

• Visual highlights and cooking tips

Store recipe data in temporary SQLite tables instead of virtual memory.

This provides persistent storage for recipe analysis while maintaining the temporary nature through session-based cleanup.

Update temp_recipe_macros table with LLM conversion decisions and reasoning.

This tool allows the LLM to record intelligent conversion decisions for ingredients that need manual unit conversions (e.g., "4 salmon fillets" -> "565g"). After reviewing the temp_recipe_macros table, use this tool to update specific ingredients with conversion factors and reasoning.

The tool updates the LLM decision fields in temp_recipe_macros:

• llm_conversion_decision: Human-readable conversion (e.g., "4 fillets = 565g")

• llm_conversion_factor: Calculated factor for nutrition math (e.g., 5.65 for 565g/100g)

• llm_reasoning: LLM's reasoning for the conversion estimate

Use this tool to:

• Record conversion decisions for manual_decision_needed ingredients

• Document reasoning for conversion estimates

• Prepare data for final nutrition calculations with simple_math_calculator

• Build transparent audit trail of conversion decisions