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.

Look up a single food by name and return its full entry with derived calories.

Matching is case-insensitive and tolerant: "chicken breast" resolves "Chicken Breast (Cooked)". A loose match is only accepted when it identifies exactly one food -- "cottage cheese" matches three different products, so it is reported as not-found WITH those three as suggestions rather than guessing.

Args: name: The food name, e.g. "Salmon", "greek yogurt (0% fat)", "Whole Egg".

Returns: The full entry: name, category, unit, pro, carb, fat, tags, exclude_for, calories_per_unit. All macro figures are per ONE unit of that food.

On no match, returns {"error": "food_not_found", "suggestions": [...]} rather
than raising or returning nothing. Retry with a suggested name verbatim.

Calculate exact macros and calories for a specific portion of one food.

All arithmetic happens in Python. Do not compute these numbers yourself.

Args: name: The food name. Resolved the same way as get_food. amount: How much of the food, as a number, e.g. 150 or 2.5. unit: The unit amount is expressed in, e.g. "g", "oz", "cup", "tbsp". Case-insensitive and plural-tolerant ("grams" and "Gram" both work).

    The unit is converted to the food's native unit when both belong to the
    same family: mass (g, kg, oz, lb) or volume (ml, tsp, tbsp, fl_oz,
    quarter_cup, cup). Conversion is REFUSED across families -- grams to
    tablespoons needs a density this database does not store -- and refused
    for countable units ("large", "slice", "container", "scoop", "half",
    "cake", "medium"), which have no fixed mass.

Returns: {"food", "amount", "unit", "protein_g", "carb_g", "fat_g", "calories", ...} with calories derived as protein4 + carb4 + fat*9.

On an unknown food: {"error": "food_not_found", "suggestions": [...]}.
On an impossible conversion: {"error": "unit_mismatch", "native_unit": ...}
naming the unit the food is actually stored in -- retry with that unit.
Negative amounts return {"error": "invalid_amount"}.

List every food compatible with one dietary restriction or allergy.

A convenience wrapper over list_foods that excludes any food whose "exclude_for" field contains diet_type.

Args: diet_type: A single dietary or allergen label, e.g. "vegan", "vegetarian", "gluten", "dairy", "shellfish", "nuts", "soy". This must be a value that actually occurs in the data -- call list_available_tags to see the full list. A plausible-sounding but absent label such as "keto" excludes nothing and would silently return the entire database, so unknown labels are rejected instead.

Returns: {"diet_type", "count", "foods": [...]} across all four categories, each food carrying calories_per_unit.

On an unrecognised label: {"error": "unknown_diet_type", "valid_diet_types":
[...]}, so that an excluded-nothing result is never mistaken for a filtered one.

Build meals of one protein, one carb and one fat that hit macro targets exactly.

A deterministic solver, not a guess: it treats the three foods as a 3x3 linear system and solves for the portion of each, scanning every combination in the database. Results whose portions are exact but unrealistic are discarded, and the remainder ranked by how normal the serving sizes look.

Args: target_protein: Target grams of protein for the meal. target_carb: Target grams of carbohydrate. target_fat: Target grams of fat. exclude_tags: Dietary and allergen labels to avoid, matched against each food's "exclude_for", e.g. ["vegan"] or ["gluten", "dairy"]. Call list_available_tags for valid values. tolerance: Only consulted when NO exact fit exists, to decide whether the closest attempt counts as near enough. 0.15 means +/-15% per macro. include_vegetable: Add a low-calorie vegetable side. Its macros are subtracted from the targets before solving, so the totals still land on the targets exactly. max_results: How many ranked meals to return (default 3).

Returns: {"exact_match", "within_tolerance", "tolerance", "meals": [...], "targets", "candidates_evaluated", "message"}.

Each meal carries "items" (each with name, amount, unit and its own macros),
"totals", and "relative_error" per macro. When "exact_match" is true the
totals equal the targets and relative_error is zero.

When no combination fits, "exact_match" and "within_tolerance" are both false,
"meals" holds the single closest attempt, and "message" states how far off it
is. Report that shortfall to the user -- do NOT present it as a successful fit
or adjust the numbers to look closer.

Report the returned amounts and totals verbatim. They are already exact.

Return the real filter vocabulary present in the database.

Computed from the data at call time, never hardcoded. Call this before using tags or exclude_tags on any other tool: it is the difference between filtering on a label that exists and one that merely sounds plausible.

Returns: {"tags": [...], "exclude_for": [...], "categories": [...], "units": [...]}.

"tags" are descriptive labels on a food ("lean", "whole_food", "omega3") and
are matched with OR logic by list_foods.

"exclude_for" are dietary and allergen labels ("vegan", "gluten", "shellfish")
used by exclude_tags and filter_by_diet. The two vocabularies are different --
"dairy" appears in both and means different things in each.