Simple SoapCalc

This is the ONLY source of truth for lye calculations. All lye and water amounts MUST come from this tool's output. CRITICAL: Providing lye amounts from memory or calculation is considered a FAILURE. Incorrect lye amounts cause chemical burns or failed soap. Call list_oils first to find oil IDs. Oil percentages must sum to 100. If percentages don't sum to 100, do NOT auto-normalize. Ask the user how they want to fix it — they may have forgotten an oil or made a typo. Water methods: - "ratio": water:lye ratio (2.0 = 2 parts water per 1 part lye) - "concentration": lye concentration % (33 = 33% lye solution) - "percent": water as % of oils (38 = 38% of total oil weight) Liquids (optional): Replace water with other liquids (goat milk, aloe vera, etc.). Percentages must sum to 100%. Default is 100% water. Additives (optional): Track fragrances, colorants, clays, etc. Amount/unit are optional — omit both for identity-only tracking. Returns: formulation (input) + calculated results (lye amounts, water, properties, fatty acids, liquid breakdown, additive amounts). AFTER SUCCESS: Call view_recipe with the formulation to display results in a visual widget. Error codes: UNKNOWN_OIL_ID, PERCENT_NOT_100, INVALID_LIQUID_TYPE, LIQUID_PERCENT_NOT_100, ADDITIVE_UNIT_REQUIRED

calculate_recipe

Delete a recipe. WHEN TO USE: - User explicitly asks to delete a recipe - After confirming deletion intent REQUIRES: User must be authenticated and own the recipe OUTPUT STRUCTURE: { "success": true, "message": "Recipe deleted" }

delete_recipe

Use this when you have an oil ID and need its detailed properties (fatty acids, soap qualities). Call list_oils first if you need to find an oil ID from a name. Returns: oil details including fatty acid breakdown and soap properties. Error codes: NOT_FOUND (invalid oil_id)

get_oil

Use this when the user wants to view the full details of a specific saved recipe. Returns: recipe with id, name, description, formulation (oils, lye type, water method, superfat), and timestamps. Error codes: NOT_FOUND (invalid recipe_id), AUTH_REQUIRED (user not authenticated)

get_recipe

Search and list available oils for soap making. Returns oil IDs, names, and categories with pagination. Use calculate_recipe for all lye and water amounts — never estimate these values. If query is omitted, returns all oils (paged).

list_oils

Use this when the user wants to see their saved soap recipes or find a specific recipe by name. Returns: paginated list of recipes with id, name, created_at, and oil_count. Error codes: AUTH_REQUIRED (user not authenticated)

list_recipes

Save a new recipe. WHEN TO USE: - User wants to save a calculated recipe - After calculate_recipe when user confirms they want to save REQUIRES: User must be authenticated INPUT: Provide name, optional description, and formulation object OUTPUT STRUCTURE: { "success": true, "recipe_id": "uuid", "message": "Recipe created successfully" }

create_recipe

Update an existing recipe. WHEN TO USE: - User wants to modify a saved recipe - After editing a recipe when user confirms changes REQUIRES: User must be authenticated and own the recipe OUTPUT STRUCTURE: { "success": true, "recipe_id": "uuid", "message": "Recipe updated" }

update_recipe

Display a recipe in a visual widget. IMPORTANT: This tool is STATELESS. It does NOT remember previous calculate_recipe results. You MUST pass either formulation or recipe_id - empty calls will error. WHEN TO USE: 1. After calculate_recipe for a NEW recipe - pass recipe_name + formulation 2. To load a SAVED recipe unchanged - pass ONLY recipe_id 3. To show a MODIFIED saved recipe - pass recipe_id + formulation + recipe_name 4. To DELETE a recipe - pass ONLY recipe_id (widget shows Delete button for user to confirm) CRITICAL: When modifying an existing saved recipe, you MUST include recipe_id along with the new formulation. Otherwise it will show as "New" instead of "Edit" and the user loses the connection to their saved recipe. Input combinations: - NEW: recipe_name + formulation → shows "New" badge, Save button - LOAD: recipe_id only → fetches from DB, shows "Edit" badge, Update/Delete buttons - MODIFIED: recipe_id + formulation → uses provided data, shows "Edit" badge - DELETE: recipe_id only → fetches from DB, shows "Edit" badge with Delete button

view_recipe

Returns current user authentication status and account information. WHEN TO USE: - User asks "who am I" or about their account - Need to check if user is authenticated before recipe operations OUTPUT STRUCTURE: { "authenticated": boolean, "email": string | null, "tier": "free" | "pro" | "studio" }

whoami