Get USDA Food
usda_get_foodGet the full nutrient profile for one food by FDC ID. Returns all available nutrients (or a filtered subset via the nutrients[] param) with optional per-portion scaling. Use usda_search_foods to discover FDC IDs. Values are per 100 g (basisUnit "g"), except Branded foods FDC reports per 100 ml (basisUnit "ml") or per 100 of a label unit that fixes neither (basisUnit absent, basis unverified). Provide unit, optionally with quantity, to scale all nutrient values from that basis to that amount (e.g. quantity=200, unit="g" → per-200g values); a mass unit is applied to an ml or label-unit basis without conversion, and a notice says so. quantity defaults to 100 for g, oz, lb, and kg and to 1 for serving. Serving uses the valid portion FDC displays first (lowest sequenceNumber), or a positive finite Branded label size in g/GRM/GM (case-insensitive) when no portion exists; quantity multiplies that weight. A label in any other unit sets the basis rather than a serving weight, so it requires an explicit mass-unit request. quantity without unit is rejected. Narrow nutrients[] to specific IDs to reduce response size for focused queries. Set provenance=true to add to each nutrient how FDC obtained its value (derivation code, description, and source), its sample count (dataPoints), and the sample min, max, and median scaled with amount, each only where FDC sends it.
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": {
"fdcId": "<fdcId>"
},
"name": "usda_get_food"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| unit | No | Unit for quantity. "serving" uses the weight of the valid portion FDC displays first (lowest sequenceNumber), or a Branded label size in g/GRM/GM (case-insensitive) when no portion exists, multiplied by quantity. Required when quantity is provided. Given alone, scales to 100 g, oz, lb, or kg, or to 1 serving. | |
| fdcId | Yes | FDC ID of the food. Use usda_search_foods to discover IDs. | |
| quantity | No | Amount of food, in unit, to scale nutrient values to. Must be positive. Requires unit. Defaults to 100 when unit is g, oz, lb, or kg, and to 1 when unit is "serving". Omit both quantity and unit for the per-100 values FDC reports (per 100 g, or per 100 ml when basisUnit is "ml"). | |
| nutrients | No | Filter to specific nutrient IDs (e.g. [1003, 1004, 1005, 1008] for protein, fat, carbs, energy). Use usda_list_nutrients to look up IDs. Omit to return all available nutrients. Requested IDs the food does not report are listed in missingNutrients. | |
| provenance | No | Add to each nutrient what FDC records about its value: derivation (code, description, source), dataPoints (sample count), and min, max, median (sample spread, scaled with amount). Each is present only where FDC sends it: Survey (FNDDS) foods send none, Branded foods only a derivation. Off by default; it makes the response two to three times as large. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| fdcId | No | FDC ID of the food. | |
| notice | No | Basis caveat when a food not reported per 100 g is scaled: the resolved amount was applied to its per-100 ml or unverified label-unit basis without conversion. | |
| gtinUpc | No | GTIN/UPC barcode as FDC stores it, leading zeros kept (e.g. "011110044174"). Branded items only. | |
| dataType | No | FDC data source: SR Legacy, Foundation, Survey (FNDDS), or Branded. | |
| scaledTo | No | Scaling basis when unit was provided. Absent when returning per-100 values. | |
| basisUnit | No | What the per-100 nutrient values are measured in: "g" for every non-Branded food and for Branded labels in g/GRM/GM, "ml" for Branded labels in ml/MLT. Absent when the label unit (e.g. IU, MG) fixes neither, so the basis is unverified. | |
| brandName | No | Brand name. Branded items only. | |
| nutrients | No | Nutrient values for this food, per 100 of basisUnit or scaled to the scaledTo basis. | |
| brandOwner | No | Brand owner. Branded items only. | |
| allPortions | No | All named portions for this food, in FDC's display order: ascending sequenceNumber, ties as FDC lists them, unnumbered portions last. | |
| description | No | Full USDA food name (e.g. "Chicken, broilers or fryers, breast, meat only, raw"). | |
| ingredients | No | Ingredient list from label. Branded items only. | |
| servingInfo | No | The portion one serving weighs: the first of allPortions (the one FDC displays first), or, when the food has no portion, a Branded gram-label serving identified in its description. | |
| servingSize | No | Serving size from the product label, in servingSizeUnit. Branded items only. | |
| foodCategory | No | USDA food category (e.g. "Poultry Products"): the food category for SR Legacy and Foundation, the label category for Branded, the WWEIA category for Survey (FNDDS). Absent when FDC reports none. | |
| publicationDate | No | Date this food entry was published in FDC, as YYYY-MM-DD (e.g. "2019-04-01"). A date FDC sends in another form is returned as sent. | |
| servingSizeUnit | No | Unit for servingSize as FDC reports it (e.g. "GRM", "MLT", "IU"); it sets basisUnit. Branded items only. | |
| missingNutrients | No | Requested nutrient IDs this food's profile does not report, deduplicated, in request order. Absent when nutrients[] was omitted or every requested ID is present. | |
| householdServingFullText | No | Serving as the label words it (e.g. "1 cup"). Branded items only. |