CalorieGoals

List everything the user logged on a given day: food, drinks and exercise. Use it to answer "what did I eat today?" or to check something was recorded.

get_day

What to buy for the days that already have a meal plan assigned. Adds up every planned day in the range: 4 oz of oatmeal on three of them is 12 oz of oatmeal. Recipes and groups come apart into their ingredients, scaled by the servings or multiplier the plan holds, so the list names food rather than dishes. Where a plan offers alternatives the amount covers whichever one is picked, and each line says which option it owes its size to. Defaults to the next seven days including today. A line flagged cooked_weight is a food named as already prepared, so the amount is its weight after cooking — plans hold what gets eaten. Say so: somebody buying 600 g of "rice, cooked" needs roughly a third of that dry. Two more flags appear only when they are true and both mean "do not trust this number": grams_unknown, where a food has no usable weight recorded so the total is an undercount rather than a figure; and weight_suspect, where a portion's stored weight contradicts its own unit, so the amount and the grams describe different quantities. Say so rather than reading either number out as fact.

get_grocery_list

Full nutrition and the available portion sizes for one food. Portions are things like "1 cup" or "1 medium", each with its own portion_id. The one flagged is_default comes first and is what the app itself preselects, so it is the right choice when the user has not named a portion.

get_food

The user's calorie goal, macro targets, units, meal categories, timezone and today's date in that timezone. Goals and units only: no name, email, or billing details.

get_profile

The foods this user logs most often, each with the portion and amount they usually pick and the ids log_food needs.

get_frequent_foods

Answer questions like "how many calories do I have left today?", "how am I doing on protein?" or "have I hit my water goal?". Returns totals so far, the goal, and what remains.

get_progress

Totals for a range of days, for questions about a week, a month or a trend, such as "how did I do this month?" or "what is my average?". Returns one row per day plus an average, so it answers in a single call rather than one per day. Pass days for a window ending today, or from and to for an explicit range. Nutrient breakdowns are not included: use get_progress or get_day for one day in detail.

get_history

The meal plan assigned to a day, its items, and which of those items have already been logged from the plan that day. Each item carries an item_id. Answers what the user is meant to eat, and what is left.

get_planned_day

The saved meal plans. A plan is a day of food decided ahead of time, built once and eaten from repeatedly. Gives the plan_id the other plan tools need, how many items each holds, its projected calories and the weekdays it repeats on. With include_items, also every item and its item_id, which is what changing or removing one needs.

list_plans

Saved groups of foods the user logs together, like "my usual breakfast". Gives you the group_id for log_food_group. Without include_items each group reports only how many foods it holds, not which ones; set include_items to name them.

list_food_groups

The user's saved recipes, with calories per serving and the recipe_id that log_recipe needs. Set include_items to also get each recipe's ingredients, which is what answers "what is in my chilli" without logging anything.

list_recipes

Records a food that is not in the database: a homemade dish, or a restaurant meal whose nutrition is known. Unlike log_food, the calorie and nutrient values here are supplied by the caller rather than measured. Also saves the food to the user's My Foods. Nutrients are optional.

log_custom_food

Logs a beer, a glass of wine or a measure of spirits, worked out from how much of it there was and how strong it was. Use this for any alcoholic drink rather than searching for one: a food database holds whichever beers somebody happened to enter, and the calories in a drink follow from its volume and its ABV, so computing beats looking up. Do not use log_custom_food for a drink — this tool names the drink the same way the CalorieGoals apps do, so the same drink stays one food in the user's library instead of becoming two. The ABV is on the label; if the user does not know it, leave it out and a typical strength for the kind is used, and say which was assumed. The style matters for beer and wine because residual sugar is the one part the ABV cannot tell you: a light lager is brewed to have almost none and a malty, full-bodied ale keeps a lot. Choose a beer's style by its body, not by who brewed it: a hop-forward IPA or pale ale from a craft brewery is regular, and heavy is for malty or sweet beers. A beer comes to about fl oz × ABV × (1.63 + 0.4 light, 0.9 regular or 1.2 heavy) calories, so when you know its published calories, pass the style that lands closest.

log_drink

Records a food the user ate, identified by a food_id or fdc_id from search_foods, get_food or get_frequent_foods. Nutrition comes from the food database rather than the caller. Without a portion_id the food's default portion is used; get_food lists the alternatives.

log_food

Log a saved group of foods from list_food_groups all at once, for example their usual breakfast.

log_food_group

Log servings of one of the saved recipes from list_recipes. Use servings 0.25 for a quarter of a serving, 2 for two servings.

log_recipe

Record exercise using an exercise_id from search_exercises. Calories burned are calculated from the exercise and the user's weight, so do not estimate them.

log_exercise

Records what a plan said, without searching for any of it: the plan already names the food, the portion and the amount. Logs one item by item_id, or every not-yet-logged item in one meal, or the whole day. A meal or a whole-day log passes over items already logged from the plan, and any whose food has since been deleted. An item named by item_id is logged whether or not it already was, with a warning when it was.

log_from_plan

Add water to the day's total. Pass a negative number to correct an over-log. One cup is about 240 ml, a pint about 470 ml, a litre 1000 ml.

log_water

Assigns a meal plan to specific dates, or to weekdays it repeats on, or both. A date takes precedence over a weekday, so a plan set for one date shows there even if another plan repeats on that weekday.

assign_plan

Takes one item out of a meal plan. Take the item_id from list_plans with include_items, or from get_planned_day. Nothing else about the plan changes: the days it is on stay as they are, and anything already logged from it stays logged. A plan with no items left is still a plan.

remove_plan_item

Removes one food entry from today or any later day, identified by the entry_id that get_day returns. Any of that day's entries can go, including ones the user added in the app. One entry per call, and days before today are out of reach: the user's history cannot be edited from here, and there is no bulk removal.

remove_entry

Changes a plan itself rather than what is in it: its name, or the calorie target it is being built against. Take the plan_id from list_plans. Leaving a field out leaves it alone. The goal is an indicator shown beside the plan's running total while it is built — it does not change any day's calorie goal and does not affect anything already logged. To change what the plan holds, use add_to_plan, update_plan_item or remove_plan_item.

update_plan

Find an exercise to log, e.g. "running", "yoga". Returns the exercise_id that log_exercise needs. Calories burned are worked out from the exercise, the duration and the user's weight, so you do not need to estimate them.

search_exercises

Finds the entry to record a food against: the USDA database plus the foods this user has saved. Each result carries calories and, where we have them, protein, carbs and fat per 100 g, so a calorie or macro target can be worked out before anything is written. Results carry the ids the logging and plan tools need: a result may have a food_id, an fdc_id, or both. An fdc_id is imported on use by log_food, create_plan and add_to_plan. Results are ordered best match first, so the first item is the strongest candidate unless something later matches the user's wording more exactly. is_yours marks a food the user saved themselves, which ranks above everything else because it is usually the one they mean.

search_foods

Leaves nothing planned on the given dates, or stops a plan repeating on the given weekdays. plan_id is required for weekdays, so another plan's repeat is never removed by mistake; for dates it checks the day holds that plan first.

unassign_plan

Removes the most recent thing you logged for this user within the last 15 minutes, including a recipe or group log, which removes every entry that log created. Anything you did since that logged nothing — saving a recipe, editing a plan — is stepped over rather than blocking it, and the reply says what it stepped over so you can tell the user that part still stands. It cannot affect entries the user made in the app or entries older than 15 minutes. Water is a running total: correct it by logging a negative amount instead. After removing something the user is correcting rather than cancelling, ask what it should have been.

undo_last_entry