Search USDA FoodData Central for candidate foods matching a plain-language query (e.g. "chicken breast", "greek yogurt"). Returns ranked candidates: generic (Foundation, SR Legacy) before branded, always. Raises only if nothing at all matches -- never returns an empty list.

This is the ONLY way to find a valid fdc_id. Never invent, recall, or reuse an fdc_id from memory or an earlier conversation: call this tool first, read the returned descriptions, and choose the one that actually matches what the user meant. Pass this exact query string as query to get_nutrition or get_nutrition_batch so the server can verify your chosen fdc_id was really one of these results. Each candidate carries a source field ("usda" or "off") -- pass it through as NutritionRequest.source unchanged; fdc_id itself always goes in the same field either way.

A returned candidate can still fail to fetch (USDA's own search index can be ahead of its detail records, especially for newer Foundation entries) -- if get_nutrition/get_nutrition_batch reports that id as failed, do not give up: try the next candidate from this same list. A failed fetch on its own is not evidence the food itself doesn't exist.

Open Food Facts fallback: set expect_branded=True when the ingredient names or clearly implies a specific commercial product (a brand name, "Mission Carb Balance," "Nature's Own keto bun," or a stated attribute like "low-carb"/"keto" you suspect USDA does not carry under that name) -- the same judgment X-7 already asks you to make about when to search using a stated attribute, extended one step further. When set, this also searches Open Food Facts (a free, crowdsourced, barcode-indexed database) and reserves a slice of limit for any candidate that passes a real plausibility gate (no impossible or self-contradictory nutrition values) -- still fundamentally less trustworthy than a USDA record, anyone can edit an entry, and get_nutrition always attaches a caveat naming this plainly. Leave it False (the default) for a plainly generic ingredient (eggs, potato, olive oil, chicken breast) -- Open Food Facts is a packaged-goods database and has nothing to offer a commodity food, so trying it there is pure latency with no upside. USDA alone is still searched every time regardless of this flag, and Open Food Facts is still tried as a last resort if USDA returns literally nothing even when this flag is False, so a real zero- result case is never silently unhandled just because you forgot to set it.

Get verified macros (kcal, protein, carbs, fat) for one ingredient at one quantity. fdc_id must come from a prior search_foods call -- never guess one. amount accepts grams/kg, oz/lb, or a count phrase like "1 medium onion" (the server resolves counts through a cited chain of real sources; it will raise rather than guess if it cannot). label is the user's own word for this ingredient, written verbatim -- do not paraphrase or clean it up, it is used to judge how confident this match is. query should be a search string that actually returns fdc_id among its results -- the server re-runs it and checks. This catches an ID invented from memory; it does not confirm query is the search you actually used, only that fdc_id is findable through it right now.

Open Food Facts fallback: set source to whatever search_foods returned for the candidate you chose ("usda", the default, or "off"). For "off", fdc_id holds the Open Food Facts barcode search_foods already gave you, query is not consulted (no re-verification exists yet for this source), and count-phrase quantities only resolve if the product itself states a serving size -- otherwise give an explicit mass (grams/oz). The response always carries a caveat naming this a crowdsourced, not USDA, source.

The response always includes a summary, a report_path, and totals (the plate sum, computed server-side, even for one item and even with no target -- never add it up yourself). Read the summary in full and relay every flagged item to the user, not just the confirmed ones -- a caveat you drop silently (a low-confidence match, an assumed mass) defeats the only safety mechanism this tool has. A macro genuinely absent from a food (no protein data at all, for example) comes back as null with a caveat naming it, never as zero -- zero means the food truly has none.

The macros this tool returns are the only ones to state as fact for a food it matched -- never invent or estimate your own number in their place. The one narrow exception: if search_foods finds nothing at all for an item, you may estimate that single item's nutrition instead of leaving it out, but only if you say plainly it is your own guess, not verified data (C-28).

Pass target if the user has a kcal/protein/carb/fat goal for this lookup; use the returned totals.outcomes, never compute whether a target was met yourself.

Same as get_nutrition, for multiple ingredients in one call -- use this instead of calling get_nutrition in a loop, it is far faster to iterate on a recipe with. One bad item does not fail the batch: a failed lookup comes back as a marked failure alongside the successful ones, in the same order as reqs.

Read the whole summary before presenting results to the user: it names every item that needed judgment, not just the ones that failed outright. Burying three flagged items under eleven confirmed ones and only mentioning the confirmed ones is the single most damaging way to misuse this tool. A macro absent from one ingredient (no protein data at all, for example) comes back null with a caveat naming it, not zero, and makes that macro's plate total totals.macros come back null too -- reported as incomplete, not silently summed as though the absent ingredient contributed nothing.

totals (the plate sum) is always computed server-side, whether or not you pass target -- never add up the plate's macros yourself, even for a bare "what does this plate total" question. Pass target once for the whole plate to also get totals.outcomes, the per-macro met/not-met judgment; without one, every macro's outcome reads "no target" and only the sum is judged.

Permanently correct what a phrase means or what a count weighs, for this user. Use this the moment a lookup's summary flags something as wrong or low-confidence and the user tells you the right answer -- that correction is the entire point of reading the summary in the first place.

Pass fdc_id to fix which food a phrase resolves to, grams to fix what a count weighs, or both. At least one is required. You cannot supply your own description of the food: the server fetches the real USDA description and writes that, so a bad correction is caught immediately rather than saved blind.

When correcting grams, phrase must be the exact count phrase you would pass as amount to get_nutrition (e.g. "1 medium onion"), not just the ingredient's name (e.g. "onion") -- masses are looked up by that phrase, and a mass saved under the wrong key is never found again.

Every future lookup of this phrase short-circuits to this correction at high confidence. note should say why, briefly -- it is the only record of that later.

Save a new version of a recipe. plate is the user's own plate only, in absolute grams per ingredient -- never a household total. Each ingredient needs an fdc_id from a real lookup (never invent one) and its exact amount in grams. shares records everyone else at the table as a fraction of the user's plate (e.g. {"maria": 0.75}) -- leave it empty if cooking just for the user, that is the common case, not a special one.

Saves are append-only: this always creates a new version, it never overwrites one. notes is required and should say what changed and why (e.g. "corrected cooked weight after weighing it") -- it is the only record of that later, and the most useful field in the whole store.

Fetch a saved recipe. Omit version for the latest. Macros are computed fresh from the stored plate on every call, never cached -- if this ever disagrees with something said earlier in the conversation, the plate or the underlying food data changed since then; trust this call.

Fetch every saved version of a recipe, in order, to see how it evolved and why -- each version's notes explains what changed. Use this before assuming a recipe's current numbers are the only numbers it ever had.

List saved recipes, optionally filtered by protein range, calorie range, or whether a given fdc_id appears as an ingredient. Filters run against each recipe's current plate, computed fresh on read.