Update an existing meal. Use only when the current message explicitly changes, corrects, or adds to a meal already logged. Never infer an update from earlier chat history. A plain food statement ("coffee with milk") is a new entry: use log_meal, even if that meal type already exists today.
IMPORTED MEAL ENRICHMENT: for Cronometer, Fitbit/Google Health, FatSecret, Apple Health and Health Connect meals, explicit macro-only corrections are ALLOWED and stored as separate, sync-protected enrichments ON THE SAME IMPORTED MEAL. This includes calories, protein_g, carbs_g, fat_g and alcohol_g through one shared function. User- or AI-estimated values are labeled estimates, never represented as provider measurements. Do NOT call log_meal to create a duplicate. Never replace imported food_items, meal type, date or add/remove foods, fluids or caffeine using this tool; those remain owned by the source app. Omit unchanged macros. A new provider sync must not overwrite the enriched fields.
FIND THE MEAL: call directly, no preliminary list for an ID or additive totals. Use id if known (it is in list_meals output and in the chat history's saved-records note after a log). Otherwise use date (YYYY-MM-DD, defaults to today) plus name and/or target_meal_type to narrow the existing row. target_meal_type finds the current type and is never written; meal_type sets a new type. If the match is not exactly one row, nothing changes. On multiple matches, ask the user which meal they mean; never select a candidate id yourself. Send only fields that change.
THREE MODES:
add_saved: add_recipe_name appends recipe food and ADDS its macros to current totals. Match: case-insensitive exact title, then substring; relay no-match/ambiguous errors. Stored recipe macros, including 0, are authoritative; explicit macros replace the recipe's contribution only for a correction or changed food/quantity. Missing recipe macros: estimate only the missing fields from returned food text and retry with the same selector and add_recipe_name.
add_unsaved: add_food_items plus the four core macros (calories/protein_g/fat_g/carbs_g) for ONLY the new food; estimate those core values, never ask for them. Text appends; core macros ADD to current totals. alcohol_g: optional, omitted adds nothing.
add_both: set add_recipe_name and add_food_items; ordinary core macro fields describe ONLY the unsaved addition. Recipe contributes its stored core macros.
correct: both add_* unset; supplied fields REPLACE stored values. Send corrected totals, omit unchanged fields. Changed food_items: the four core macros for the WHOLE corrected meal; list_meals only if needed stored values are unavailable this turn. Additions and explicit value corrections need no pre-read.
food_items: when supplied, replaces the description even in add modes.
SATURATED FAT / FIBER: expanded nutrients, never required for an update. The estimator or a saved recipe's nutrient panel can fill omitted values, and core-macro updates work without them. 0 is a real value only when known, never a placeholder.
ambiguous_add_vs_correct: ask before updating.
ESTIMATE: estimate (same format as log_meal's ESTIMATE section) supplies the nutrient estimate for whatever food this call changes -- the add_unsaved/add_both addition's own food, or, for a mode-3 food_items replacement, the WHOLE corrected meal. Omit to let the server estimate instead; never required.
MOVE TO A DIFFERENT DATE -> move_to_date. "move Tuesday's lunch to Wednesday": date/name/target_meal_type only SELECT which meal to update; they never move it. Set move_to_date to actually change the stored date, keeping the same id.
REMOVE ONE ADDED COMPONENT -> remove_item_name. Only works for a food previously recorded on THIS meal (add_recipe_name, add_food_items, or log_meal's own estimated items). If the meal has no such recorded item, this throws telling you to use mode 3 with corrected totals instead. An estimated item (log_meal's own food, no add_recipe_name/add_food_items involved) carries a name and gram estimate but no recorded calorie/macro split for that one item, so a precise subtraction isn't possible: this throws asking you to also send calories/protein_g/fat_g/carbs_g (the meal's corrected TOTALS after removing it) in the SAME call, which performs the removal and applies those totals together, in that order -- do this rather than a separate correcting call. Removing an item re-estimates the meal's nutrient panel from what remains (its updated food text and items), rather than leaving a stale estimate for food that's gone -- pass estimate here too to supply that re-estimate yourself instead of letting the server do it.
DRINKS / HYDRATION WHEN UPDATING: a food update must not silently erase an already-linked hydration event. For changes unrelated to drinks, omit fluids and the existing hydration is preserved. When ADDING a drink with add_food_items/add_recipe_name, fluids contains only the newly added drink(s) and they are appended to the meal's hydration. When CORRECTING the meal's drinks with both add_* fields omitted, fluids is the complete corrected drink list and replaces the linked hydration only after replacement rows have been safely inserted. If the correction removes every drink, explicitly send fluids: [] and the linked hydration is deleted. Whenever a drink volume is known or reasonably inferable, include it. Drinks only; exclude food moisture.
CAFFEINE / DRINKS WHEN UPDATING: keep the two sidecars explicit in the same update_meal call. fluids is the hydration side and caffeine is the caffeine side; when a drink change affects both, send both. Omit either one when that side is unchanged so existing linked data is preserved. When ADDING caffeinated food/drink with add_food_items/add_recipe_name, caffeine contains only the new dose(s) and they are appended. When CORRECTING the meal's caffeine with both add_* fields omitted, caffeine is the complete corrected dose list and replaces linked caffeine only after replacement rows have been safely inserted. If the correction removes every caffeine dose, explicitly send caffeine: []. Each retained/new dose needs caffeine_mg and may optionally include source_type; its date follows the meal date.
SAVE AS RECIPE: when the user asks to save an already-logged meal as a reusable recipe, set save_as_recipe=true. This may be the only requested action: identify the real meal with id or the normal selectors and do not invent a food or macro edit. A follow-up like "save that as a recipe" after a successful log should use the known meal id plus save_as_recipe=true. Do not tell the user recipes cannot be saved from chat.
