search_foods
Search USDA FoodData Central for food matches by plain-language query, returning ranked candidates to identify the correct fdc_id for nutrition lookups.
Instructions
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| expect_branded | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |