Compare USDA Foods
usda_compare_foodsCompare nutrients side-by-side for 2–5 foods. Returns a structured table — one row per nutrient, one column per food — formatted as markdown. Best for "spinach vs kale iron" or "which has more protein?" questions. Accepts up to 500 FDC IDs: repeats are dropped, the first 5 distinct IDs are compared, and the rest are returned in deferredIds without being requested from FDC, with a notice naming the follow-up call. Omit nutrients[] to use the 12 most common defaults (energy, protein, fat, saturated fat, carbs, fiber, sugars, sodium, potassium, calcium, iron, vitamin C); a food that lacks the default energy (1008) or total sugars (2000) value has that cell filled from its equivalent nutrient — energy from 2048, then 2047; sugars from 1063 — and each fill is listed in substitutions. Provide nutrients[] with specific FDC IDs to compare different nutrients; an explicit list is compared as given, repeats dropped, without fills. All values are scaled to the same basis, quantity in unit: default 100 g, so unit="oz" alone compares per 100 oz and quantity alone is grams. A Branded food FDC reports per 100 ml (basisUnit "ml") or per 100 of a label unit that fixes neither (basisUnit absent) is compared on that basis without conversion, and a notice names it. If one or more FDC IDs are not found, the comparison proceeds with the valid foods — only throws too_few_foods when fdcIds holds fewer than 2 distinct IDs or fewer than 2 of the compared IDs return data. IDs FDC does not return before the call's deadline (slow Foundation records, most often) or keeps failing on are left out, listed in deferredIds ahead of any past the first 5, and named in a notice; when that leaves fewer than 2 foods, the call fails with retry_deadline_exceeded instead, or with too_few_foods when even answers for those IDs could not make 2 foods.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"fdcIds": "<fdcIds>"
},
"name": "usda_compare_foods"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| unit | No | Unit for quantity. Default "g". Does not support "serving" (each food's portion weight differs, so a serving basis would not compare equal amounts). | g |
| fdcIds | Yes | FDC IDs to compare — 2 to 500 entries (a server configured with strict limits rejects more than 5). Repeats are dropped; the first 5 distinct IDs are compared and the rest are returned in deferredIds. Use usda_search_foods to discover IDs. | |
| quantity | No | Amount of food, in unit, that every value is scaled to. Must be positive. Default 100. | |
| nutrients | No | Nutrient IDs to include in the comparison. Defaults to the 12 most common: energy (1008), protein (1003), total fat (1004), saturated fat (1258), carbohydrate (1005), fiber (1079), total sugars (2000), sodium (1093), potassium (1092), calcium (1087), iron (1089), vitamin C (1162). Under the defaults, a food missing energy or total sugars has that cell filled from its equivalent nutrient (listed in substitutions); IDs given here are compared as given, repeats dropped. Use usda_list_nutrients to look up other IDs. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| basis | No | The common scaling basis applied to all nutrient values. | |
| error | No | Present when the call failed. Absent on success. | |
| foods | No | The compared foods, in the same order as the values arrays below. | |
| notice | No | Present when deferredIds is, or a compared food is not reported per 100 g. First, how many distinct IDs past the first 5 were not requested, which of the first 5 FDC did not return before the deadline or kept failing on, and the call that fetches them; then the basis caveat naming each food not per 100 g: an ml food compared per basis.gramWeight millilitres, or a food whose per-100 basis is unverified, both without conversion. | |
| nutrients | No | Nutrient rows — one entry per requested nutrient, with per-food values in the values[] array. | |
| deferredIds | No | Distinct requested IDs this call did not compare, in request order: any of the first 5 FDC did not return before the call's deadline or kept failing on, then those past the first 5, which were never requested from FDC. The comparison leaves them out: they appear in neither foods nor missingData. Call usda_compare_foods with them and the same nutrients, quantity, and unit (pair a single one with an ID already compared), or fetch an unanswered one with usda_get_food. Absent when every distinct ID was requested and FDC answered each one. | |
| missingData | No | Foods or food+nutrient pairs where data was unavailable. A cell filled from an equivalent nutrient is listed in substitutions, not here. Absent when all data was present. | |
| substitutions | No | Default-row cells filled from an equivalent nutrient because the food does not report the row ID, in nutrients[] then foods[] order. Absent when nothing was filled. |