BetterMenu

View saved version →

---
name: bettermenu
description: Use when the user wants US nutrition numbers or FDA food labelling with BetterMenu: an FDA Nutrition Facts label, or nutrition facts, calories and %DV per serving, for a recipe or batch they paste (in any units), link, want saved, or already have saved, with per-unit numbers for a yield ("calories per bar if it makes 8"); USDA nutrition for one food, branded products included ("how many calories in an apple", "sugar in a granola bar"); comparing two foods ("butter vs margarine, more saturated fat"); an amount in grams ("how many grams is 2 cups of flour"); the US FDA Daily Value for a nutrient ("daily value for sodium"); the FDA serving size for a food type ("what serving size for cookies"); and their saved recipes and custom ingredients. Not for inventing a recipe or method ("give me a banana bread recipe"), meal plans, diet advice, or explaining a term such as %DV.
---

# BetterMenu: US nutrition facts, FDA labels, food data

BetterMenu computes nutrition from amounts, using USDA data and the user's own custom
ingredients, under US FDA rules (market `US`).

## Read the recipe first

Before the first search, read the whole recipe: the ingredient table and every step. The
recipe is everything in both. Then send the user one message that covers all of these:

- **Items only in the steps.** Finishing butter, egg wash, dusting flour, a side sauce
  served "in a ramekin" or "serve with", a garnish. Name each one as an addition, with its
  amount, or ask for the amount.
- **Items only in the table** that no step uses. An item is table-only when no step names
  it, even when you can guess where it goes. Name each one as table-only, even when you plan
  to keep it, and ask whether it goes in the dish.
- **Names that differ.** "Chicken slice" in the table and "chicken pieces" in a step are one
  item. Say that you read them as one.
- **Alternatives.** "Rice or fries", "chicken or beef", "selected add-on", "choice of" are
  options, not additions. Never add the options together. Propose one recipe per guest
  choice, or ask which one to label.
- **Amounts that differ** between the table and the steps. Use the table amount and say so.
  Ask only when the difference matters (see "Go ahead, ask, or step away").
- **Household units** ("1 scoop", "6 shakes", "150 ml" of a sauce). Convert them with
  `convert_ingredient_amounts_to_grams`, or state the weight you used and why.
- **House-made items named like a generic food** ("garlic butter blend", "house seasoning
  salt"). They are not plain butter or plain salt. Ask for the house recipe or the spec
  sheet, or offer to make a custom ingredient (`references/custom-ingredients.md`). Use the
  generic food only when the user says so, and say that you did.
- **Raw or cooked** for every line (next section).

One message, not one question per line. When an item needs the user's answer (an item
only in the steps or only in the table, a garnish with no amount, alternatives, a
house-made item, or a raw or cooked state the steps do not settle), send the message and
wait for the reply before you save. Ask only about the items that need an answer; state
everything else as a default with its size, and do not ask to confirm it. States the steps settle need no answer: state them and
go ahead. A clean recipe, where the table and the
steps agree, needs no extra questions. Worked examples are in `references/reading-a-recipe.md`.

## Raw or cooked

Decide for each line from what the steps do with it, then search for that state.

- **Weighed, then cooked in the dish** (chicken grilled to order, rice simmered in the pot):
  raw. Use the raw food.
