list_foods
Search and filter the USDA food database by category, tags, and dietary exclusions. Get macros and derived calories per unit for each food.
Instructions
List foods from the database, with derived calories, optionally filtered.
Args:
category: Restrict to one category. Must be exactly one of "proteins",
"carbs", "fats", "vegetables". Omit to search every category.
tags: Keep a food if it carries AT LEAST ONE of these tags (an OR match, not
AND). Tags are descriptive, e.g. "lean", "whole_food", "high_protein".
Call list_available_tags for the complete real vocabulary.
exclude_tags: Drop a food if ANY of these appear in its "exclude_for" field.
These are dietary and allergen labels, e.g. "vegan", "gluten", "dairy",
"shellfish" -- NOT the same vocabulary as tags.
Returns:
{"count": int, "foods": [...]} where each food carries name, category, unit,
pro, carb, fat, tags, exclude_for and a derived calories_per_unit. Macro
values are per ONE of the food's own unit -- note this varies per food
(grams, ounces, tbsp, "large", "container"). To scale a food to a real
portion, use calculate_macros rather than multiplying yourself.
On an invalid category, returns {"error": "invalid_category", ...} listing
the valid values. An empty "foods" list means the filters genuinely matched
nothing, not that the request was malformed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| category | No | ||
| exclude_tags | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||