MCP server exposing a USDA-accurate food database with deterministic macro math — no hallucinated nutrition numbers.
Strong tool definitions with comprehensive descriptions (avg 250+ chars), well-structured JSON schemas with types and descriptions for all parameters, and explicit error handling guidance. All 6 tools follow verb_noun naming (list_, get_, calculate_, filter_, build_, list_). Descriptions clearly state WHAT the tool does, WHEN to use it, and what it returns. Parameters are well-constrained (enums for category, clear ranges for numeric inputs). Error responses include recovery hints ('Call list_available_tags', 'Retry with a suggested name verbatim'). Minor gaps: no tool annotations (readOnlyHint/destructiveHint), no pagination support for list_foods (could return 100+ items), and output schemas documented in prose rather than formal JSON Schema. All tools are READ_ONLY and safe to retry.
Build meals of one protein, one carb and one fat that hit macro targets exactly. A deterministic solver: given three macro targets, it finds every combination of one food from each category that solves the 3x3 linear system exactly, ranks them by portion plausibility, and returns the top results. When no exact fit exists, it returns the closest attempt and says so explicitly. Args: target_protein: grams of protein the meal should supply. target_carb: grams of carbohydrate. target_fat: grams of fat. exclude_tags: drop any food whose ``exclude_for`` contains one of these (e.g. ``["vegan"]``, ``["gluten", "dairy"]``). tolerance: only used when no exact fit exists, to judge whether the closest attempt is worth calling a near-miss. ``0.15`` means +/-15% per macro. include_vegetable: add a low-calorie vegetable, subtracting its macros from the targets before solving so the fit stays exact. max_results: how many ranked meals to return. Returns: A dict with ``exact_match``, ``within_tolerance``, ``meals`` (each carrying its items, totals and per-macro relative error), a human-readable ``message``, and ``candidates_evaluated``. When nothing fits, ``meals`` holds the closest attempt and both boolean flags are ``False``. Raises: ValueError: if any target is negative, all three targets are zero, or ``max_results`` is below 1.
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 protein*4 + carb*4 + 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"}.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) declared. All 6 tools are READ_ONLY and idempotent, but this is not formally signaled to clients.
list_foods lacks pagination (limit/offset/page_size parameters). Could return 100+ foods, exhausting context window. No documented result cap.
Output schemas documented in prose docstrings, not formal JSON Schema. LLMs cannot parse prose descriptions to infer response structure for downstream planning.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 65 | 2026-07-28+ | v2 |
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.
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.
List every tag and dietary-exclusion label that appears in the database. Returns: {"tags": [...], "exclude_for": [...]}, two separate vocabularies. ``tags`` are descriptive ("lean", "whole_food", "high_protein"), while ``exclude_for`` are dietary and allergen labels ("vegan", "gluten", "dairy", "shellfish"). Both are sorted and deduplicated.
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.
build_meal raises ValueError for invalid inputs (negative targets, all-zero targets, max_results < 1) instead of returning structured error payloads. Inconsistent with other tools' error handling pattern.
No batch variants for tools agents might call in loops. If an agent needs macros for 10 foods, it must call calculate_macros 10 times instead of one batch call.