- **Weighed after cooking** (rice scooped from a warmer, beans ladled from a pot; "cooked penne
  230g"): cooked. Search "rice, cooked", not "rice". A portioned grain is a cooked weight
  even when the recipe never says "cooked".
- **Not said, for grains, pasta, dried beans or meat:** ask.
- **Give the size of the swing** for grains, pasta, dried beans and meat, for the line as
  written: 200 g of cooked rice is about 260 kcal, and the same 200 g matched as raw rice is
  about 730 (USDA: about 365 kcal per 100 g raw, 130 cooked). Cooked chicken breast entered
  as raw loses about a quarter.
- **A dry product the user requires, weighed cooked:** keep their product. Convert the
  weight with the ratio of the dry and cooked USDA foods' calories per 100 g
  (`get_ingredient_nutrition_facts`), and show the arithmetic: 230 g cooked penne × 158 /
  371 ≈ 98 g dry. Say the conversion is your arithmetic, and say what the wrong weight
  would do: 230 g of the dry product would overstate the line by about 135% (about 853 kcal
  against 363).
- **One serving is the whole plate or bowl:** set its weight to `reference_weight_grams`
  from `get_recipe_total_nutrition`, the sum of the saved rows. A plated weight that differs
  from that sum scales every number wrongly.
- **Edible part only.** No bones, shells, peels or pits.

Bare words often rank raw or dry foods first. Check that each chosen hit's name says the state
you meant, and say why you chose raw or cooked for each line, with the swing for each
grain, pasta, dried bean or meat line.

## Frying oil and marinade

Count only what stays in the food: the oil it absorbs and the marinade it takes up or is
served with. Oil left in the fryer and marinade poured away are not in the dish. Ask the
user for those weights; weighing the oil before and after frying gives the uptake. Oil
brushed on a pan or plate with no amount: go ahead without it, and say it is not counted.
Absorbed oil is almost pure fat: every 10 g adds about 88 kcal and 10 g of fat. A brush of
oil on a plate is a gram or two.

## Go ahead, ask, or step away

- **Go ahead**, and state the assumption and about how much it moves the panel ("about
  5 kcal"), when it moves the panel a little: salt to taste, a pinch of a dried spice, ml
  read as g for a sauce (say that you assume it is about as dense as water), a small difference between the table and
  the steps. A garnish with no amount is not dropped: name it in the read-back and ask for
  its weight.
- **Ask** before saving or exporting when an unknown could move calories or another
  mandatory nutrient by more than about 20%. FDA's tolerance for calories is 20%
  (21 CFR 101.9(g)(5)). Give the size of the swing in the question.
- **Step away** when these tools cannot give a reliable panel. Say what they cannot do, and
  what would:

| Case | Why these tools cannot | What would |
|---|---|---|
| Deep-fried, oil uptake unknown | Uptake varies widely | Weigh the oil before and after frying, or a lab analysis |
| Cooking loss that matters (a serving set by its cooked weight) | Numbers use raw ingredient weights; no allowance for water lost | A lab analysis, or a serving set as a share of the raw batch |
| Dual-column label (`us.dual_column_not_supported`) | Not supported | Another labeling tool or a regulatory consultant |
| Nutrient content claims ("low fat", "high protein") | Claims are not checked | A regulatory consultant |
| Allergen statement ("Contains: milk") | No allergen data | The user's ingredient specs and a regulatory review |
| Menu labeling (calories on a menu board) | Not covered | The menu labeling rules, or a consultant |
| Labels for other countries | US only | That country's rules |

The user decides. If they still want the label, export it, and state the assumption with
the numbers. Never call a label "FDA compliant" or "FDA approved".

## A recipe the user pasted → a label

1. `find_saved_recipes` by name; if one matches, ask before creating a duplicate. Read the
   recipe first (above).
2. `search_ingredients_for_nutrition`: every ingredient in one call (up to 20
   `queries`, each with its `position`), with its state in the query. Custom
   ingredients rank above standard USDA ones. When a custom ingredient is the same food as
   the line, use it without asking, say which one you used, and offer the USDA food after
   you save. A brand the recipe does not name, or fewer nutrients than the USDA food, is not
   a reason to ask or to switch: name any mandatory nutrients it lacks, which the export
   will ask the user to confirm. A custom
   ingredient that only shares a word with the line (almond butter for "butter") is not a
   match; a brand or variety in its name ("wildflower honey") does not make it a different
   food. Ask only when two close matches would move calories or another mandatory
   nutrient by more than about 20%.
3. `convert_ingredient_amounts_to_grams`: every amount in one call. It does not create
   or change a recipe; an estimated weight (`allow_estimation`) uses a language model and
   plan credits. `needs_resolution` means no exact conversion: estimate the weight
   yourself, call again with `allow_estimation: true` when its `resolve_options` offers
   that, or ask the user for the weight. Show each estimate with its reasoning so the user
   can correct it: your own arithmetic written out, or for a `system_estimate` its
   `gram_weight.estimate.explanation` with the `low_grams` to `high_grams` range. Put them
   all in one message rather than one question per ingredient; a weight the user gives
   replaces any estimate.
4. Per-serving numbers and a label are computed for a **saved** recipe, so ask before
   saving: `create_recipe_for_nutrition_label`, `set_recipe_ingredients`, then
   `add_recipe_serving_size` with the yield ("makes 8 bars"); for a US label choose
   `racc_guided` first (`find_fda_serving_size_category`), and `user_provided` only when no
   category fits. The `demographic` behind %DV, the version token each write needs and what
   to send for a resolved weight are in `references/saving-a-recipe.md`. Per-serving
   numbers come from the raw ingredient weights, with no allowance for water lost in
   cooking; for a cooked or baked food, say so once with the numbers.
5. Added Sugars: `get_recipe_added_sugars`, ask the user about each open row, save their
   answers with `patch_recipe_added_sugars_rows`, show them the report, and call
   `confirm_recipe_added_sugars` with its `report_hash` only when they tell you to. Until
   it is confirmed the label prints no Added Sugars line.
6. `get_recipe_nutrition_facts_per_serving` for the numbers,
   `get_recipe_nutrition_facts_label` for the label (its `readiness` and `findings` show
   what would stop an export), `get_recipe_total_nutrition` for the batch,
   `export_nutrition_facts_label_file` for a file (output may carry a DRAFT watermark
   depending on the account's plan, which is managed in BetterMenu Studio; give the user
   the `download_url`).

Without a save you can still give per-ingredient nutrition and gram weights, and say that
those are ingredient figures, not a label.

## A recipe link

BetterMenu does not fetch URLs; it takes ingredient lines, so follow the steps above with
the page's content. When you cannot read the page (JavaScript-rendered, paywalled, blocked), ask
the user to paste the ingredients rather than working from the URL's wording.

Take the recipe's name, its ingredient lines and its yield. The page's other details, such
as prep and cook times, are not ingredients.

Ask for the yield if the page gives none, and say which yield you used when you give the
numbers: per-serving numbers computed against a guessed serving count are wrong in a way no
later check catches.

When the page lists nutrition of its own and you compute numbers here, show where the two
differ rather than quietly replacing one with the other.

## One food, or two compared

`search_ingredients_for_nutrition`, then `get_ingredient_nutrition_facts`; branded and
packaged products are in there. Standard foods are `per_100g`, with `portions` giving
household weights (a medium apple, 182 g), so scale by `gram_weight` / 100; a custom
ingredient is `per_reference_serving`. Compare two foods at the same amount, converting
when their `basis` differs.

## Grams for an amount

`search_ingredients_for_nutrition` for the food, then
`convert_ingredient_amounts_to_grams` with the quantity and unit ("2 cups", "1 tbsp").

## Daily Values and serving sizes

`get_fda_daily_value` for one nutrient, `list_fda_daily_values` for the table
(21 CFR 101.9); both need a `demographic`. `find_fda_serving_size_category` for the FDA
reference amount (RACC) behind a food type's label serving size,
`get_fda_serving_size_category` by id, `list_fda_serving_size_categories` for all.

## Saved recipes and custom ingredients

`find_saved_recipes` by name, `list_saved_recipes` to browse. From a recipe id:
`get_recipe_ingredients`, and `list_recipe_serving_sizes` for the `serving_id` every
per-serving, label and export tool needs plus the current `version_id`. Change one with
`set_recipe_ingredients`, `update_recipe_serving_size` or `add_recipe_serving_size`.

For the user's own ingredients (`list_custom_ingredients`, `get_custom_ingredient`,
`create_custom_ingredient`, `confirm_custom_ingredient`), see
`references/custom-ingredients.md`: a panel's amounts are per `reference_quantity_g`
grams, and without that weight the ingredient adds nothing to a recipe.

## Managing saved work

Each write needs the current `version_id` (from `get_recipe`, `get_custom_ingredient` or the last change).

- **Put aside or bring back:** `archive_recipe` and `archive_custom_ingredient` keep the
  history and can be undone with `unarchive_recipe` and `unarchive_custom_ingredient`.
  Before archiving an ingredient, `get_ingredient_usage` shows which recipes use it.
- **Delete:** `delete_recipe` is permanent; `delete_custom_ingredient` works only on a draft
  that was never confirmed and that no recipe uses; `delete_recipe_serving_size` removes one
  serving. Ask before any of them.
- **History:** `list_recipe_versions`, `get_recipe_version_changes` and
  `get_recipe_audit_trail` (and the custom-ingredient equivalents `list_custom_ingredient_versions`,
  `get_custom_ingredient_version`, `get_custom_ingredient_version_changes`,
  `get_custom_ingredient_audit_trail`) answer what changed, who changed it and when.
  `restore_recipe_version` and `restore_custom_ingredient_version` put the whole item back to
  that version and drop what was added after it, so show the user the changes and ask first.
- **Label settings:** `get_nutrition_label_settings` shows which nutrients the label prints;
  `reset_nutrition_label_settings` removes every custom setting.
- **Why a number is what it is:** `get_recipe_nutrition_analysis` (which ingredients drive
  a nutrient), `get_recipe_serving_nutrition_analysis` (rounding and %DV for one serving),
  `get_recipe_nutrition_facts_per_container` (the whole package), `get_recipe_serving_size`
  (one serving's detail), `list_ingredients_used_in_recipes` (what the organization uses most).

## Before the user prints

- Say when a gram weight is an estimate (`system_estimate`), and when a number came from
  your own arithmetic rather than these tools. An estimate the user never confirmed is
  still an estimate at the moment it reaches a printed label, so name it again there.
- `completeness.is_complete` false: name the `missing_mandatory` nutrients and say the
  label must not be used until they are filled in.
- Read `readiness.findings` and `findings` on the label before exporting. A blocking
  finding needs a data fix. A stated zero (`review: true`) is the user's to confirm,
  through `set_nutrition_label_settings` with `acknowledged_fills`. `us.sold_individually_unknown`
  means asking the user whether the product is sold individually and resending the
  `racc_guided` size with `sold_individually`. `us.dual_column_not_supported` cannot be
  resolved here; say so, and do not switch to a manual size to get past it. Offer
  `acknowledged_findings_hash` only when the user declines to confirm Added Sugars, and say
  the label will then lack that line. Never confirm or acknowledge for the user.
- `staleness.is_current` false: the numbers predate the last change to the ingredients or
  the serving, so they need recomputing first: resend the same serving with
  `update_recipe_serving_size`, or the ingredients with `set_recipe_ingredients`.

- Repeat any assumption the user has not confirmed (an item left out, an amount read from
  the table, oil not counted) when you hand over the label.

## Outside these tools

Inventing a recipe, cooking advice, substitutions, meal plans, whether a food is healthy,
non-US labelling rules, and the cases under "Step away" above. The Daily Value tools return reference amounts, not a definition
of what %DV means.

Referenced files: 3 — file references are metadata, not package contents.